com.yworks.yfiles.view.input

Class SnapContext

java.lang.Object

com.yworks.yfiles.view.input.SnapContext

Direct Known Subclasses:

GraphSnapContext, LabelSnapContext

public class SnapContext
extends Object

Manages interactive snapping of elements to other elements during drag operations like movements.

This class should be used by IInputMode implementations and similar code as follows:

• To initialize the operation initializeDrag(IInputModeContext, PointD) needs to be called.
• Method dragInitialized() needs to be called after the mode has performed all of its own initialization.
• Then a series of zero or more invocations handleMove(PointD, boolean) needs to be called for each incremental movement of the user's input device.
• After handleMove(PointD, boolean) has been called, the mode should perform the move and report back to the instance by calling the dragged(PointD, SnapState) method.
• If the operation is canceled by the user cancelDrag() should be called.
• If the operation is finalized the dragFinished(PointD, boolean) method should be called.

See Also:

HandleInputMode.getSnapContext(), MoveInputMode.getSnapContext(), createSnapResultsModelManager(CanvasControl)

Constructor Summary

Constructors

Constructor and Description
SnapContext() Initializes a new instance of the SnapContext class.

Method Summary

Modifier and Type	Method and Description
void	addCleanedUpListener(IEventHandler<InputModeEventArgs> cleanedUpEvent) Adds the given listener for the CleanedUp event that occurs when this instance has been cleaned up.
void	addCollectSnapResultsListener(IEventHandler<CollectSnapResultsEventArgs> collectSnapResultsEvent) Adds the given listener for the CollectSnapResults event that occurs while moving items and handles.
void	addInitializedListener(IEventHandler<InputModeEventArgs> initializedEvent) Adds the given listener for the Initialized event that occurs when this instance has been initialized.
void	addInitializingListener(IEventHandler<InputModeEventArgs> initializingEvent) Adds the given listener for the Initializing event that occurs when this instance is about to be initialized.
void	cancelDrag() Called when a drag has been canceled.
protected void	cleanUp() Performs clean up procedures.
ICanvasObjectDescriptor	createSnapResultCanvasObjectDescriptor() Helper method used by createSnapResultsModelManager(CanvasControl) to create the ICanvasObjectDescriptor for the SnapResult type.
CollectionModelManager<SnapResult>	createSnapResultsModelManager(CanvasControl canvas) Helper method that creates the a CollectionModelManager that can be used to present the current SnapResults in the provided CanvasControl.
SnapState	dragFinished(PointD newLocation, boolean snappingDisabled) Called when a drag has been successfully finished.
void	dragged(PointD mouseLocation, SnapState finalSnapState) This method needs to be called by the client IInputMode that initialized this instance after it has performed the actual move operation with the adjusted coordinates after a call to handleMove(PointD, boolean).
void	dragInitialized() Collects a list of snap lines.
protected IInputModeContext	getCurrentInputModeContext() Gets the current input mode context.
PointD	getOriginalLocation() Gets the original location of the mouse at the time the gesture was initialized.
double	getSnapDistance() Gets the global snap distance, which is the maximum distance between the current mouse coordinates and the coordinates to which the mouse will snap.
IObservableCollection<SnapResult>	getSnapResults() The collection of SnapResults.
SnapState	handleMove(PointD newLocation, boolean snappingDisabled) Handles a move.
void	initializeDrag(IInputModeContext context, PointD originalLocation) Called by IInputMode implementations when an interactive drag is started.
boolean	isEnabled() Gets a value indicating whether this SnapContext is enabled.
boolean	isInitialized() Whether the context is initialized.
boolean	isInitializing() Gets a value indicating whether this instance is currently initializing.
boolean	isSnapResultVisualizationEnabled() Gets a value indicating whether to visualize the snap results.
protected void	onCleanUp(InputModeEventArgs eventArgs) Raises the cleanUp() event.
protected void	onCollectSnapResults(CollectSnapResultsEventArgs args) Raises the CollectSnapResults event.
protected void	onInitialized(InputModeEventArgs eventArgs) Raises the Initialized event.
protected void	onInitializing(InputModeEventArgs eventArgs) Raises the Initializing event.
protected SnapState	processSnapResults(ArrayList<SnapResult> snapResults, PointD originalLocation, PointD newLocation) Chooses the current SnapResults from a temporary list.
void	removeCleanedUpListener(IEventHandler<InputModeEventArgs> cleanedUpEvent) Removes the given listener for the CleanedUp event that occurs when this instance has been cleaned up.
void	removeCollectSnapResultsListener(IEventHandler<CollectSnapResultsEventArgs> collectSnapResultsEvent) Removes the given listener for the CollectSnapResults event that occurs while moving items and handles.
void	removeInitializedListener(IEventHandler<InputModeEventArgs> initializedEvent) Removes the given listener for the Initialized event that occurs when this instance has been initialized.
void	removeInitializingListener(IEventHandler<InputModeEventArgs> initializingEvent) Removes the given listener for the Initializing event that occurs when this instance is about to be initialized.
void	setEnabled(boolean value) Sets a value indicating whether this SnapContext is enabled.
void	setSnapDistance(double value) Sets the global snap distance, which is the maximum distance between the current mouse coordinates and the coordinates to which the mouse will snap.
void	setSnapResultVisualizationEnabled(boolean value) Sets a value indicating whether to visualize the snap results.
IInputModeContext	wrapContext(IInputModeContext context) Helper method that wraps the given context so that a ILookup.lookup(Class) query on the wrapped context for the SnapContext type yields this instance.

