Class GestureFollower

Object
CanvasFollower
GestureFollower
All Implemented Interfaces:
Property­Change­Listener, Event­Listener, Event­Handler<Mouse­Event>, Disposable
public class GestureFollower extends CanvasFollower implements EventHandler<MouseEvent>
A listener of mouse or keyboard events in a source canvas which can be reproduced in a target canvas. This listener can reproduce the "real world" displacements documented in parent class. In addition, this class can also follow mouse movements in source canvas and move a cursor in the target canvas at the same "real world" position. These two features are disabled by default and can be enabled by setting the transform­Enabled and/or cursor­Enabled flags to true.

Listeners

Gesture­Follower listeners need to be registered explicitly by a call to the Canvas­Follower​.initialize() method. Conversely, the dispose() method unregisters all those listeners. The listeners are unidirectional: changes in the source canvas are applied on the target canvas, but not the converse.

Multi-threading

This class is not thread-safe. All events should be processed in the JavaFX thread.
Since:
1.3

  • Field Details

    • transformEnabled

      public final BooleanProperty transformEnabled
      Whether changes in the "objective to display" transforms should be propagated from source to target canvas. The default value is false. This property needs to be enabled explicitly by caller if desired.
      See Also:

    • cursorEnabled

      public final BooleanProperty cursorEnabled
      Whether mouse position in source canvas should be shown by a cursor in the target canvas. The default value is false. This property needs to be enabled explicitly by caller if desired.

  • Constructor Details

    • GestureFollower

      public GestureFollower(MapCanvas source, MapCanvas target)
      Creates a new listener for synchronizing "objective to display" transform changes and cursor position between the specified canvas. This is a unidirectional binding: changes in source are applied on target, but not the converse.

      Caller needs to register listeners by a call to the Canvas­Follower​.initialize() method. This is not done automatically by this constructor for allowing users to control when to start listening to source change events.

      Parameters:
      source - the canvas which is the source of zoom, pan or rotation events.
      target - the canvas on which to apply the changes of zoom, pan or rotation.
      Throws:
      Illegal­Argument­Exception - if source and target are the same map canvas.

  • Method Details

    • getSourceDisplayPOI

      public Optional<Point2D> getSourceDisplayPOI()
      Returns the position for the mouse cursor in the source canvas if that position is known. This information is used when the source and target canvases do not use the same CRS. Gesture­Follower tries to transform the canvas views in such a way that the "real world" change is the same for both canvas at that location.

      The returned value is "live"; it may change with mouse and gesture events. Callers should not modify that value, and copy it if they need to keep it.

      Overrides:
      get­Source­Display­POI in class Canvas­Follower
      Returns:
      mouse position in source canvas where displacements, zooms and rotations applied on the source canvas should be mirrored exactly on the target canvas.

    • handle

      public void handle(MouseEvent event)
      Invoked when the mouse position changed. This method should be invoked only if cursor­Enabled is true (this is not verified by this method).
      Specified by:
      handle in interface Event­Handler<Mouse­Event>
      Parameters:
      event - the enter, exit or move event.

    • filter

      protected boolean filter(TransformChangeEvent event)
      Returns true if this listener should replicate the following changes on the target canvas. This implementation returns true if the transform reason is Transform­Change­Event​.Reason​.INTERIM. It allows immediate feedback to users without waiting for the background thread to complete the rendering.
      Overrides:
      filter in class Canvas­Follower
      Parameters:
      event - a transform change event that occurred on the source canvas.
      Returns:
      whether to replicate that change on the target canvas.

    • transformedSource

      protected void transformedSource(TransformChangeEvent event)
      Invoked after the source "objective to display" transform has been updated. This implementation adjusts the cursor position for compensating the relative change in mouse position.

      Details

      If the map moved in the source canvas without a change of mouse cursor position (for example if the user navigates using the keyboard), then the mouse position changed relatively to the map, so the cursor position on the target canvas needs to be updated accordingly. This is a temporary change applied until the next Mouse­Event gives us new mouse coordinates relative to the map.
      Overrides:
      transformed­Source in class Canvas­Follower
      Parameters:
      event - the change which has been applied on the CanvasFollower.source canvas.

    • dispose

      public void dispose()
      Removes all listeners registered by this Gesture­Follower instance. This method should be invoked when Gesture­Follower is no longer needed, in order to avoid memory leak.
      Specified by:
      dispose in interface Disposable
      Overrides:
      dispose in class Canvas­Follower
      See Also: