com.yworks.yfiles.view.input

Class MultiplexingInputMode

java.lang.Object

com.yworks.yfiles.view.input.MultiplexingInputMode

All Implemented Interfaces:

IInputMode

Direct Known Subclasses:

GraphEditorInputMode, GraphViewerInputMode, OverviewInputMode, TableEditorInputMode

public class MultiplexingInputMode
extends Object
implements IInputMode

A composite IInputMode implementation that additionally can deal with Exclusive instances.

Instances of this class can install(IInputModeContext, ConcurrencyController) and uninstall(IInputModeContext) multiple IInputModes. Child input modes can be added using the add(IInputMode) method. By providing priorities to the different modes, their installation order can be influenced. Input modes with lower priorities are handled earlier.

Child input modes can run exclusively while they hold the mutex. Other exclusive input modes are temporarily deactivated until the mutex is released. This can be controlled by setting the Exclusive property on the controller. Input modes that disable the Exclusive property will always run concurrently with all other input modes.

This class itself implements the IInputMode interface so that hierarchies of instances of this class can easily be built. This class will request the input mutex if one of its child modes requests the mutex. Also if the instance itself gets disabled, it will stop or cancel the current owner of the mutex.

See Also:

getMutexOwner(), add(IInputMode)

Constructor Summary

Constructors

Constructor and Description
MultiplexingInputMode() Creates an instance with no initial modes.

Method Summary

Modifier and Type	Method and Description
void	add(IInputMode mode) Adds the given mode.
void	adjustCursor() Adjusts the cursor of the CanvasControl according to the current input mutex owner or the first mode in the list whose ConcurrencyController returns a non-null PreferredCursor.
void	cancel() Cancels all modes.
protected Object	childInputModeContextLookup(Class type) Callback method that will be used by the child context's ILookup.lookup(Class) method.
protected IInputModeContext	createChildInputModeContext() Yields an IInputModeContext for the child modes of this mode.
protected InputModeEventArgs	createInputModeEventArgs(IInputModeContext context) Helper method that yields a suitably configured InputModeEventArgs for this input mode.
protected ConcurrencyController	getController() Returns the installed Controller.
Cursor	getDefaultCursor() Gets the cursor to use whenever no child mode prefers a different cursor.
IInputModeContext	getInputModeContext() Returns the context instance this mode is currently installed in or null if this instance is not installed.
IInputMode	getMutexOwner() Gets the IInputMode that currently owns the mutex.
int	getPriority() The priority of this input mode.
List<IInputMode>	getSortedModes() Returns a list of all modes managed by this instance in sorted order.
protected void	initialize() Performs one-time initialization of this instance.
void	install(IInputModeContext context, ConcurrencyController controller) Installs this mode into the given context that is provided by the canvas.
protected void	invalidate() Convenience method for subclass implementations that invalidates the canvas this mode is currently installed in.
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	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.
void	remove(IInputMode mode) Removes the given mode from this compound mode.
void	setDefaultCursor(Cursor value) Sets the cursor to use whenever no child mode prefers a different cursor.
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() Tries to stop all modes.
protected void	subModePriorityChanged() Called when the Priority of an installed sub mode has changed.
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

MultiplexingInputMode

public MultiplexingInputMode()

Creates an instance with no initial modes.

Method Detail

add

public final void add(IInputMode mode)

Adds the given mode.

The input modes will be ordered according to their Priority: Input modes with lower priority will be installed earlier.

Input modes will run exclusively if the Exclusive property of their installed controller is set to true. Otherwise they can not and will not be deactivated if another IInputMode acquires the mutex.

Throws:

IllegalArgumentException - If the same mode has is already added to this instance.

Parameters:

mode - The input mode to add to this mode.

adjustCursor

public void adjustCursor()

Adjusts the cursor of the CanvasControl according to the current input mutex owner or the first mode in the list whose ConcurrencyController returns a non-null PreferredCursor.

This method will set DefaultCursor as the current cursor if no other PreferredCursor has been specified.

cancel