Methods inherited from class java.lang.Object

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

Constructor Detail

SnapContext

public SnapContext()

Initializes a new instance of the SnapContext class.

Method Detail

addCleanedUpListener

public final void addCleanedUpListener(IEventHandler<InputModeEventArgs> cleanedUpEvent)

Adds the given listener for the CleanedUp event that occurs when this instance has been cleaned up.

Parameters:

cleanedUpEvent - The listener to add.

See Also:

cleanUp(), removeCleanedUpListener(IEventHandler)

addCollectSnapResultsListener

public final void addCollectSnapResultsListener(IEventHandler<CollectSnapResultsEventArgs> collectSnapResultsEvent)

Adds the given listener for the CollectSnapResults event that occurs while moving items and handles.

The moving model items must register for this event, preferably in the IDragHandler.initializeDrag(IInputModeContext) method of the IDragHandler.

The event handler has to add SnapResults for the moving object to the list. The IDragHandlers of the moved items have to take care themselves whether to add a handler to the list depending on the their settings.

Parameters:

collectSnapResultsEvent - The listener to add.

See Also:

removeCollectSnapResultsListener(IEventHandler)

addInitializedListener

public final void addInitializedListener(IEventHandler<InputModeEventArgs> initializedEvent)

Adds the given listener for the Initialized event that occurs when this instance has been initialized.

Parameters:

initializedEvent - The listener to add.

See Also:

initializeDrag(IInputModeContext, PointD), removeInitializedListener(IEventHandler)

addInitializingListener

public final void addInitializingListener(IEventHandler<InputModeEventArgs> initializingEvent)

Adds the given listener for the Initializing event that occurs when this instance is about to be initialized.

Parameters:

initializingEvent - The listener to add.

See Also:

initializeDrag(IInputModeContext, PointD), removeInitializingListener(IEventHandler)

cancelDrag

public void cancelDrag()

Called when a drag has been canceled.

Clears all temporary lists and sets IsInitialized back to false, as well as performs cleanUp() and finally triggers the CleanedUp event.

cleanUp

protected void cleanUp()

Performs clean up procedures.

This is called in response to cancelDrag() and dragFinished(PointD, boolean) as well as initially during initializeDrag(IInputModeContext, PointD).

createSnapResultCanvasObjectDescriptor

public ICanvasObjectDescriptor createSnapResultCanvasObjectDescriptor()

Helper method used by createSnapResultsModelManager(CanvasControl) to create the ICanvasObjectDescriptor for the SnapResult type.

Returns:

An instance that can install SnapResults in a CanvasControl.

createSnapResultsModelManager

public CollectionModelManager<SnapResult> createSnapResultsModelManager(CanvasControl canvas)

Helper method that creates the a CollectionModelManager that can be used to present the current SnapResults in the provided CanvasControl.

Parameters:

canvas - The control to initialize the CollectionModelManager with.

Returns:

The model manager that manages the visual representation of the SnapResults.

dragFinished

public SnapState dragFinished(PointD newLocation,
                              boolean snappingDisabled)

Called when a drag has been successfully finished.

