# Class PlanarCanvas

Object
Observable
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
  `Envelope2D`
  `getDisplayBounds()`
  Returns the size and location of the display device.
  `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 Observable

  `addPropertyChangeListener, firePropertyChange, firePropertyChange, hasPropertyChangeListener, removePropertyChangeListener`

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