com.yworks.yfiles.view.input

Class KeyboardInputMode

java.lang.Object

com.yworks.yfiles.view.input.KeyboardInputMode

All Implemented Interfaces:

IInputMode

public class KeyboardInputMode
extends Object
implements IInputMode

An IInputMode that recognizes simple key events and invokes a registered handler.

This mode is Exclusive by default.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	KeyboardInputMode.CanExecuteCommandHandler Defines the contract for determining whether a given ICommand can be executed for the given parameter set.
static interface	KeyboardInputMode.ExecuteCommandHandler Defines the contract for executign a given ICommand for the given parameter set.

Constructor Summary

Constructors

Constructor and Description
KeyboardInputMode()

Method Summary

Modifier and Type	Method and Description
KeyboardInputModeBinding	addCommandBinding(ICommand command) Adds a command and associated execution handlers to this instance.
KeyboardInputModeBinding	addCommandBinding(ICommand command, KeyboardInputMode.ExecuteCommandHandler execute) Adds a command and associated execution handlers to this instance.
KeyboardInputModeCommandBinding	addCommandBinding(ICommand command, KeyboardInputMode.ExecuteCommandHandler execute, KeyboardInputMode.CanExecuteCommandHandler canExecute) Adds a command and associated execution handlers to this instance.
KeyboardInputModeBinding	addHandler(IEventRecognizer recognizer, KeyboardInputMode.ExecuteCommandHandler handler) Adds an event handler for key events recognized by the given IEventRecognizer.
KeyboardInputModeBinding	addHandler(KeyCodeCombination accelerator, KeyboardInputMode.ExecuteCommandHandler handler) Adds an event handler for the given KeyCodeCombination to this mode.
KeyboardInputModeBinding	addKeyBinding(KeyCodeCombination gesture, ICommand command) Adds an event handler for a specific key press gesture to this mode.
KeyboardInputModeKeyBinding	addKeyBinding(KeyCodeCombination gesture, ICommand command, Object commandParameter) Adds an event handler for a specific key press gesture to this mode.
KeyboardInputModeBinding	addKeyBinding(KeyCode key, ModifierKeys modifiers, ICommand command, Object commandParameter) Adds an event handler for a specific key press gesture to this mode.
KeyboardInputModeBinding	addRecognizerBinding(IEventRecognizer recognizer, ICommand command) Adds a given handler to this instance that will be triggered if the IEventRecognizer recognizes a key event that has been triggered by the CanvasControl.
KeyboardInputModeRecognizerBinding	addRecognizerBinding(IEventRecognizer recognizer, ICommand command, Object commandParameter) Adds a given handler to this instance that will be triggered if the IEventRecognizer recognizes a key event that has been triggered by the canvas control.
void	cancel() Called by the client to unconditionally cancel all editing.
Collection<KeyboardInputModeCommandBinding>	getCommandBindings(ICommand command) Returns the command bindings that have been registered using one of this mode's addCommandBinding methods for the given command.
protected ConcurrencyController	getController() Returns the installed Controller.
IInputModeContext	getInputModeContext() Returns the context instance this mode is currently installed in or null if this instance is not installed.
Collection<KeyboardInputModeKeyBinding>	getKeyBindings(ICommand command) Returns the key bindings registered for the given command.
int	getPriority() The priority of this input mode.
Collection<KeyboardInputModeRecognizerBinding>	getRecognizerBindings(ICommand command) Returns the recognizer bindings registered for the given command.
void	install(IInputModeContext context, ConcurrencyController controller) Installs this mode into the given context that is provided by the canvas.
boolean	isEnabled() Gets the enabled state of this input mode.
boolean	isExclusive() Gets a value indicating whether this mode will be the only one running when it has the mutex.
protected void	onCanceled() Called after cancel() has been called.
protected void	onConcurrencyControllerActivated() Called after the Active property of the installed ConcurrencyController has been set to true.
protected void	onConcurrencyControllerDeactivated() Called after the Active property of the installed ConcurrencyController has been set to false.
protected void	onStopped() Called after stop() has been called.
void	removeCommand(ICommand command) Removes all previously registered commands from this instance.
void	setEnabled(boolean value) Sets the enabled state of this input mode.
void	setExclusive(boolean value) Sets a value indicating whether this mode will be the only one running when it has the mutex.
void	setPriority(int value) The priority of this input mode.
boolean	stop() Overridden to only return true if this instance does not currently have the input mutex.
void	uninstall(IInputModeContext context) Uninstalls this mode from the given context.