Clears all temporary lists and sets IsInitialized back to false. Also the cleanUp() method is invoked and the CleanedUp event is triggered.

Parameters:

newLocation - The current mouse location.

snappingDisabled - If set to true snapping is temporarily disabled. This will remove the snap line visualizations and return a SnapState with the unchanged coordinates and the SnapTypes.NOT_SNAPPED SnapType.

Returns:

A SnapState that specifies the adjusted coordinates and how they have been adjusted. The unchanged coordinates if snapping has been temporarily disabled by setting snappingDisabled to true.

dragged

public void dragged(PointD mouseLocation,
                    SnapState finalSnapState)

This method needs to be called by the client IInputMode that initialized this instance after it has performed the actual move operation with the adjusted coordinates after a call to handleMove(PointD, boolean).

Most of the client code implementations will just call this method with the exact values returned by handleMove(PointD, boolean). This method does not need to be called if snapping has been temporarily disabled by calling handleMove(PointD, boolean) with its snappingDisabled parameter set to true.

Parameters:

mouseLocation - The actual mouse location.

finalSnapState - The final snap state that contains the location that has been used by the client code for the move and how it has been snapped.

dragInitialized

public void dragInitialized()

Collects a list of snap lines.

Snap lines represent possible horizontal or vertical lines to which a moved item can "snap".

This method is called at the start of MoveInputMode's or HandleInputMode's gesture after all items to be moved or reshaped have been added.

getCurrentInputModeContext

protected final IInputModeContext getCurrentInputModeContext()

Gets the current input mode context.

Returns:

The current input mode context if this instance IsInitialized or IsInitializing, otherwise null.

getOriginalLocation

public final PointD getOriginalLocation()

Gets the original location of the mouse at the time the gesture was initialized.

Returns:

The original location.

See Also:

initializeDrag(IInputModeContext, PointD)

getSnapDistance

public final double getSnapDistance()

Gets the global snap distance, which is the maximum distance between the current mouse coordinates and the coordinates to which the mouse will snap.

The distance is interpreted in view coordinates.

The default is 5.0d

Returns:

The SnapDistance.

See Also:

CollectSnapResultsEventArgs.getSnapDistance(), setSnapDistance(double)

getSnapResults

public final IObservableCollection<SnapResult> getSnapResults()

The collection of SnapResults.

This collection is automatically updated during moving the mouse.

Returns:

The SnapResults.

handleMove

public SnapState handleMove(PointD newLocation,
                            boolean snappingDisabled)

Handles a move.

This method returns the adjusted (mouse) coordinates. It also manages the collection of SnapResults. If snapping should be temporarily (for a mouse move) disabled, snappingDisabled has to be set to true.

Parameters:

newLocation - The current mouse location.

snappingDisabled - If set to true snapping is temporarily disabled. This will remove the snap line visualizations and return a SnapState with the unchanged coordinates and the SnapType SnapTypes.NOT_SNAPPED.

Returns:

The adjusted coordinates and how they have been adjusted. The unchanged coordinates if snapping has been temporarily disabled by setting snappingDisabled to true.

initializeDrag

public void initializeDrag(IInputModeContext context,
                           PointD originalLocation)

Called by IInputMode implementations when an interactive drag is started.

Updates IsInitializing, OriginalLocation, and CurrentInputModeContext and then triggers the Initializing event.

Throws:

IllegalStateException - If this context is already initialized.

Parameters:

context - The context in which the interactive drag is started.

originalLocation - The original location of the mouse.

isEnabled

public final boolean isEnabled()

Gets a value indicating whether this SnapContext is enabled.

Returns:

true if enabled; false otherwise.

See Also:

setEnabled(boolean)

isInitialized

public final boolean isInitialized()

Whether the context is initialized.

The context is initialized between the calls to dragInitialized() and dragFinished(PointD, boolean) or cancelDrag().

Returns:

The IsInitialized.

isInitializing

public final boolean isInitializing()

Gets a value indicating whether this instance is currently initializing.

Returns:

true if this instance is initializing; false otherwise.

See Also:

addInitializedListener(IEventHandler), addInitializingListener(IEventHandler), isInitialized()

isSnapResultVisualizationEnabled

public final boolean isSnapResultVisualizationEnabled()

Gets a value indicating whether to visualize the snap results.

Returns:

true if the results should be visualized false otherwise.

