Class TransformChangeEvent

java.lang.Object
java.util.EventObject
java.beans.PropertyChangeEvent
org.apache.sis.portrayal.TransformChangeEvent
All Implemented Interfaces:
Serializable

public class TransformChangeEvent extends PropertyChangeEvent
A change in the "objective to display" transform that Canvas uses for rendering data. That transform is updated frequently following gestures events such as zoom, translation or rotation. All events fired by Canvas for the "objectiveToDisplay" property are instances of this class. This specialization provides methods for computing the difference between the old and new state.

Multi-threading

This class is not thread-safe. All listeners should process this event in the same thread.
Since:
1.3
Version:
1.3
See Also:
  • Field Details

  • Constructor Details

    • TransformChangeEvent

      public TransformChangeEvent(Canvas source, LinearTransform oldValue, LinearTransform newValue, TransformChangeEvent.Reason reason)
      Creates a new event for a change of the "objective to display" property. The old and new transforms should not be null, except on initialization or for lazy computation: a null newValue means to take the value from Canvas.getObjectiveToDisplay() when needed.
      Parameters:
      source - the canvas that fired the event.
      oldValue - the old "objective to display" transform, or null if none.
      newValue - the new transform, or null for lazy computation.
      reason - the reason why the "objective to display" transform changed..
      Throws:
      IllegalArgumentException - if source is null.
    • TransformChangeEvent

      public TransformChangeEvent(Canvas source, LinearTransform oldValue, LinearTransform newValue, AffineTransform objective, AffineTransform display, TransformChangeEvent.Reason reason)
      Creates a new event for an incremental change of the "objective to display" property. The incremental change can be specified by the objective and/or the display argument. Usually only one of those two arguments is non-null.
      Parameters:
      source - the canvas that fired the event.
      oldValue - the old "objective to display" transform, or null if none.
      newValue - the new transform, or null for lazy computation.
      objective - the incremental change in objective coordinates, or null for lazy computation.
      display - the incremental change in display coordinates, or null for lazy computation.
      reason - the reason why the "objective to display" transform changed..
      Throws:
      IllegalArgumentException - if source is null.
  • Method Details

    • isSameSource

      final boolean isSameSource(Canvas source)
      Quick and non-overrideable check about whether the specified source is the source of this event.
    • getSource

      public Canvas getSource()
      Returns the canvas on which this event initially occurred.
      Overrides:
      getSource in class EventObject
      Returns:
      the canvas on which this event initially occurred.
    • getReason

      public TransformChangeEvent.Reason getReason()
      Returns the reason why the "objective to display" transform changed. It may be because of canvas initialization, or an adjustment for a change of CRS without change in the viewing area, or a navigation for viewing a different area.
      Returns:
      the reason why the "objective to display" transform changed.
    • getOldValue

      public LinearTransform getOldValue()
      Gets the old "objective to display" transform.
      Overrides:
      getOldValue in class PropertyChangeEvent
      Returns:
      the old "objective to display" transform, or null if none.
    • getNewValue

      public LinearTransform getNewValue()
      Gets the new "objective to display" transform. It should be the current value of Canvas.getObjectiveToDisplay().
      Overrides:
      getNewValue in class PropertyChangeEvent
      Returns:
      the new "objective to display" transform.
    • getObjectiveChange

      public LinearTransform getObjectiveChange()
      Returns the change from old objective coordinates to new objective coordinates. When the "objective to display" transform changed (e.g. because the user did a zoom, translation or rotation), this method expresses how the "real world" coordinates (typically in metres) of any point on the screen changed.
      Example: if the map is shifted 10 metres toward the right side of the canvas, then (assuming no rotation or axis flip) the x translation coefficient of the change is +10 (same sign than getDisplayChange()). Note that it may correspond to any amount of pixels, depending on the zoom factor.
      The getObjectiveChange2D() method gives the same transform as a Java2D object. That change can be replicated on another canvas by giving the transform to PlanarCanvas.transformObjectiveCoordinates(AffineTransform).
      Returns:
      the change in objective coordinates. Usually not null, unless one of the canvas is initializing or has a non-invertible transform.
    • getDisplayChange

      public LinearTransform getDisplayChange()
      Returns the change from old display coordinates to new display coordinates. When the "objective to display" transform changed (e.g. because the user did a zoom, translation or rotation), this method expresses how the display coordinates (typically pixels) of any given point on the map changed.
      Example: if the map is shifted 10 pixels toward the right side of the canvas, then (assuming no rotation or axis flip) the x translation coefficient of the change is +10: the points on the map which were located at x=0 pixel before the change are now located at x=10 pixels after the change.
      The getDisplayChange2D() method gives the same transform as a Java2D object. That change can be replicated on another canvas by giving the transform to PlanarCanvas.transformDisplayCoordinates(AffineTransform).
      Returns:
      the change in display coordinates. Usually not null, unless one of the canvas is initializing or has a non-invertible transform.
    • getObjectiveChange2D

      public Optional<AffineTransform> getObjectiveChange2D()
      Returns the change in objective coordinates as a Java2D affine transform. This method is suitable for two-dimensional canvas only. For performance reason, it does not clone the returned transform.
      Returns:
      the change in objective coordinates. Do not modify.
      See Also:
    • getDisplayChange2D

      public Optional<AffineTransform> getDisplayChange2D()
      Returns the change in display coordinates as a Java2D affine transform. This method is suitable for two-dimensional canvas only. For performance reason, it does not clone the returned transform.
      Returns:
      the change in display coordinates. Do not modify.
      See Also:
    • canNotCompute

      private void canNotCompute(String method, Exception e)
      Invoked when a change cannot be computed. It should never happen because "objective to display" transforms should always be invertible. If this error nevertheless happens, consider the change as a missing optional information.