Methods inherited from class java.lang.Object

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

Constructor Detail

KeyboardInputMode

public KeyboardInputMode()

Method Detail

addCommandBinding

public final KeyboardInputModeBinding addCommandBinding(ICommand command)

Adds a command and associated execution handlers to this instance.

The command will not be allowed to execute if this mode is disabled or inactive.

Parameters:

command - The command to register handlers with.

Returns:

A token for the newly created command binding that can used to later remove this binding from this instance again.

addCommandBinding

public final KeyboardInputModeBinding addCommandBinding(ICommand command,
                                                        KeyboardInputMode.ExecuteCommandHandler execute)

Adds a command and associated execution handlers to this instance.

The command will not be allowed to execute if this mode is disabled or inactive.

Parameters:

command - The command to register handlers with.

execute - The handler for the execution; a handler that will do nothing if omitted.

Returns:

A token for the newly created command binding that can used to later remove this binding from this instance again.

addCommandBinding

public final KeyboardInputModeCommandBinding addCommandBinding(ICommand command,
                                                               KeyboardInputMode.ExecuteCommandHandler execute,
                                                               KeyboardInputMode.CanExecuteCommandHandler canExecute)

Adds a command and associated execution handlers to this instance.

The command will not be allowed to execute if this mode is disabled or inactive.

Parameters:

command - The command to register handlers with.

execute - The handler for the execution; a handler that will do nothing if omitted.

canExecute - The handler that determines executability; a handler that is always enabled if omitted.

Returns:

A token for the newly created command binding that can used to later remove this binding from this instance again.

addHandler

public KeyboardInputModeBinding addHandler(IEventRecognizer recognizer,
                                           KeyboardInputMode.ExecuteCommandHandler handler)

Adds an event handler for key events recognized by the given IEventRecognizer.

Using this method, the handler will not be invoked if this instance is disabled.

This method is convenience for adding "always active" event handlers. For more complex handlers whose execution is conditional or depends on parameters, use addCommandBinding and addRecognizerBinding.

Parameters:

recognizer - An event recognizer that will be queried for all key events.

handler - The handler to invoke if the recognizer recognizes an event.

Returns:

A token that can be used to remove the handler again.

See Also:

addCommandBinding(ICommand, ExecuteCommandHandler, CanExecuteCommandHandler), addRecognizerBinding(IEventRecognizer, ICommand, Object)

addHandler

public KeyboardInputModeBinding addHandler(KeyCodeCombination accelerator,
                                           KeyboardInputMode.ExecuteCommandHandler handler)

Adds an event handler for the given KeyCodeCombination to this mode.

Using this method, the handler will not be invoked if this instance is disabled.

This method is convenience for adding "always active" event handlers. For more complex handlers whose execution is conditional or depends on parameters, use addCommandBinding and addKeyBinding.

Parameters:

accelerator - The keyboard shortcut that will be used to trigger the event handler.

handler - The handler that will be used to handle the event.

Returns:

A token that can be used to remove the handler again.

See Also:

addCommandBinding(ICommand, ExecuteCommandHandler, CanExecuteCommandHandler), addKeyBinding(KeyCodeCombination, ICommand, Object)

addKeyBinding

public final KeyboardInputModeBinding addKeyBinding(KeyCodeCombination gesture,
                                                    ICommand command)

Adds an event handler for a specific key press gesture to this mode.

Using this registration method, the command will not be allowed to execute if this mode is disabled or inactive.

Parameters:

gesture - The gesture.

command - The command to execute.

Returns:

A token for the newly created command binding that can used to later remove this binding from this instance again.

addKeyBinding

public final KeyboardInputModeKeyBinding addKeyBinding(KeyCodeCombination gesture,
                                                       ICommand command,
                                                       Object commandParameter)

Adds an event handler for a specific key press gesture to this mode.

Using this registration method, the command will not be allowed to execute if this mode is disabled or inactive.

Parameters:

gesture - The gesture.

