strokes
Class StrokeShortcuts

java.lang.Object
  java.awt.event.WindowAdapter
      strokes.StrokeShortcuts

All Implemented Interfaces:

java.awt.event.WindowFocusListener, java.awt.event.WindowListener, java.awt.event.WindowStateListener, java.util.EventListener

public class StrokeShortcuts
extends java.awt.event.WindowAdapter

A stroke shortcuts manager used to register:

1. The windows containing the accessible commands for which shortcuts are defined,
2. The mappings (command, stroke),
3. The 'strokable' components, i.e. the graphical components that must interpret a press-drag-release as a stroke.

A stroke shortcuts manager has an underlying shape matching classifier. Each time, the user inputs a stroke on a strokable component, the manager invokes the command corresponding to this stroke if exists.

A stroke shortcuts manager can implement several visual clues for available stroke shortcuts: Strokes Sheet, Menu Preview and Tooltip. For more information about these features, see the StrokeShortcuts' tutorial.

StrokeListeners or StateMachine can be attached to this manager to be notified each time a stroke event occurs: a stroke begins, a point is added to a stroke, a stroke ends as a shortcut, a stroke ends as a command or a stroke ends as non recognized.

Author:

Caroline Appert

See Also:

strokes.listeners, strokes.transitions

Constructor Summary

StrokeShortcuts()
Builds a strokes shortcuts manager.

Method Summary

void	addShortcut(java.lang.String actionName, java.util.Vector<java.awt.geom.Point2D> stroke, boolean inline, boolean tooltip) Registers a new stroke shortcut in this strokes shortcuts manager.
void	addShortcuts(java.io.File recognizer, boolean inline, boolean tooltip) Registers a set of stroke shortcuts contained in a shape matching classifier in this strokes shortcuts manager.
void	addShortcuts(fr.lri.swingstates.gestures.shapeMatching.ShapeMatchingClassifier recognizer, boolean inline, boolean tooltip) Registers a set of stroke shortcuts contained in a shape matching classifier in this strokes shortcuts manager.
void	addShortcuts(java.lang.String recognizerFile, boolean inline, boolean tooltip) Registers a set of stroke shortcuts contained in a shape matching classifier in this strokes shortcuts manager.
void	addStrokeListener(fr.lri.swingstates.sm.StateMachine stateMachine) Adds a state machine to this strokes shortcuts manager so this state machine will be notified each time: a stroke begins, a new point is added to a stroke, a stroke ends and has been recognized, a stroke ends but has not been recognized.
void	addStrokeListener(StrokeListener strokeListener) Adds a StrokeListener to this strokes shortcuts manager so this listener will be notified each time: a stroke begins, a new point is added to a stroke, a stroke ends and has been recognized, a stroke ends but has not been recognized.
void	addWindow(java.awt.Window window) Registers a window in this strokes shortcuts manager.
java.lang.String	classify(fr.lri.swingstates.gestures.Gesture gesture) Return the command name that minimizes the distance to an input stroke within the set of stroke templates registered in this strokes shortcuts manager.
void	disableStrokes(java.awt.Component strokableComponent) Disables stroke recognition for strokes started on a given component.
void	disableStrokes(java.awt.Component strokableComponent, boolean hierarchy) Disables stroke recognition for strokes started on a given component.
void	enableStrokes(java.awt.Component strokableComponent, boolean hierarchy, boolean drawInkOnGlassPane) Registers a component to enable stroke when a drag interaction starts on it.
void	enableStrokes(java.awt.Component strokableComponent, boolean hierarchy, boolean drawInkOnGlassPane, Criterion criterion) Registers a component to enable stroke when a drag interaction starts on when a given criterion is verified.
void	enableStrokesSheet() Enables the strokes sheet: when pausing for 300 milliseconds while tracing a strokes, the strokes sheet pops up close to the mouse cursor.
fr.lri.swingstates.gestures.shapeMatching.ShapeMatchingClassifier	getClassifier()
Criterion	getCriterion(javax.swing.JComponent component)
StrokeIcon	getIcon(java.lang.String command, int width, int height) Creates a StrokeIcon of a stroke given its command name.
StrokeIcon	getIcon(java.lang.String command, int width, int height, java.awt.Color colorStroke, int sizeStartingPoint, java.awt.Color colorStartingPoint) Creates a StrokeIcon of a stroke given its command name.
java.awt.Color	getInkColorWhenNonRecognized() In case of bad recognition, the stroke will stay displayed for 200 milliseconds in a this color.
java.awt.Color	getInkColorWhileBeautifying() In case of good recognition, the stroke will be beautified to match its template stroke.
java.awt.Color	getInkColorWhileStroking()
fr.lri.swingstates.canvas.CPolyLine	getInkTrail()
int	getMinimumStrokeLength()
void	getPngImage(java.io.File file, java.lang.String command, int sideSizeImage, java.awt.Color colorStroke, int sizeStartingPoint, java.awt.Color colorStartingPoint) Creates a squared png image of a stroke given its command name.
void	getPngImage(java.io.File file, java.lang.String command, int sideSizeImage, int sizeStartingPoint) Creates a squared png image of a stroke given its command name.
fr.lri.swingstates.canvas.CEllipse	getStartingPoint()
java.awt.Color	getStartPointColor()
double	getThreshold()
static boolean	invokeAccessibleAction(javax.accessibility.Accessible accessible, java.lang.String actionName) Looks for the first occurrence of a named action in the hierarchy of an Accessible component.
boolean	invokeCommand(java.lang.String accessibleAction) Invokes an accessible action
boolean	isStrokable(java.awt.Component c)
void	removeStrokeListener(fr.lri.swingstates.sm.StateMachine stateMachine) Adds a state machine from this strokes shortcuts manager.
void	removeStrokeListener(StrokeListener strokeListener) Removes a listener from this strokes shortcuts manager.
boolean	setCriterion(java.awt.Component component, Criterion criterion) Sets the criterion for one component that is already registered in this strokes shortcuts manager.
void	setInkColorWhenNonRecognized(java.awt.Color inkColorWhenNonRecognized) In case of bad recognition, the stroke will stay displayed for 200 milliseconds in a this color.
void	setInkColorWhileBeautifying(java.awt.Color inkColorWhileBeautifying) In case of good recognition, the stroke will be beautified to match its template stroke.
void	setInkColorWhileStroking(java.awt.Color inkColorWhileStroking)
void	setMinimumStrokeLength(int minimumStrokeLength)
void	setStartPointColor(java.awt.Color startPointColor)
void	setThreshold(double maximumDistance)
void	windowGainedFocus(java.awt.event.WindowEvent e)

Methods inherited from class java.awt.event.WindowAdapter

windowActivated, windowClosed, windowClosing, windowDeactivated, windowDeiconified, windowIconified, windowLostFocus, windowOpened, windowStateChanged

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

StrokeShortcuts

public StrokeShortcuts()

Builds a strokes shortcuts manager.

Method Detail

addStrokeListener

public void addStrokeListener(StrokeListener strokeListener)

Adds a StrokeListener to this strokes shortcuts manager so this listener will be notified each time:

• a stroke begins,
• a new point is added to a stroke,
• a stroke ends and has been recognized,
• a stroke ends but has not been recognized.

Parameters:

strokeListener - The listener to add

See Also:

StrokeListener, StrokeAdapter

addStrokeListener

public void addStrokeListener(fr.lri.swingstates.sm.StateMachine stateMachine)

Adds a state machine to this strokes shortcuts manager so this state machine will be notified each time:

• a stroke begins,
• a new point is added to a stroke,
• a stroke ends and has been recognized,
• a stroke ends but has not been recognized.

Parameters:

stateMachine - The state machine to add.

See Also:

StrokeBegun, StrokePointAdded, ShortcutRecognized, StrokeNotRecognized

