Class MapCanvas

All Implemented Interfaces:
Localized
Direct Known Subclasses:
Map­Canvas­AWT

public abstract class MapCanvas extends PlanarCanvas
A canvas for maps to be rendered on screen in a JavaFX application. The map may be an arbitrary JavaFX node, typically an Image­View or Canvas, which must be supplied by subclasses. This base class provides handlers for keyboard, mouse, track pad or touch screen events such as pans, zooms and rotations. The keyboard actions are:
Keyboard actions
Key Action
Move view to the right
Move view to the left
Move view to the top
Move view to the bottom
⎇ + ⇨ Rotate clockwise
⎇ + ⇦ Rotate anticlockwise
Page down Zoom in
Page up Zoom out
Home Reset
Ctrl + above Above actions as a smaller translation, zoom or rotation

Subclassing

Implementations need to add at least one JavaFX node in the floating­Pane list of children. Map rendering involves the following steps:
  1. create­Renderer() is invoked in the JavaFX thread. That method shall take a snapshot of every information needed for performing the rendering in background.
  2. Map­Canvas​.Renderer​.render() is invoked in a background thread. That method creates or updates the nodes to show in this Map­Canvas but without interacting with the canvas yet.
  3. Map­Canvas​.Renderer​.commit(Map­Canvas) is invoked in the JavaFX thread. The nodes prepared by render() can be transferred to floating­Pane in that method.
Since:
1.1

Defined in the sis-javafx module

  • Property Details

    • rendering

      public final ReadOnlyBooleanProperty renderingProperty
      Returns a property telling whether a rendering is in progress. This property become true when this Map­Canvas is about to start a background thread for performing a rendering, and is reset to false after this Map­Canvas has been updated with new rendering result.
      See Also:
    • error

      public final ReadOnlyObjectProperty<Throwable> errorProperty
      Returns a property giving the exception or error that occurred during last rendering operation. The property value is reset to null when a rendering operation completed successfully.
      See Also:
  • Field Details

    • floatingPane

      protected final Pane floatingPane
      The pane showing the map and any other JavaFX nodes to scale and translate together with the map. This pane is initially empty; subclasses should add nodes (canvas, images, shapes, texts, etc.) into the Pane​.get­Children() list. All children must specify their coordinates in units relative to the pane (absolute layout). Those coordinates can be computed from real world coordinates by Planar­Canvas​.objective­To­Display.

      This pane contains an Affine transform which is updated by user gestures such as pans, zooms or rotations. Visual positions of all children move together in response to user's gesture, thus giving an appearance of pane floating around. Changes in floating­Pane affine transform are temporary; they are applied for producing immediate visual feedback while the map is recomputed in a background thread. Once calculation is completed and the content of this pane has been updated, the floating­Pane Affine transform is reset to identity.

    • fixedPane

      protected final StackPane fixedPane
      The pane showing the map and other JavaFX nodes to keep at fixed position regardless pans, zooms or rotations applied on the map. This pane contains at least the floatingPane (which itself contains the map), but more children (shapes, texts, controls, etc.) can be added by subclasses into the Pane​.get­Children() list.
  • Constructor Details

    • MapCanvas

      public MapCanvas(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

    • reset

      public void reset()
      Resets the map view to its default zoom level and default position with no rotation. Contrarily to clear(), this method does not remove the map content.
    • setObjectiveBounds

      protected void setObjectiveBounds(Envelope visibleArea)
      Sets the data bounds to use for computing the initial value of Planar­Canvas​.objective­To­Display. Invoking this method also sets the objective CRS of this canvas to the CRS of given envelope.

      This method should be invoked only when new data have been loaded, or when the caller wants to discard any zoom or translation and reset the view to the given bounds. This method does not cause new repaint event; request­Repaint() must be invoked by the caller if desired.

      Parameters:
      visible­Area - bounding box in (new) objective CRS of the initial area to show, or null if unknown (in which case an identity transform will be set).
      See Also:
    • createRenderer

      protected abstract MapCanvas.Renderer createRenderer()
      Invoked in JavaFX thread for creating a renderer to be executed in a background thread. Subclasses shall copy in this method all Map­Canvas properties that the background thread will need for performing the rendering process.
      Returns:
      rendering process to be executed in background thread, or null if there is nothing to paint.
    • requestRepaint

      public final void requestRepaint()
      Requests the map to be rendered again, possibly with new data. Invoking this method does not necessarily causes the repaint process to start immediately. The request will be queued and executed at an arbitrary (short) time later.
    • renderingProperty

      public final ReadOnlyBooleanProperty renderingProperty()
      Returns a property telling whether a rendering is in progress. This property become true when this Map­Canvas is about to start a background thread for performing a rendering, and is reset to false after this Map­Canvas has been updated with new rendering result.
      Returns:
      a property telling whether a rendering is in progress.
    • errorProperty

      public final ReadOnlyObjectProperty<Throwable> errorProperty()
      Returns a property giving the exception or error that occurred during last rendering operation. The property value is reset to null when a rendering operation completed successfully.
      Returns:
      a property giving the exception or error that occurred during last rendering operation.
    • clearError

      protected final void clearError()
      Clears the error message in status bar.
    • errorOccurred

      protected void errorOccurred(Throwable ex)
      Sets the error property to the given value. This method is provided for subclasses that perform processing outside the Map­Canvas​.Renderer. It does not need to be invoked if the error occurred during the rendering process.

      If the error property already has a value, then the new error will be to the current error as a suppressed exception. The error property is cleared when a rendering operation completed successfully.

      Parameters:
      ex - the exception that occurred (can not be null).
    • runAfterRendering

      protected boolean runAfterRendering(Runnable task)
      Registers a task to execute after the background thread finished its current rendering task. This method shall be invoked in JavaFX thread. If there is a rendering in progress at the time this method is invoked, then the given task is queued for execution in JavaFX thread after the rendering finished. Otherwise the given task is executed immediately.

      Exceptions are propagated if the given task has been executed immediately, or logged if execution has been deferred.

      This method is useful for subclasses when modifying the Map­Canvas state during a rendering process may cause inconsistent state.

      Parameters:
      task - the task to execute.
      Returns:
      true if the task has been executed immediately, or false if it has been queued for later execution.
      Since:
      1.2
      See Also:
    • clear

      protected void clear()
      Removes map content and clears all properties of this canvas.

      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);
      See Also:
    • 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:
      property­Name - 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 property­Name 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:
      property­Name - name of the listened property.
      listener - property listener to unregister.
    • 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:
      property­Name - name of the property that changed its value.
      old­Value - the old property value (may be null).
      new­Value - the new property value (may be null).
      See Also:
    • 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. Can not be null.
      See Also: