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:

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

Since:

1.1

Field Summary

Fields

Modifier and Type	Field	Description
final Object­Property<Math­Transform>	local­To­Objective­CRS	Conversion from local coordinates to geographic or projected coordinates of rendered data.
final Object­Property<Quantity<Length>>	lowest­Accuracy	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 Read­Only­Object­Property<Reference­System>	position­Reference­System	The reference systems used by the coordinates shown in this status bar.
final Object­Property<Values­Under­Cursor>	sample­Values­Provider	The object providing sample values under cursor position.

Constructor Summary

Constructors

Constructor	Description
Status­Bar(Recent­Reference­Systems system­Chooser)	Creates a new status bar for showing coordinates of mouse cursor position in a canvas.

Method Summary

Modifier and Type	Method	Description
void	apply­Canvas­Geometry(Grid­Geometry geometry)	Configures this status bar for showing coordinates in the CRS and with the resolution given by the specified grid geometry.
void	apply­Canvas­Geometry(Grid­Geometry geometry, Grid­Extent slice­Extent, int xdim, int ydim)	Configures this status bar for showing coordinates of a slice of a grid coverage.
Optional<Point2D>	get­Local­Coordinates()	Returns the pixel coordinates from which the geospatial coordinates have been computed.
Optional<String>	get­Message()	Returns the message currently shown.
Observable­String­Value	get­Reference­System­Name()	Returns a property for the name of the reference system used by the coordinates.
Region	get­View()	Returns the encapsulated JavaFX component to add in a scene graph for making the status bar visible.
final int[]	get­XYDimensions()	Returns the indices of x and y coordinate values in a grid coordinate tuple.
void	handle(Mouse­Event event)	Updates the coordinates shown in the status bar with the value given by the mouse event.
void	set­Default­Message(String text, Tooltip tooltip)	Sets the default message to show when there is no error and no operation in progress.
void	set­Error­Message(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	set­Info­Message(String text)	Deprecated, for removal: This API element is subject to removal in a future version. Renamed set­Progress­Message(String).
void	set­Local­Coordinates(double x, double y)	Converts and formats the given pixel coordinates.
void	set­Progress­Message(String text)	Shows or hides a message for an operation in progress.
void	track(Map­Canvas canvas)	Registers listeners on the specified canvas for tracking mouse movements.

Methods inherited from class Widget

get­Locale

Modifier and Type	Method	Description
Locale	get­Locale()	Returns the locale for controls and messages.

Methods inherited from class Object

clone, equals, finalize, get­Class, hash­Code, notify, notify­All, to­String, 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 Mouse­Event. The objective coordinates are the (usually geographic or projected) coordinates of the image shown in the Map­Canvas or other control associated with this status bar. Objective coordinates are not necessarily the coordinates shown in the status bar, because another transformation step may happen if the user selected a different CRS in the contextual menu of the status bar.

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 the canvas's objective to display transform, but temporary mismatches may exist during gesture events such as pans, zooms and rotations.

This transform may change continuously as a result of gesture events such as zooms and pans. It is possible to set explicitly a value to this property, but the specified value may be overwritten by the next gesture event. Therefore, setting an explicit value is more useful when this status bar is not associated with a Map­Canvas. For example, it may be associated with a Grid­View instead).

Setting a value explicitly

If this transform is set to a new value, the given transform must have the same number of source and target dimensions as the previous value (if a change in the number of dimensions is desired, use apply­Canvas­Geometry(Grid­Geometry) instead). The status bar is updated as if the specified transform was applied before transformation to the CRS specified through the contextual menu.

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:

• Canvas.get­Objective­CRS()
• Canvas.get­Objective­To­Display()

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
• get­Reference­System­Name()

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:

• Map­Canvas.positional­Accuracy­Property()
• Coordinate­Format.set­Ground­Accuracy(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:

• position­Reference­System

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 reference systems using the contextual menu on the status bar.

Limitations

This constructor registers numerous listeners on 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

This constructor registers numerous listeners on canvas. There is currently no unregistration mechanism. This method can be invoked only once.

Parameters:

canvas - the canvas that this status bar is tracking.

Throws:

Illegal­State­Exception - if this method has already been invoked with another canvas.

Since:

1.3

getView

public Region getView()

Returns the encapsulated JavaFX component to add in a scene graph for making the status bar visible. The Region subclass is implementation dependent and may change in any future SIS version.

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:

• Grid­Geometry.get­Coordinate­Reference­System() defines the CRS of the coordinates to format.
• Grid­Geometry.get­Grid­To­CRS(Pixel­In­Cell.CELL_CENTER) defines the conversion from coordinate values local to the canvas to coordinate values in the CRS (the local to objective CRS conversion).
• Grid­Geometry.get­Extent() provides the view size in pixels, used for estimating a resolution.
• Grid­Geometry.get­Resolution(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 local­To­Objective­CRS property.

Parameters:

geometry - geometry of the coverage shown in Map­Canvas, or null.

See Also:

• Canvas.get­Grid­Geometry()

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 pixel coordinates from which the geospatial coordinates have been computed. The returned point contains the coordinates given in the last call to set­Local­Coordinates(double, double). Note that the latter call may have been caused by a user an action such as a mouse displacement, not necessarily an explicit call from the application code. If the coordinates are not currently shown in the status bar, then this method returns an empty value.

Returns:

the local coordinates which are the sources of the 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(Mouse­Event)

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:

• Mouse­Event.MOUSE_ENTERED: show the coordinates.
• Mouse­Event.MOUSE_EXITED: hide the coordinates.
• Mouse­Event.MOUSE_MOVED: delegate to set­Local­Coordinates(double, double).

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.

getReferenceSystemName

public ObservableStringValue getReferenceSystemName()

Returns a property for the name of the reference system used by the coordinates. This is the localized name of the position­Reference­System property.

Returns:

a property for the name of the reference system used by the coordinates.

Since:

1.7

See Also:

• position­Reference­System

getMessage

public Optional<String> getMessage()

Returns the message currently shown. It may be an error message, a message for an operation in progress or a default message to show when there is no error or operation in progress.

Returns:

the current message, or an empty value if none.

Since:

1.3

See Also:

• set­Progress­Message(String)
• set­Error­Message(String, Throwable)
• set­Default­Message(String, Tooltip)

setDefaultMessage

public void setDefaultMessage(String text,
 Tooltip tooltip)

Sets the default message to show when there is no error and no operation in progress. If set­Progress­Message(String) or set­Error­Message(String, Throwable) is invoked, the informative or error message has precedence over this default message. When the informative and error message are reset to null, this default message is restored.

Parameters:

text - message to show when there is no other kind of message, or null if none.

tooltip - optional tool tip to show on the default message, or null if none.

Since:

1.7

setInfoMessage

@Deprecated(since="1.7",
            forRemoval=true)
public void setInfoMessage(String text)

Deprecated, for removal: This API element is subject to removal in a future version.

Renamed set­Progress­Message(String).

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

setProgressMessage

public void setProgressMessage(String text)

Shows or hides a message for an operation in progress. The given text should be a temporary message, for example for telling that a loading is in progress. If text is non-null, it replaces the default message. If text is null (typically after completion of the operation which was in progress), the default message is restored.

Parameters:

text - the message to show, or null for restoring the default message.

Since:

1.7

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.