Module org.apache.sis.gui
Package org.apache.sis.gui.map

# Class MapCanvasAWT

Object
Canvas
PlanarCanvas
MapCanvas
MapCanvasAWT

All Implemented Interfaces:
  `Localized`

Direct Known Subclasses:
  `CoverageCanvas`

public abstract class MapCanvasAWT extends MapCanvas
A canvas for maps to be rendered using Java2D from Abstract Window Toolkit. The map is rendered using Java2D in a background thread, then copied in a JavaFX image. Java2D is used for rendering the map because it may contain too many elements for a scene graph. After the map has been rendered, other JavaFX nodes can be put on top of the map, typically for controls by the user.

Since:
  1.1

- ## Property Summary

  ### Properties inherited from class MapCanvas

  `error, rendering`

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `protected static class`
  `MapCanvasAWT​.Renderer`
  A snapshot of `MapCanvasAWT` state to paint as an image.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected final ImageView`
  `image`
  The node where the rendered map will be shown.
  `final ObjectProperty<Insets>`
  `imageMargin`
  Number of additional pixels to paint on each sides of the image, outside the viewing area.

  ### Fields inherited from class MapCanvas

  `fixedPane, floatingPane`

  ### Fields inherited from class PlanarCanvas

  `BIDIMENSIONAL, objectiveToDisplay`

  ### Fields inherited from class Canvas

  `DISPLAY_BOUNDS_PROPERTY, OBJECTIVE_CRS_PROPERTY, OBJECTIVE_TO_DISPLAY_PROPERTY, POINT_OF_INTEREST_PROPERTY`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `MapCanvasAWT(Locale locale)`
  Creates a new canvas for JavaFX application.

- ## 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`
  `clear()`
  Clears the image and all intermediate buffer.
  `protected abstract MapCanvasAWT​.Renderer`
  `createRenderer()`
  Invoked in JavaFX thread for creating a renderer to be executed in a background thread.
  `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.
  `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.

  ### Methods inherited from class MapCanvas

  `clearError, errorOccurred, errorProperty, getObjectiveBounds, initialize, renderingProperty, requestRepaint, reset, runAfterRendering, setObjectiveBounds, setObjectiveToDisplay, toString, transformDisplayCoordinates, transformObjectiveCoordinates`

  ### Methods inherited from class PlanarCanvas

  `getDisplayBounds`

  ### Methods inherited from class Canvas

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

  ### Methods inherited from class Object

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

- ## Field Details

  - ### imageMargin

    public final ObjectProperty<Insets> imageMargin
    Number of additional pixels to paint on each sides of the image, outside the viewing area. Computing a larger image reduces the black borders that user sees during translations or during zoom out before the new image is repainted.

  - ### image

    protected final ImageView image
    The node where the rendered map will be shown. Its content is prepared in a background thread by `MapCanvasAWT​.Renderer`. Subclasses should not set the image content directly.

- ## Constructor Details

  - ### MapCanvasAWT

    public MapCanvasAWT(Locale locale)
    Creates a new canvas for JavaFX application.
    Parameters:
      `locale` - the locale to use for labels and some messages, or `null` for default.

- ## Method Details

  - ### createRenderer

    protected abstract MapCanvasAWT.Renderer createRenderer()
    Invoked in JavaFX thread for creating a renderer to be executed in a background thread. Subclasses should copy in this method all `MapCanvas` properties that the background thread will need for performing the rendering process.
    Specified by:
      `createRenderer` in class `MapCanvas`
    Returns:
      rendering process to be executed in background thread, or `null` if there is nothing to paint.

  - ### clear

    protected void clear()
    Clears the image and all intermediate buffer. Invoking this method may help to release memory when the map is no longer shown.

    #### Usage

    Overriding methods in subclasses should invoke `super​.clear()`. Other methods should generally not invoke this method directly, and use the following code instead:

        runAfterRendering(this::clear);

    Overrides:
      `clear` in class `MapCanvas`
    See Also:
      - `MapCanvas​.runAfterRendering(Runnable)`

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