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

# Class PlanarCanvas

Object
Canvas
PlanarCanvas

All Implemented Interfaces:
  `Localized`

Direct Known Subclasses:
  `MapCanvas`

public abstract class PlanarCanvas extends Canvas
A canvas for two-dimensional display device using a Cartesian coordinate system. Data are reduced to a two-dimensional slice before to be displayed.

## Multi-threading

`PlanarCanvas` is not thread-safe. Synchronization, if desired, must be done by the caller. Another common strategy is to interact with `PlanarCanvas` from a single thread, for example the Swing or JavaFX event queue.

Since:
  1.1

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected static final int`
  `BIDIMENSIONAL`
  The 2 constant for identifying code specific to bi-dimensional case.
  `protected final AffineTransform`
  `objectiveToDisplay`
  The conversion from objective CRS to the display coordinate system as a Java2D affine transform.

  ### Fields inherited from class Canvas

  `DISPLAY_BOUNDS_PROPERTY, OBJECTIVE_CRS_PROPERTY, OBJECTIVE_TO_DISPLAY_PROPERTY, POINT_OF_INTEREST_PROPERTY`

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `PlanarCanvas(Locale locale)`
  Creates a new two-dimensional canvas.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `final void`
  `addPropertyChangeListener(String propertyName, PropertyChangeListener listener)`
  Registers a listener for the property of the given name.
  `protected void`
  `firePropertyChange(PropertyChangeEvent event)`
  Notifies all registered listeners that a property changed its value.
  `protected void`
  `firePropertyChange(String propertyName, Object oldValue, Object newValue)`
  Notifies all registered listeners that a property of the given name changed its value.
  `Envelope2D`
  `getDisplayBounds()`
  Returns the size and location of the display device.
  `protected final boolean`
  `hasPropertyChangeListener(String propertyName)`
  Returns `true` if the given property has at least one listener.
  `final void`
  `removePropertyChangeListener(String propertyName, PropertyChangeListener listener)`
  Unregisters a property listener.
  `void`
  `transformDisplayCoordinates(AffineTransform after)`
  Updates the objective to display transform as if the given transform was applied after the current transform.
  `void`
  `transformObjectiveCoordinates(AffineTransform before)`
  Updates the objective to display transform as if the given transform was applied before the current transform.

  ### Methods inherited from class Canvas

  `getDisplayCRS, getGeographicArea, getGridGeometry, getLocale, getObjectiveCRS, getObjectiveToDisplay, getPointOfInterest, getSpatialResolution, setDisplayBounds, setGridGeometry, setObjectiveCRS, setObjectiveToDisplay, setPointOfInterest`

  ### Methods inherited from class Object

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

- ## Field Details

  - ### BIDIMENSIONAL

    protected static final int BIDIMENSIONAL
    The 2 constant for identifying code specific to bi-dimensional case.
    See Also:
      - Constant Field Values

  - ### objectiveToDisplay

    protected final AffineTransform objectiveToDisplay
    The conversion from objective CRS to the display coordinate system as a Java2D affine transform. This transform will be modified in-place when user applies zoom, translation or rotation on the view area. Subclasses should generally not modify this affine transform directly; invoke one of the `transformFooCoordinates(AffineTransform)` methods instead.
    See Also:
      - `Canvas​.getObjectiveToDisplay()`
      - `transformObjectiveCoordinates(AffineTransform)`
      - `transformDisplayCoordinates(AffineTransform)`

- ## Constructor Details

  - ### PlanarCanvas

    protected PlanarCanvas(Locale locale)
    Creates a new two-dimensional canvas.
    Parameters:
      `locale` - the locale to use for labels and some messages, or `null` for default.

- ## Method Details

  - ### getDisplayBounds

    public Envelope2D getDisplayBounds()
    Returns the size and location of the display device. The unit of measurement is `Units​.PIXEL` and coordinate values are usually (but not necessarily) integers.

    This value may be `null` on newly created `Canvas`, before data are added and canvas is configured. It should not be `null` anymore once a `Canvas` is ready for displaying. The returned envelope is a copy; display changes happening after this method invocation will not be reflected in the returned envelope.

    Overrides:
      `getDisplayBounds` in class `Canvas`
    Returns:
      size and location of the display device in pixel coordinates.
    See Also:
      - `Canvas​.setDisplayBounds(Envelope)`

  - ### transformObjectiveCoordinates

    public void transformObjectiveCoordinates(AffineTransform before)
    Updates the objective to display transform as if the given transform was applied before the current transform. For example if the given `before` transform is a translation, then the translation vector is in units of the objective CRS (typically metres on the map).

    This method does nothing if the given transform is identity. Otherwise an "objectiveToDisplay" property change event will be sent with the `TransformChangeEvent​.Reason​.OBJECTIVE_NAVIGATION` reason after the change became effective. Depending on the implementation, the change may not take effect immediately. For example, subclasses may do the rendering in a background thread.

    Parameters:
      `before` - coordinate conversion to apply before the current objective to display transform.
    See Also:
      - `TransformChangeEvent​.getObjectiveChange()`

  - ### transformDisplayCoordinates

    public void transformDisplayCoordinates(AffineTransform after)
    Updates the objective to display transform as if the given transform was applied after the current transform. For example if the given `after` transform is a translation, then the translation vector is in pixel units.

    This method does nothing if the given transform is identity. Otherwise an "objectiveToDisplay" property change event will be sent with the `TransformChangeEvent​.Reason​.DISPLAY_NAVIGATION` reason after the change became effective. Depending on the implementation, the change may not take effect immediately. For example, subclasses may do the rendering in a background thread.

    Parameters:
      `after` - coordinate conversion to apply after the current objective to display transform.
    See Also:
      - `TransformChangeEvent​.getDisplayChange()`

  - ### addPropertyChangeListener

    public final void addPropertyChangeListener(String propertyName, PropertyChangeListener listener)
    Registers a listener for the property of the given name. The listener will be notified every time that the property of the given name got a new value. If the same listener is registered twice for the same property, then it will be notified twice (this method does not perform duplication checks).
    Parameters:
      `propertyName` - name of the property to listen (should be one of the `*_PROPERTY` constants).
      `listener` - property listener to register.

  - ### removePropertyChangeListener

    public final void removePropertyChangeListener(String propertyName, PropertyChangeListener listener)
    Unregisters a property listener. The given `propertyName` should be the name used during listener registration. If the specified listener is not registered for the named property, then nothing happen. If the listener has been registered twice, then only one registration is removed (one registration will remain).
    Parameters:
      `propertyName` - name of the listened property.
      `listener` - property listener to unregister.

  - ### hasPropertyChangeListener

    protected final boolean hasPropertyChangeListener(String propertyName)
    Returns `true` if the given property has at least one listener.
    Parameters:
      `propertyName` - name of the property to test.
    Returns:
      `true` if the given property has at least one listener.

  - ### firePropertyChange

    protected void firePropertyChange(String propertyName, Object oldValue, Object newValue)
    Notifies all registered listeners that a property of the given name changed its value. The change event source will be `this`. It is caller responsibility to verify that the old and new values are different (this method does not check for equality).
    Parameters:
      `propertyName` - name of the property that changed its value.
      `oldValue` - the old property value (may be `null`).
      `newValue` - the new property value (may be `null`).
    See Also:
      - `PropertyChangeEvent`
      - `PropertyChangeListener`

  - ### firePropertyChange

    protected void firePropertyChange(PropertyChangeEvent event)
    Notifies all registered listeners that a property changed its value. It is caller responsibility to verify that the event source and property name are valid.
    Parameters:
      `event` - the event to forward. Cannot be null.
    See Also:
      - `PropertyChangeEvent`
      - `PropertyChangeListener`