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

Class StatusBar

Object
Widget
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:

Alternatively, users can omit some or all above listener registrations and invoke set­Local­Coordinates(double, double) explicitly instead.
Since:
1.1

  • 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 transform 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:

    • lowestAccuracy

      public final ObjectProperty<Quantity<Length>> lowestAccuracy
      Specifies a minimal uncertainty to append as "± accuracy" after the coordinate values. This uncertainty can be caused for example by a coordinate transformation applied on data before rendering in the canvas.

      Note that Status­Bar maintains also its own uncertainty, which can be caused by transformation from objective CRS to the reference system used in this status bar. Such transformations happen when users select a CRS on the status bar (e.g. using the contextual menu) which is different than the canvas objective CRS. In such case we have two sources of stochastic errors: one internal to this status bar and one having causes external to this status bar. This lowest­Accuracy property is for specifying the latter.

      The accuracy actually shown by Status­Bar will be the greatest value between the accuracy specified in this property and the accuracy computed internally by Status­Bar. 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.

      Since:
      1.3
      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)
      Creates a new status bar for showing coordinates of mouse cursor position in a canvas. If track(Canvas) is invoked, then 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 system­Chooser argument is non-null, user will be able to select different CRS using the contextual menu on the status bar.

      Limitations

      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.
      Parameters:
      system­Chooser - the manager of reference systems chosen by user, or null if none.

  • Method Details

    • track

      public void track(MapCanvas canvas)
      Registers listeners on the specified canvas for tracking mouse movements. After this method call, this Status­Bar will show coordinates (usually geographic or projected) of mouse cursor position when the mouse is over that canvas. The local­To­Objective­CRS property value may be overwritten at any time, for example after each gesture event such as pan, zoom or rotation.

      Limitations

      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).
      Parameters:
      canvas - the canvas that this status bar is tracking.
      Since:
      1.3

    • 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
      Returns:
      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.
      Parameters:
      geometry - geometry of the coverage shown in Map­Canvas, or null.
      See Also:

    • applyCanvasGeometry

      public void applyCanvasGeometry(GridGeometry geometry, GridExtent sliceExtent, int xdim, int ydim)
      Configures this status bar for showing coordinates of a slice of a grid coverage. This method is useful for tracking the pixel coordinates of an image obtained by a call to Grid­Coverage​.render(Grid­Extent). By render(Grid­Extent) contract, the Rendered­Image pixel coordinates are relative to the requested Grid­Extent. Consequently, we need to translate the grid coordinates so that the request coordinates start at zero. This method handles that translation.
      Parameters:
      geometry - geometry of the coverage which produced the Rendered­Image to track, or null.
      slice­Extent - the extent specified in call to Grid­Coverage​.render(Grid­Extent) (can be null).
      xdim - the grid dimension where to assign the values of x pixel coordinates.
      ydim - the grid dimension where to assign the values of y pixel coordinates.
      Since:
      1.3

    • getXYDimensions

      public final int[] getXYDimensions()
      Returns the indices of x and y coordinate values in a grid coordinate tuple. They are the indices where to assign the values of the x and y arguments in calls to set­Local­Coordinates(x,y).

      The default value is {0,1}, i.e. the 2 first dimensions in a coordinate tuple. The value can be changed by call to apply­Canvas­Geometry(Grid­Geometry, Grid­Extent, int, int).

      Returns:
      indices of x and y coordinate values in a grid coordinate tuple.
      Since:
      1.3

    • 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.
      Returns:
      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.

      Supplemental dimensions

      If local coordinates have more than 2 dimensions, then the given (x,y) values will be assigned to the dimensions specified by get­XYDimensions(). Coordinates in all other dimensions will have the values given by Grid­Extent​.get­Point­Of­Interest(Pixel­In­Cell) from the extent of the grid geometry given to apply­Canvas­Geometry(Grid­Geometry).
      Parameters:
      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>
      Parameters:
      event - the enter, exit or move event. For the convenience of programmatic calls, a null value is synonymous to a mouse exit event.

    • getMessage

      public Optional<String> getMessage()
      Returns the message currently shown. It may be an error message or an informative message.
      Returns:
      the current message, or an empty value if none.
      Since:
      1.3

    • setInfoMessage

      public void setInfoMessage(String text)
      Shows or hides an informative message on the status bar. The message should be temporary, for example for telling that a loading is in progress.
      Parameters:
      text - the message to show, or null if none.
      Since:
      1.3

    • setErrorMessage

      public void setErrorMessage(String text, Throwable details)
      Shows or hides 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.
      Parameters:
      text - the error message to show, or null if none.
      details - the exception that caused the error, or null if none.