command - The command to execute.

commandParameter - The command parameter to use for the execution; null if omitted.

Returns:

A token for the newly created command binding that can used to later remove this binding from this instance again.

addKeyBinding

public final KeyboardInputModeBinding addKeyBinding(KeyCode key,
                                                    ModifierKeys modifiers,
                                                    ICommand command,
                                                    Object commandParameter)

Adds an event handler for a specific key press gesture to this mode.

Using this registration method, the command will not be allowed to execute if this mode is disabled or inactive.

Parameters:

key - The key constant that should be recognized.

modifiers - The modifiers that should be recognized when the key is pressed.

command - The command to execute.

Returns:

A token for the newly created command binding that can used to later remove this binding from this instance again.

addRecognizerBinding

public final KeyboardInputModeBinding addRecognizerBinding(IEventRecognizer recognizer,
                                                           ICommand command)

Adds a given handler to this instance that will be triggered if the IEventRecognizer recognizes a key event that has been triggered by the CanvasControl.

Parameters:

recognizer - An event recognizer that will be fed with all key events.

command - The command to invoke if the recognizer matches a key event.

Returns:

The newly constructed binding on which KeyboardInputModeBinding.remove() can be called to remove the resulting binding from this instance.

addRecognizerBinding

public final KeyboardInputModeRecognizerBinding addRecognizerBinding(IEventRecognizer recognizer,
                                                                     ICommand command,
                                                                     Object commandParameter)

Adds a given handler to this instance that will be triggered if the IEventRecognizer recognizes a key event that has been triggered by the canvas control.

Parameters:

recognizer - An event recognizer that will be fed with all key events.

command - The command to invoke if the recognizer matches a key event.

commandParameter - The optional parameter to provide to the command.

Returns:

The newly constructed binding on which KeyboardInputModeBinding.remove() can be called to remove the resulting binding from this instance.

cancel

public void cancel()

Description copied from interface: IInputMode

Called by the client to unconditionally cancel all editing.

This will be called prior to the uninstalling of this instance.

In order to stop an active input mode manually, client code should use the following idiom:

Specified by:

cancel in interface IInputMode

getCommandBindings

public final Collection<KeyboardInputModeCommandBinding> getCommandBindings(ICommand command)

Returns the command bindings that have been registered using one of this mode's addCommandBinding methods for the given command.

See Also:

addCommandBinding(ICommand), addCommandBinding(ICommand, ExecuteCommandHandler), addCommandBinding(ICommand, ExecuteCommandHandler, CanExecuteCommandHandler)

getController

protected final ConcurrencyController getController()

Returns the installed Controller.

Returns:

The Controller.

getInputModeContext

public final IInputModeContext getInputModeContext()

Description copied from interface: IInputMode

Returns the context instance this mode is currently installed in or null if this instance is not installed.

Note that this instance should not be passed down to subordinate modes or instances. Instead a corresponding context that has this instance set as the ParentInputMode should be used.

Specified by:

getInputModeContext in interface IInputMode

Returns:

The InputModeContext.

getKeyBindings

public final Collection<KeyboardInputModeKeyBinding> getKeyBindings(ICommand command)

Returns the key bindings registered for the given command.

See Also:

addKeyBinding(KeyCode, ModifierKeys, ICommand, Object), addKeyBinding(KeyCodeCombination, ICommand), addKeyBinding(KeyCodeCombination, ICommand, Object)

getPriority

public final int getPriority()

Description copied from interface: IInputMode

The priority of this input mode.

The priority will influence the order in which the modes will be installed into the canvas control. The lower the priority value, the earlier it will be installed. If two modes are installed using the same priority value, the first one will be installed earlier.

Specified by:

getPriority in interface IInputMode

Returns:

The Priority.

getRecognizerBindings

public final Collection<KeyboardInputModeRecognizerBinding> getRecognizerBindings(ICommand command)

Returns the recognizer bindings registered for the given command.

See Also:

addRecognizerBinding(IEventRecognizer, ICommand), addRecognizerBinding(IEventRecognizer, ICommand, Object)

install

public void install(IInputModeContext context,
                    ConcurrencyController controller)

Installs this mode into the given context that is provided by the canvas.

In general a mode can only be installed into a single canvas at all times.