public void cancel()

Cancels all modes.

Specified by:

cancel in interface IInputMode

childInputModeContextLookup

protected Object childInputModeContextLookup(Class type)

Callback method that will be used by the child context's ILookup.lookup(Class) method.

Parameters:

type - The type argument passed to ILookup.lookup(Class).

Returns:

The result of the lookup query, or null.

See Also:

createChildInputModeContext()

createChildInputModeContext

protected IInputModeContext createChildInputModeContext()

Yields an IInputModeContext for the child modes of this mode.

This method is called during installation to create a new context for the child modes and can be used by client code to obtain a suitable context object. The InputModeContext property is already set, when this method is called. ILookup.lookup(Class) calls for the created context will be resolved by this instance's childInputModeContextLookup(Class) method.

Returns:

A new instance that delegates to the parent's context.

createInputModeEventArgs

protected InputModeEventArgs createInputModeEventArgs(IInputModeContext context)

Helper method that yields a suitably configured InputModeEventArgs for this input mode.

Parameters:

context - An input mode context that is available in the InputModeEventArgs.

Can be null in which case a new context for this instance is created automatically.

Returns:

An input mode event argument that is configured for this instance.

getController

protected final ConcurrencyController getController()

Returns the installed Controller.

Returns:

The Controller.

getDefaultCursor

public final Cursor getDefaultCursor()

Gets the cursor to use whenever no child mode prefers a different cursor.

The default is null

Returns:

The DefaultCursor.

See Also:

adjustCursor(), setDefaultCursor(Cursor)

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.

getMutexOwner

public final IInputMode getMutexOwner()

Gets the IInputMode that currently owns the mutex.

Returns:

The IInputMode that currently owns the mutex or null.

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.

getSortedModes

public final List<IInputMode> getSortedModes()

Returns a list of all modes managed by this instance in sorted order.

Returns:

A list of the modes.

initialize

protected void initialize()

Performs one-time initialization of this instance.

This method should not be invoked by subclasses. This will be done automatically upon first installation of this mode.

This code will be executed only once per instance. The Canvas property and InputModeContext property will be null when this code is executed. This method should not be used to install this mode into a specific canvas. Subclasses should always call base.Initialize() first.

See Also:

install(IInputModeContext, ConcurrencyController)

install

public void install(IInputModeContext context,
                    ConcurrencyController controller)

Description copied from interface: IInputMode

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.
When this instance gets uninstalled from the context the same context instance will be passed to it.
Implementations may hold a reference to the context instance and use it while they are being installed.

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 ConcurrencyController for this mode.

See Also:

IInputMode.uninstall(IInputModeContext)

invalidate

protected void invalidate()

Convenience method for subclass implementations that invalidates the canvas this mode is currently installed in.

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)

onConcurrencyControllerActivated

protected void onConcurrencyControllerActivated()

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

This implementation reenabled previously disabled concurrent child modes.

onConcurrencyControllerDeactivated

protected void onConcurrencyControllerDeactivated()

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

This implementation sets the PreferredCursor property to null and releases the mutex if the mutex is currently owned by this instance. Also, all concurrent child modes will be disabled.

remove

public final void remove(IInputMode mode)

Removes the given mode from this compound mode.

Parameters:

mode - The mode to remove.

setDefaultCursor

public final void setDefaultCursor(Cursor value)

Sets the cursor to use whenever no child mode prefers a different cursor.

The default is null

Parameters:

value - The DefaultCursor to set.

See Also:

adjustCursor(), getDefaultCursor()

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()

Tries to stop all modes.

Specified by:

stop in interface IInputMode

Returns:

true if and only if the editing has been stopped or there was no edit in progress

See Also:

IInputMode.cancel()

subModePriorityChanged

protected final void subModePriorityChanged()

Called when the Priority of an installed sub mode has changed.

This implementation uninstalls all sub modes and then re-installs them according to their new priorities.

uninstall

public void uninstall(IInputModeContext context)

Description copied from interface: IInputMode

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.

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.