See Also:

createSnapResultsModelManager(CanvasControl), setSnapResultVisualizationEnabled(boolean)

onCleanUp

protected void onCleanUp(InputModeEventArgs eventArgs)

Raises the cleanUp() event.

Parameters:

eventArgs - The InputModeEventArgs instance containing the event data.

onCollectSnapResults

protected void onCollectSnapResults(CollectSnapResultsEventArgs args)

Raises the CollectSnapResults event.

Parameters:

args - The CollectSnapResultsEventArgs instance containing the event data.

onInitialized

protected void onInitialized(InputModeEventArgs eventArgs)

Raises the Initialized event.

Parameters:

eventArgs - The InputModeEventArgs instance containing the event data.

onInitializing

protected void onInitializing(InputModeEventArgs eventArgs)

Raises the Initializing event.

Parameters:

eventArgs - The InputModeEventArgs instance containing the event data.

processSnapResults

protected SnapState processSnapResults(ArrayList<SnapResult> snapResults,
                                       PointD originalLocation,
                                       PointD newLocation)

Chooses the current SnapResults from a temporary list.

Chooses from a list of possible results the most important ones. Also maintains the collection of snap results.

Parameters:

snapResults - A temporary list of suggested SnapResults.

originalLocation - The point in world coordinates where the mouse move started.

newLocation - The current mouse location.

Returns:

The adjusted coordinates and how they have been adjusted.

removeCleanedUpListener

public final void removeCleanedUpListener(IEventHandler<InputModeEventArgs> cleanedUpEvent)

Removes the given listener for the CleanedUp event that occurs when this instance has been cleaned up.

Parameters:

cleanedUpEvent - The listener to remove.

See Also:

cleanUp(), addCleanedUpListener(IEventHandler)

removeCollectSnapResultsListener

public final void removeCollectSnapResultsListener(IEventHandler<CollectSnapResultsEventArgs> collectSnapResultsEvent)

Removes the given listener for the CollectSnapResults event that occurs while moving items and handles.

The moving model items must register for this event, preferably in the IDragHandler.initializeDrag(IInputModeContext) method of the IDragHandler.

The event handler has to add SnapResults for the moving object to the list. The IDragHandlers of the moved items have to take care themselves whether to add a handler to the list depending on the their settings.

Parameters:

collectSnapResultsEvent - The listener to remove.

See Also:

addCollectSnapResultsListener(IEventHandler)

removeInitializedListener

public final void removeInitializedListener(IEventHandler<InputModeEventArgs> initializedEvent)

Removes the given listener for the Initialized event that occurs when this instance has been initialized.

Parameters:

initializedEvent - The listener to remove.

See Also:

initializeDrag(IInputModeContext, PointD), addInitializedListener(IEventHandler)

removeInitializingListener

public final void removeInitializingListener(IEventHandler<InputModeEventArgs> initializingEvent)

Removes the given listener for the Initializing event that occurs when this instance is about to be initialized.

Parameters:

initializingEvent - The listener to remove.

See Also:

initializeDrag(IInputModeContext, PointD), addInitializingListener(IEventHandler)

setEnabled

public final void setEnabled(boolean value)

Sets a value indicating whether this SnapContext is enabled.

Parameters:

value - true if enabled; false otherwise.

See Also:

isEnabled()

setSnapDistance

public final void setSnapDistance(double value)

Sets the global snap distance, which is the maximum distance between the current mouse coordinates and the coordinates to which the mouse will snap.

The distance is interpreted in view coordinates.

The default is 5.0d

Parameters:

value - The SnapDistance to set.

See Also:

CollectSnapResultsEventArgs.getSnapDistance(), getSnapDistance()

setSnapResultVisualizationEnabled

public final void setSnapResultVisualizationEnabled(boolean value)

Sets a value indicating whether to visualize the snap results.

Parameters:

value - true if the results should be visualized false otherwise.

See Also:

createSnapResultsModelManager(CanvasControl), isSnapResultVisualizationEnabled()

wrapContext

public IInputModeContext wrapContext(IInputModeContext context)

Helper method that wraps the given context so that a ILookup.lookup(Class) query on the wrapped context for the SnapContext type yields this instance.

Parameters:

context - The context to wrap and delegate all calls to.

Returns:

A modified instance that yields this instance if it is queried for the SnapContext type.