Module org.apache.sis.portrayal
Package org.apache.sis.portrayal

# Class TransformChangeEvent

Object
EventObject
PropertyChangeEvent
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
See Also:
  - `Canvas​.OBJECTIVE_TO_DISPLAY_PROPERTY`
  - Serialized Form

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static enum`
  `TransformChangeEvent​.Reason`
  The reason why the "objective to display" transform changed.

- ## Field Summary

  ### Fields inherited from class EventObject

  `source`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `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.
  `TransformChangeEvent(Canvas source, LinearTransform oldValue, LinearTransform newValue, TransformChangeEvent​.Reason reason)`
  Creates a new event for a change of the "objective to display" property.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `LinearTransform`
  `getDisplayChange()`
  Returns the change from old display coordinates to new display coordinates.
  `Optional<AffineTransform>`
  `getDisplayChange2D()`
  Returns the change in display coordinates as a Java2D affine transform.
  `LinearTransform`
  `getNewValue()`
  Gets the new "objective to display" transform.
  `LinearTransform`
  `getObjectiveChange()`
  Returns the change from old objective coordinates to new objective coordinates.
  `Optional<AffineTransform>`
  `getObjectiveChange2D()`
  Returns the change in objective coordinates as a Java2D affine transform.
  `LinearTransform`
  `getOldValue()`
  Gets the old "objective to display" transform.
  `TransformChangeEvent​.Reason`
  `getReason()`
  Returns the reason why the "objective to display" transform changed.
  `Canvas`
  `getSource()`
  Returns the canvas on which this event initially occurred.

  ### Methods inherited from class PropertyChangeEvent

  `getPropagationId, getPropertyName, setPropagationId, toString`

  ### Methods inherited from class Object

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

- ## 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

  - ### 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:
      - `getObjectiveChange()`

  - ### 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:
      - `getDisplayChange()`