removeStrokeListener

public void removeStrokeListener(StrokeListener strokeListener)

Removes a listener from this strokes shortcuts manager.

Parameters:

strokeListener - The listener to remove

removeStrokeListener

public void removeStrokeListener(fr.lri.swingstates.sm.StateMachine stateMachine)

Adds a state machine from this strokes shortcuts manager.

Parameters:

stateMachine - The state machine to add.

invokeCommand

public boolean invokeCommand(java.lang.String accessibleAction)

Invokes an accessible action

Parameters:

accessibleAction - The name of the accessible action to invoke

Returns:

True if the action has been found in the windows registered in this strokes shortcuts manager and thus invoked.

invokeAccessibleAction

public static boolean invokeAccessibleAction(javax.accessibility.Accessible accessible,
                                             java.lang.String actionName)

Looks for the first occurrence of a named action in the hierarchy of an Accessible component.

Parameters:

accessible - the Accessible component.

actionName - the action name.

Returns:

true if an action has been found and invoked, false otherwise.

addShortcut

public void addShortcut(java.lang.String actionName,
                        java.util.Vector<java.awt.geom.Point2D> stroke,
                        boolean inline,
                        boolean tooltip)

Registers a new stroke shortcut in this strokes shortcuts manager.

Parameters:

actionName - The action to invoke

stroke - The stroke that invokes actionName

inline - True if this stroke shortcut must be displayed beside the menu item that also invokes actionName

tooltip - True if this stroke shortcut must be displayed in the tooltip of components that also invoke actionName

addShortcuts

public void addShortcuts(fr.lri.swingstates.gestures.shapeMatching.ShapeMatchingClassifier recognizer,
                         boolean inline,
                         boolean tooltip)

Registers a set of stroke shortcuts contained in a shape matching classifier in this strokes shortcuts manager. Every (strokeName, stroke) found in the classifier is registered as a stroke shortcut.

Parameters:

recognizer - The shape matching classifier

inline - True if stroke shortcuts must be displayed beside their corresponding menu items

tooltip - True if stroke shortcuts must be displayed in the tooltip of corresponding components

See Also:

addShortcut(String, Vector, boolean, boolean)

addShortcuts

public void addShortcuts(java.io.File recognizer,
                         boolean inline,
                         boolean tooltip)

Registers a set of stroke shortcuts contained in a shape matching classifier in this strokes shortcuts manager. Every (strokeName, stroke) found in the classifier is registered as a stroke shortcut.

Parameters:

recognizer - The file containing the shape matching recognizer definition

inline - True if stroke shortcuts must be displayed beside their corresponding menu items

tooltip - True if stroke shortcuts must be displayed in the tooltip of corresponding components

See Also:

addShortcut(String, Vector, boolean, boolean)

addShortcuts

public void addShortcuts(java.lang.String recognizerFile,
                         boolean inline,
                         boolean tooltip)

Registers a set of stroke shortcuts contained in a shape matching classifier in this strokes shortcuts manager. Every (strokeName, stroke) found in the classifier is registered as a stroke shortcut.
WARNING: The windows that contain the Swing widgets for these commands must have been registered in the stroke shortcuts manager before registering the shortcuts.

Parameters:

recognizerFile - The name of the file containing the shape matching recognizer definition

inline - True if stroke shortcuts must be displayed beside their corresponding menu items

tooltip - True if stroke shortcuts must be displayed in the tooltip of corresponding components

See Also:

addShortcut(String, Vector, boolean, boolean), addWindow(Window)

windowGainedFocus

public void windowGainedFocus(java.awt.event.WindowEvent e)

Specified by:

windowGainedFocus in interface java.awt.event.WindowFocusListener

Overrides:

windowGainedFocus in class java.awt.event.WindowAdapter

addWindow

public void addWindow(java.awt.Window window)

Registers a window in this strokes shortcuts manager. This means that a stroke shortcut can be defined for any accessible action found in this window hierarchy.

Parameters:

window - The window to register.

enableStrokes

public void enableStrokes(java.awt.Component strokableComponent,
                          boolean hierarchy,
                          boolean drawInkOnGlassPane)

Registers a component to enable stroke when a drag interaction starts on it. If the component is already registered, his criterion will be deleted.

Parameters:

strokableComponent - The component where stroke recognition must be enabled.

hierarchy - If the component children of strokableComponent must also be added.

drawInkOnGlassPane - If stroke ink must be drawn on the glasspane.

setCriterion

public boolean setCriterion(java.awt.Component component,
                            Criterion criterion)

Sets the criterion for one component that is already registered in this strokes shortcuts manager.

Parameters:

component - The component

criterion - The new criterion

Returns:

True if the criterion has been set, false if component was not already registered (in this latter case, this method does nothing).

enableStrokes

public void enableStrokes(java.awt.Component strokableComponent,
                          boolean hierarchy,
                          boolean drawInkOnGlassPane,
                          Criterion criterion)

Registers a component to enable stroke when a drag interaction starts on when a given criterion is verified. If the component is already registered, his criterion will be replaced by criterion. If this component is a RootPaneContainer, its content pane is registered.
WARNING: Only JComponents can be defined as strokable.

Parameters:

strokableComponent - The component where stroke recognition must be enabled.

hierarchy - If the component children of strokableComponent must also be added.

drawInkOnGlassPane - If stroke ink must be drawn on the glasspane.

criterion - The criterion that specifies when a stroke begins.

isStrokable

public boolean isStrokable(java.awt.Component c)

Parameters:

c - the component

Returns:

true if this component is registered as a strokable component in this strokes shortcuts manager.

enableStrokesSheet

public void enableStrokesSheet()

Enables the strokes sheet: when pausing for 300 milliseconds while tracing a strokes, the strokes sheet pops up close to the mouse cursor. It automatically disappears when a stroke has been recognized.

getClassifier

public fr.lri.swingstates.gestures.shapeMatching.ShapeMatchingClassifier getClassifier()

Returns:

The shape matching classifier associated with this strokes shortcuts manager.

disableStrokes

public void disableStrokes(java.awt.Component strokableComponent)

Disables stroke recognition for strokes started on a given component.

Parameters:

strokableComponent - The component on which stroke recognition must be disabled.

disableStrokes

public void disableStrokes(java.awt.Component strokableComponent,
                           boolean hierarchy)

Disables stroke recognition for strokes started on a given component.

Parameters:

strokableComponent - The component on which stroke recognition must be disabled.

getMinimumStrokeLength

public int getMinimumStrokeLength()

Returns:

The minimum length that must have a mouse drag to be considered as a stroke.

setMinimumStrokeLength

public void setMinimumStrokeLength(int minimumStrokeLength)

Parameters:

minimumStrokeLength - The minimum length that must have a mouse drag to be considered as a stroke.

getThreshold

public double getThreshold()

Returns:

The distance threshold (i.e. if the distance between the input stroke and the best template is greater than this threshold, the stroke is not recognized).

setThreshold

public void setThreshold(double maximumDistance)

Parameters:

maximumDistance - The distance threshold (i.e. if the distance between the input stroke and the best template is greater than this threshold, the stroke is not recognized).

getCriterion

public Criterion getCriterion(javax.swing.JComponent component)

Parameters:

component - a component

Returns:

The criterion associated with component or null if this component is not registered or does not have any criterion associated with it.

getStartPointColor

public java.awt.Color getStartPointColor()

Returns:

the color used for the rendering the first point of a stroke.

setStartPointColor

public void setStartPointColor(java.awt.Color startPointColor)

Parameters:

startPointColor - the color used for the rendering the first point of a stroke.

getInkColorWhileStroking

public java.awt.Color getInkColorWhileStroking()

Returns:

the color used for the rendering of a stroke ink while it is tracing.

setInkColorWhileStroking

