# Class StatusBar

Object
Widget
StatusBar

All Implemented Interfaces:
  `EventListener`, `EventHandler<MouseEvent>`, `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 `StatusBar` job is to listen to mouse events for updating coordinates, this class implements `EventHandler` directly. `StatusBar` can be registered as a listener using the following methods:

- `Node​.setOnMouseEntered(EventHandler)` for showing the coordinate values when the mouse enters the region of interest.
- `Node​.setOnMouseExited(EventHandler)` for hiding the coordinate values when the mouse exits the region of interest.
- `Node​.setOnMouseMoved(EventHandler)` 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 `setLocalCoordinates(double, double)` explicitly instead.

Since:
  1.1

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `final ObjectProperty<MathTransform>`
  `localToObjectiveCRS`
  Conversion from local coordinates to geographic or projected coordinates of rendered data.
  `final ObjectProperty<Quantity<Length>>`
  `lowestAccuracy`
  Specifies a minimal uncertainty to append as "± accuracy" after the coordinate values.
  `protected final Label`
  `position`
  The label where to format the cursor position, either as coordinate values or other representations.
  `final ReadOnlyObjectProperty<ReferenceSystem>`
  `positionReferenceSystem`
  The reference systems used by the coordinates shown in this status bar.
  `final ObjectProperty<ValuesUnderCursor>`
  `sampleValuesProvider`
  The object providing sample values under cursor position.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `StatusBar(RecentReferenceSystems systemChooser)`
  Creates a new status bar for showing coordinates of mouse cursor position in a canvas.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `applyCanvasGeometry(GridGeometry geometry)`
  Configures this status bar for showing coordinates in the CRS and with the resolution given by the specified grid geometry.
  `void`
  `applyCanvasGeometry(GridGeometry geometry, GridExtent sliceExtent, int xdim, int ydim)`
  Configures this status bar for showing coordinates of a slice of a grid coverage.
  `Optional<Point2D>`
  `getLocalCoordinates()`
  Returns the coordinates given to the last call to `setLocalCoordinates(double, double)`, or an empty value if those coordinates are not visible.
  `Optional<String>`
  `getMessage()`
  Returns the message currently shown.
  `final Region`
  `getView()`
  Returns the node to add to the scene graph for showing the status bar.
  `final int[]`
  `getXYDimensions()`
  Returns the indices of x and y coordinate values in a grid coordinate tuple.
  `void`
  `handle(MouseEvent event)`
  Updates the coordinates shown in the status bar with the value given by the mouse event.
  `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.
  `void`
  `setInfoMessage(String text)`
  Shows or hides an informative message on the status bar.
  `void`
  `setLocalCoordinates(double x, double y)`
  Converts and formats the given pixel coordinates.
  `void`
  `track(MapCanvas canvas)`
  Registers listeners on the specified canvas for tracking mouse movements.

  ### Methods inherited from class Widget

  `getLocale`

  ### Methods inherited from class Object

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

- ## 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 `MouseEvent` 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 `applyCanvasGeometry(GridGeometry)`. 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 `applyCanvasGeometry(GridGeometry)` 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 `StatusBar` is not associated to a `MapCanvas` (for example it may be used with a `GridView` instead).

    #### API note

    We do not provide getter/setter for this property; use `WritableObjectValue​.set(Object)` directly instead. We omit the "Property" suffix for making this operation more natural.
    See Also:
      - `Canvas​.getObjectiveCRS()`
      - `Canvas​.getObjectiveToDisplay()`

  - ### 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 `ObservableObjectValue​.get()` directly instead. We omit the "Property" suffix for making this operation more natural.
    See Also:
      - `position`

  - ### 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 `StatusBar` 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 `lowestAccuracy` property is for specifying the latter.

    The accuracy actually shown by `StatusBar` will be the greatest value between the accuracy specified in this property and the accuracy computed internally by `StatusBar`. 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:
      - `CoordinateFormat​.setGroundAccuracy(Quantity)`

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

  - ### 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 `WritableObjectValue​.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 `StatusBar` will show coordinates (usually geographic or projected) of mouse cursor position when the mouse is over that canvas. Note that in such case, the `localToObjectiveCRS` 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 `systemChooser` 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 `systemChooser`. There is currently no unregistration mechanism. The `StatusBar` instance is expected to exist as long as the `MapCanvas` and `RecentReferenceSystems` instances given to this constructor.
    Parameters:
      `systemChooser` - 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 `StatusBar` will show coordinates (usually geographic or projected) of mouse cursor position when the mouse is over that canvas. The `localToObjectiveCRS` 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 `MapCanvas`. A future implementation may accept a larger number 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:
      `getView` 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:
    - `GridGeometry​.getCoordinateReferenceSystem()` defines the CRS of the coordinates to format.
    - `GridGeometry​.getGridToCRS(PixelInCell​.CELL_CENTER)` defines the conversion from coordinate values local to the canvas to coordinate values in the CRS (the local to objective CRS conversion).
    - `GridGeometry​.getExtent()` provides the view size in pixels, used for estimating a resolution.
    - `GridGeometry​.getResolution(boolean)` is also used for estimating a resolution.
    All above properties are optional. The "local to objective CRS" conversion can be updated after this method call by setting the `localToObjectiveCRS` property.
    Parameters:
      `geometry` - geometry of the coverage shown in `MapCanvas`, or `null`.
    See Also:
      - `Canvas​.getGridGeometry()`

  - ### 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 `GridCoverage​.render(GridExtent)`. By `render(GridExtent)` contract, the `RenderedImage` pixel coordinates are relative to the requested `GridExtent`. 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 `RenderedImage` to track, or `null`.
      `sliceExtent` - the extent specified in call to `GridCoverage​.render(GridExtent)` (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 `setLocalCoordinates(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 `applyCanvasGeometry(GridGeometry, GridExtent, 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 `setLocalCoordinates(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 `getXYDimensions()`. Coordinates in all other dimensions will have the values given by `GridExtent​.getPointOfInterest(PixelInCell)` from the extent of the grid geometry given to `applyCanvasGeometry(GridGeometry)`.
    Parameters:
      `x` - the x coordinate local to the view.
      `y` - the y coordinate local to the view.
    See Also:
      - `handle(MouseEvent)`

  - ### 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:
    - `MouseEvent​.MOUSE_ENTERED`: show the coordinates.
    - `MouseEvent​.MOUSE_EXITED`: hide the coordinates.
    - `MouseEvent​.MOUSE_MOVED`: delegate to `setLocalCoordinates(double, double)`.
    Specified by:
      `handle` in interface `EventHandler<MouseEvent>`
    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.