This method is called to initialize this instance. Subclasses should override this method to register the corresponding event handler delegates for the various input events they need to register with.

Overriding implementations should call the base implementation, first.

Specified by:

install in interface IInputMode

Parameters:

context - The context that this instance shall be installed into. The same instance will be passed to this instance during IInputMode.uninstall(IInputModeContext). A reference to the context may be kept and queried during the time the mode is installed.

controller - The Controller for this mode.

See Also:

IInputMode.uninstall(IInputModeContext)

isEnabled

public boolean isEnabled()

Gets the enabled state of this input mode.

Clients can use this property to disable or reenable this instance. This will set the Enabled property of the installed Controller so a disabled instance should never try to acquire the input mutex.

Returns:

The Enabled.

See Also:

setEnabled(boolean)

isExclusive

public final boolean isExclusive()

Gets a value indicating whether this mode will be the only one running when it has the mutex.

The value of this property will be delegated to the Exclusive property of the Controller.

If this mode is marked as exclusive and has the mutex, all other modes added to the same MultiplexingInputMode will be deactivated. Otherwise it will always run concurrently with all other modes.

Returns:

The Exclusive.

See Also:

setExclusive(boolean)

onCanceled

protected void onCanceled()

Called after cancel() has been called.

Can be overridden in subclasses to perform additional actions after the mode has been canceled.

This implementation does nothing.

onConcurrencyControllerActivated

protected void onConcurrencyControllerActivated()

Called after the Active property of the installed ConcurrencyController has been set to true.

Enables the registered commands and can be overridden in subclasses to perform additional actions after the mode has been activated.

Overriding implementations should call the base implementation.

onConcurrencyControllerDeactivated

protected void onConcurrencyControllerDeactivated()

Called after the Active property of the installed ConcurrencyController has been set to false.

Disables the registered commands and can be overridden in subclasses to perform additional actions after the mode has been deactivated.

Overriding implementations should call the base implementation.

onStopped

protected void onStopped()

Called after stop() has been called.

Can be overridden in subclasses to perform additional actions after the mode has been stopped.

This implementation does nothing.

removeCommand

public final void removeCommand(ICommand command)

Removes all previously registered commands from this instance.

This effectively disables the command for the instance managed by this mode.

Parameters:

command - The command to remove from all registered bindings.

See Also:

addKeyBinding(KeyCode, ModifierKeys, ICommand, Object), addRecognizerBinding(IEventRecognizer, ICommand, Object)

setEnabled

public void setEnabled(boolean value)

Sets the enabled state of this input mode.

Clients can use this property to disable or reenable this instance. This will set the Enabled property of the installed Controller so a disabled instance should never try to acquire the input mutex.

Parameters:

value - The Enabled to set.

See Also:

isEnabled()

setExclusive

public final void setExclusive(boolean value)

Sets a value indicating whether this mode will be the only one running when it has the mutex.

The value of this property will be delegated to the Exclusive property of the Controller.

If this mode is marked as exclusive and has the mutex, all other modes added to the same MultiplexingInputMode will be deactivated. Otherwise it will always run concurrently with all other modes.

Parameters:

value - The Exclusive to set.

See Also:

isExclusive()

setPriority

public final void setPriority(int value)

The priority of this input mode.

The priority will influence the order in which the modes will be installed into the canvas control. The lower the priority value, the earlier it will be installed. If two modes are installed using the same priority value, the first one will be installed earlier.

Parameters:

value - The Priority to set.

See Also:

getPriority()

stop

public boolean stop()

Overridden to only return true if this instance does not currently have the input mutex.

Specified by:

stop in interface IInputMode

Returns:

true iff this instance does not own the mutex.

See Also:

IInputMode.cancel()

uninstall

public void uninstall(IInputModeContext context)

Uninstalls this mode from the given context.

This code should clean up all changes made to the canvas in the IInputMode.install(IInputModeContext, ConcurrencyController) method. After a mode has been uninstalled it can be installed again into the same or another canvas.

Overriding implementations should call the base implementation after their own code.

Specified by:

uninstall in interface IInputMode

Parameters:

context - The context to deregister from. This is the same instance that had been passed to IInputMode.install(IInputModeContext, ConcurrencyController) during installation.