public void setInkColorWhileStroking(java.awt.Color inkColorWhileStroking)

Parameters:

inkColorWhileStroking - the color used for the rendering of a stroke ink while it is tracing.

getInkColorWhenNonRecognized

public java.awt.Color getInkColorWhenNonRecognized()

In case of bad recognition, the stroke will stay displayed for 200 milliseconds in a this color.

Returns:

the color used for the rendering of a stroke when it is not recognized.

setInkColorWhenNonRecognized

public void setInkColorWhenNonRecognized(java.awt.Color inkColorWhenNonRecognized)

In case of bad recognition, the stroke will stay displayed for 200 milliseconds in a this color.

Parameters:

inkColorWhenNonRecognized - the color used for the rendering of a stroke when it is not recognized.

getInkColorWhileBeautifying

public java.awt.Color getInkColorWhileBeautifying()

In case of good recognition, the stroke will be beautified to match its template stroke. This beautification animation lasts 300 milliseconds.

Returns:

the color used for the rendering of a stroke while it is beautified.

setInkColorWhileBeautifying

public void setInkColorWhileBeautifying(java.awt.Color inkColorWhileBeautifying)

In case of good recognition, the stroke will be beautified to match its template stroke. This beautification animation lasts 300 milliseconds.

Parameters:

inkColorWhileBeautifying - the color used for the rendering of a stroke while it is beautified.

classify

public java.lang.String classify(fr.lri.swingstates.gestures.Gesture gesture)

Return the command name that minimizes the distance to an input stroke within the set of stroke templates registered in this strokes shortcuts manager.

Parameters:

gesture - The stroke

Returns:

The name of the accessible action that has the best match in the classifier of this strokes shortcuts manager or null if the stroke is not long enough (i.e. inferior to the minimum stroke length defined in this strokes shortcuts manager)

getIcon

public StrokeIcon getIcon(java.lang.String command,
                          int width,
                          int height)

Creates a StrokeIcon of a stroke given its command name. The stroke is drawn in black with a red starting point of diameter 6.

Parameters:

command - The name of the command activated by the stroke

width - The width of the icon

height - The height of the icon

getIcon

public StrokeIcon getIcon(java.lang.String command,
                          int width,
                          int height,
                          java.awt.Color colorStroke,
                          int sizeStartingPoint,
                          java.awt.Color colorStartingPoint)

Creates a StrokeIcon of a stroke given its command name.

Parameters:

command - The name of the command activated by the stroke

width - The width of the icon

height - The height of the icon

colorStroke - The color of the stroke

sizeStartingPoint - The diameter of the starting point

colorStartingPoint - The color of the starting point

getPngImage

public void getPngImage(java.io.File file,
                        java.lang.String command,
                        int sideSizeImage,
                        java.awt.Color colorStroke,
                        int sizeStartingPoint,
                        java.awt.Color colorStartingPoint)

Creates a squared png image of a stroke given its command name.

Parameters:

file - The image file

command - The name of the command activated by the stroke

sideSizeImage - The size of image side

colorStroke - The stroke color

sizeStartingPoint - The diameter of the stroke's starting point

colorStartingPoint - The color of the stroke's starting point

getInkTrail

public fr.lri.swingstates.canvas.CPolyLine getInkTrail()

Returns:

The ink trail as a SwingStates' polyline. Null if ink trail is not enabled.

getStartingPoint

public fr.lri.swingstates.canvas.CEllipse getStartingPoint()

Returns:

The ink trail's starting point of a stroke as a SwingStates' ellipse. Null if ink trail is not enabled.

getPngImage

public void getPngImage(java.io.File file,
                        java.lang.String command,
                        int sideSizeImage,
                        int sizeStartingPoint)

Creates a squared png image of a stroke given its command name. The stroke is colored in black and its starting point in red.

Parameters:

file - The image file

command - The name of the command activated by the stroke

sideSizeImage - The size of image side

sizeStartingPoint - The diameter of the stroke's starting point