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

# Class ValuesUnderCursor

Object
ValuesUnderCursor

public abstract class ValuesUnderCursor extends Object
Provider of textual content to show in a `StatusBar` for values under cursor position. When the mouse cursor moves, `evaluateLater(DirectPosition)` is invoked with the same "real world" coordinates than the ones shown in the status bar.

## Multi-threading

Instances of `ValueUnderCursor` do not need to be thread-safe, because all `ValuesUnderCursor` methods will be invoked from JavaFX thread. However, the actual fetching and formatting of values will be done in a background thread using the `ValuesUnderCursor​.Formatter` inner class, which needs to be thread-safe.

Since:
  1.1

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `protected static class`
  `ValuesUnderCursor​.Formatter`
  Task for fetching and formatting values in a background thread.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected final Menu`
  `valueChoices`
  Menu offering choices among the values that this `ValuesUnderCursor` can show.

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `ValuesUnderCursor()`
  Creates a new evaluator instance.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `evaluateLater(DirectPosition point)`
  Formats a string representation of data under given "real world" position.
  `protected abstract ValuesUnderCursor​.Formatter`
  `formatter()`
  Returns the task for fetching and formatting values in a background thread.

  ### Methods inherited from class Object

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

- ## Field Details

  - ### valueChoices

    protected final Menu valueChoices
    Menu offering choices among the values that this `ValuesUnderCursor` can show. This menu will be available as a contextual menu in the `StatusBar`. It is subclass responsibility to listen to menu selections and adapt their `evaluateLater(DirectPosition)` output accordingly.

- ## Constructor Details

  - ### ValuesUnderCursor

    protected ValuesUnderCursor()
    Creates a new evaluator instance. The `valueChoices` list of items is initially empty; subclass constructor should set a text and add items.

- ## Method Details

  - ### formatter

    protected abstract ValuesUnderCursor.Formatter formatter()
    Returns the task for fetching and formatting values in a background thread. `ValuesUnderCursor` subclasses should keep a single `ValuesUnderCursor​.Formatter` instance, eventually replaced when the data shown in `MapCanvas` changed. That instance will be reused every time that the cursor position changed.
    Returns:
      task for fetching and formatting values in a background thread, or `null` if none.
    Since:
      1.3

  - ### evaluateLater

    public void evaluateLater(DirectPosition point)
    Formats a string representation of data under given "real world" position. This method shall be invoked in JavaFX thread, but values will be fetched and formatted in a background thread managed automatically by this `ValuesUnderCursor` class.

    The position CRS should be non-null for avoiding ambiguity about what is the default CRS. The position CRS can be anything; it will be transformed if needed.

    Parameters:
      `point` - the cursor location in arbitrary CRS (usually the CRS shown in the status bar). May be `null` for declaring that the point is outside canvas region.
    Since:
      1.3