Class StatusBar

All Implemented Interfaces:
Event­Listener, Event­Handler<Mouse­Event>, Localized

public class StatusBar extends Widget implements EventHandler<MouseEvent>
A status bar showing geographic or projected coordinates under mouse cursor. The number of fraction digits is adjusted according pixel resolution for each coordinate to format. Other components such as error message may also be shown.

Since the main Status­Bar job is to listen to mouse events for updating coordinates, this class implements Event­Handler directly. Status­Bar can be registered as a listener using the following methods:

  • Node​.set­On­Mouse­Entered(Event­Handler) for showing the coordinate values when the mouse enters the region of interest.
  • Node​.set­On­Mouse­Exited(Event­Handler) for hiding the coordinate values when the mouse exits the region of interest.
  • Node​.set­On­Mouse­Moved(Event­Handler) for updating the coordinate values when the mouse moves inside the region of interest.
Alternatively users can omit some or all above listener registrations and invoke set­Local­Coordinates(double, double) explicitly instead.

Defined in the sis-javafx module

  • Field Details

    • localToObjectiveCRS

      public final ObjectProperty<MathTransform> localToObjectiveCRS
      Conversion from local coordinates to geographic or projected coordinates of rendered data. The local coordinates are the coordinates of the JavaFX view, as given for example in Mouse­Event The objective coordinates are geographic or projected coordinates of rendered data, ignoring all CRS changes that may result from user selecting a different CRS in the contextual menu. Consequently while this transform is often the conversion from pixel coordinates to the coordinates shown in this status bar, this is not always the case.

      This transform shall never be null. It is initially an identity transform and is modified by apply­Canvas­Geometry(Grid­Geometry). The transform is usually (but not necessarily) affine and should have no inaccuracy (ignoring rounding error). This is normally the inverse of canvas objective to display transform, but temporary mismatches may exist during gesture events such as pans, zooms and rotations.

      If this transform is set to a new value, the given transform must have the same number of source and target dimensions than the previous value (if a change in the number of dimension is desired, use apply­Canvas­Geometry(Grid­Geometry) instead). The status bar is updated as if the new conversion was applied before any CRS changes resulting from user selecting a different CRS in the contextual menu. Note however that any specified transform may be overwritten if some canvas gesture events happen later; setting an explicit transform is more useful when this Status­Bar is not associated to a Map­Canvas (for example it may be used with a Grid­View instead).

      API note: We do not provide getter/setter for this property; use Writable­Object­Value​.set(Object) directly instead. We omit the "Property" suffix for making this operation more natural.
      See Also:
    • positionReferenceSystem

      public final ReadOnlyObjectProperty<ReferenceSystem> positionReferenceSystem
      The reference systems used by the coordinates shown in this status bar. This is initially the objective CRS, but may become different if the user selects another reference system through contextual menu.
      API note: We do not provide getter method for this property; use Observable­Object­Value​.get() directly instead. We omit the "Property" suffix for making this operation more natural.
      See Also:
    • position

      protected final Label position
      The label where to format the cursor position, either as coordinate values or other representations. The text is usually the result of formatting coordinate values as numerical values, but may also be other representations such as Military Grid Reference System (MGRS) codes.
      See Also:
    • sampleValuesProvider

      public final ObjectProperty<ValuesUnderCursor> sampleValuesProvider
      The object providing sample values under cursor position. The property value may be null if there are no sample values to format. If non-null, the text provided by this object will appear at the right of the coordinates.
      API note: We do not provide getter/setter for this property; use Writable­Object­Value​.set(Object) directly instead. We omit the "Property" suffix for making this operation more natural.
  • Constructor Details

    • StatusBar

      public StatusBar(RecentReferenceSystems systemChooser, MapCanvas... toTrack)
      Creates a new status bar for showing coordinates of mouse cursor position in a canvas. If the canvas argument is non-empty, this Status­Bar will show coordinates (usually geographic or projected) of mouse cursor position when the mouse is over that canvas. Note that in such case, the local­To­Objective­CRS property value will be overwritten at any time (for example every time that a gesture event such as pan, zoom or rotation happens).

      If the choices argument is non-null, user will be able to select different CRS using the contextual menu on the status bar.


      This constructor registers numerous listeners on canvas and system­Chooser. There is currently no unregistration mechanism. The Status­Bar instance is expected to exist as long as the Map­Canvas and Recent­Reference­Systems instances given to this constructor.

      Current implementation accepts only zero or one Map­Canvas. A future implementation may accept a larger amount of canvas for tracking many views with a single status bar (for example images over the same area but at different times).

      system­Chooser - the manager of reference systems chosen by user, or null if none.
      to­Track - the canvas that this status bar is tracking. Currently restricted to an array of length 0 or 1.
  • Method Details

    • getView

      public final Region getView()
      Returns the node to add to the scene graph for showing the status bar.
      Specified by:
      get­View in class Widget
      the JavaFX component to insert in a scene graph.
    • applyCanvasGeometry

      public void applyCanvasGeometry(GridGeometry geometry)
      Configures this status bar for showing coordinates in the CRS and with the resolution given by the specified grid geometry. The geometry properties are applied as below: All above properties are optional. The "local to objective CRS" conversion can be updated after this method call by setting the local­To­Objective­CRS property.
      geometry - geometry of the coverage shown in Map­Canvas, or null.
      See Also:
    • getLowestAccuracy

      public Quantity<Length> getLowestAccuracy()
      Returns the lowest value appended as "± accuracy" after the coordinate values. This is the last value specified to set­Lowest­Accuracy(Quantity).
      the lowest accuracy to append after the coordinate values, or null if none.
      See Also:
    • setLowestAccuracy

      public void setLowestAccuracy(Quantity<Length> accuracy)
      Specifies an uncertainty to append as "± accuracy" after the coordinate values. If user has selected (e.g. by contextual menu) a CRS causing the use of a coordinate transformation, then the accuracy actually shown by Status­Bar will be the greatest value between the accuracy specified to this method and the coordinate transformation accuracy.

      Note that the "± accuracy" text may be shown or hidden depending on the zoom level. If pixels on screen are larger than the accuracy, then the accuracy text is hidden.

      accuracy - the lowest accuracy to append after the coordinate values, or null if none.
      See Also:
    • getLocalCoordinates

      public Optional<Point2D> getLocalCoordinates()
      Returns the coordinates given to the last call to set­Local­Coordinates(double, double), or an empty value if those coordinates are not visible.
      the local coordinates currently shown in the status bar.
    • setLocalCoordinates

      public void setLocalCoordinates(double x, double y)
      Converts and formats the given pixel coordinates. Those coordinates will be automatically converted to geographic or projected coordinates if a "local to CRS" conversion is available.
      x - the x coordinate local to the view.
      y - the y coordinate local to the view.
      See Also:
    • handle

      public void handle(MouseEvent event)
      Updates the coordinates shown in the status bar with the value given by the mouse event. This method handles the following events:
      Specified by:
      handle in interface Event­Handler<Mouse­Event>
      event - the enter, exit or move event. For the convenience of programmatic calls, a null value is synonymous to a mouse exit event.
    • getErrorMessage

      public Optional<String> getErrorMessage()
      Returns the error message currently shown.
      the current error message, or an empty value if none.
    • setErrorMessage

      public void setErrorMessage(String text, Throwable details)
      Show or hide an error message on the status bar, optionally with a button showing details in a dialog box. The text argument specifies the message to show on the status bar. If text is null, the message will be taken from the details if non-null. If details is also null, then the error message will be hidden.
      text - the error message to show, or null if none.
      details - the exception that caused the error, or null if none.