Module org.apache.sis.gui
Package org.apache.sis.gui.coverage

# Class CoverageExplorer

Object
Widget
CoverageExplorer

All Implemented Interfaces:
  `Localized`

@DefaultProperty("coverage") public class CoverageExplorer extends Widget
An image or tabular view of `GridCoverage` together with controls for band selection and other operations. The class contains two properties:

- A `GridCoverage` supplied by user. May be specified indirectly with an `ImageRequest` for loading the coverage.
- A `CoverageExplorer​.View` type which specify how to show the coverage:
  - using `GridView` for showing numerical values in a table, or
  - using `CoverageCanvas` for showing the coverage as an image.

Controls are provided for allowing user to customize map projection, number formats, etc.. The set of control depends on the view type.

## Limitations

Current implementation is restricted to `GridCoverage` instances, but a future implementation may generalize to `org​.opengis​.coverage​.Coverage` instances.

Since:
  1.1
See Also:
  - `CoverageCanvas`
  - `GridView`

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static enum`
  `CoverageExplorer​.View`
  Type of view shown in the explorer.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `final ObjectProperty<GridCoverage>`
  `coverageProperty`
  The data shown in this canvas.
  `final ObjectProperty<GridCoverageResource>`
  `resourceProperty`
  The source of coverage data shown in this explorer.
  `final ObjectProperty<CoverageExplorer​.View>`
  `viewTypeProperty`
  The type of view (image or tabular data) shown in this explorer.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `CoverageExplorer(CoverageExplorer source)`
  Creates an explorer initialized with the same coverage or resource than the given explorer.
  `CoverageExplorer(CoverageExplorer​.View type)`
  Creates an initially empty explorer with the specified view type.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `final CoverageCanvas`
  `getCanvas()`
  Returns the canvas where the image is shown.
  `final TitledPane[]`
  `getControls(CoverageExplorer​.View type)`
  Returns the panes containing the controls, without data visualization component.
  `final GridCoverage`
  `getCoverage()`
  Returns the source of sample values for this explorer.
  `final Region`
  `getDataView(CoverageExplorer​.View type)`
  Returns the region containing the data visualization component, without controls other than navigation.
  `final GridCoverageResource`
  `getResource()`
  Returns the source of coverages for this explorer.
  `final Region`
  `getView()`
  Returns the region containing the grid or coverage view, band selector and any control managed by this `CoverageExplorer`.
  `final CoverageExplorer​.View`
  `getViewType()`
  Returns the type of view (image or tabular data) shown in this explorer.
  `final WindowHandler`
  `getWindowHandler()`
  Returns the handler of the window showing this coverage view.
  `final void`
  `setCoverage(GridCoverage coverage)`
  Sets the coverage to show in this explorer.
  `final void`
  `setCoverage(ImageRequest source)`
  Loads coverage in a background thread from the given source.
  `final void`
  `setResource(GridCoverageResource resource)`
  Sets the source of coverages shown in this explorer.
  `final void`
  `setViewType(CoverageExplorer​.View type)`
  Sets the type of view to show in this explorer.

  ### Methods inherited from class Widget

  `getLocale`

  ### Methods inherited from class Object

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

- ## Field Details

  - ### viewTypeProperty

    public final ObjectProperty<CoverageExplorer.View> viewTypeProperty
    The type of view (image or tabular data) shown in this explorer.
    See Also:
      - `getViewType()`
      - `setViewType(View)`

  - ### resourceProperty

    public final ObjectProperty<GridCoverageResource> resourceProperty
    The source of coverage data shown in this explorer. If this property value is non-null, then `coverageProperty` value will change at any time (potentially many times) depending on the zoom level or other user interaction. Conversely if a value is set explicitly on `coverageProperty`, then this `resourceProperty` is cleared.

    #### Relationship with view properties

    This property is "weakly bound" to `CoverageCanvas​.resourceProperty`: the two properties generally have the same value but are not necessarily updated in same time. After a value is set on one property, the other property may be updated only after some background process (e.g. loading) finished. If a view is not the currently visible view, its property may be updated only when the view become visible.
    Since:
      1.2
    See Also:
      - `getResource()`
      - `setResource(GridCoverageResource)`
      - `CoverageCanvas​.resourceProperty`

  - ### coverageProperty

    public final ObjectProperty<GridCoverage> coverageProperty
    The data shown in this canvas. This property value may be set implicitly or explicitly:
    - If the `resourceProperty` value is non-null, then the value will change automatically at any time (potentially many times) depending on user interaction.
    - Conversely if an explicit value is set on this property, then the `resourceProperty` is cleared.
    Note that a change in this property value may not modify the canvas content immediately. Instead, a background process will request the tiles and update the canvas content later, when data are ready.

    Current implementation is restricted to `GridCoverage` instances, but a future implementation may generalize to `org​.opengis​.coverage​.Coverage` instances.

    #### Relationship with view properties

    This property is "weakly bound" to `CoverageCanvas​.coverageProperty`: the two properties generally have the same value but are not necessarily updated in same time. After a value is set on one property, the other property may be updated only after some background process (e.g. loading) finished. If a view is not the currently visible view, its property may be updated only when the view become visible.
    See Also:
      - `getCoverage()`
      - `setCoverage(GridCoverage)`
      - `setCoverage(ImageRequest)`
      - `CoverageCanvas​.coverageProperty`

- ## Constructor Details

  - ### CoverageExplorer

    public CoverageExplorer(CoverageExplorer.View type)
    Creates an initially empty explorer with the specified view type.
    Parameters:
      `type` - the way to show coverages in this explorer.
    Since:
      1.2
    See Also:
      - `setViewType(View)`

  - ### CoverageExplorer

    public CoverageExplorer(CoverageExplorer source)
    Creates an explorer initialized with the same coverage or resource than the given explorer.
    Parameters:
      `source` - the source explorer from which to take the initial coverage or resource.
    Since:
      1.2

- ## Method Details

  - ### getWindowHandler

    public final WindowHandler getWindowHandler()
    Returns the handler of the window showing this coverage view. Those windows are created when the user clicks on the "New window" button. Each window provides the area where data are shown and where the user interacts. The window can be a JavaFX top-level window (`Stage`), but not necessarily. It may also be a tile in a mosaic of windows.
    Returns:
      the handler of the window showing this coverage view.
    Since:
      1.3

  - ### getCanvas

    public final CoverageCanvas getCanvas()
    Returns the canvas where the image is shown.
    Returns:
      the canvas where the image is shown.
    Since:
      1.2

  - ### getView

    public final Region getView()
    Returns the region containing the grid or coverage view, band selector and any control managed by this `CoverageExplorer`. The `Region` subclass returned by this method is implementation dependent and may change in any future version.
    Specified by:
      `getView` in class `Widget`
    Returns:
      the region to show.
    See Also:
      - `getDataView(View)`
      - `getControls(View)`

  - ### getDataView

    public final Region getDataView(CoverageExplorer.View type)
    Returns the region containing the data visualization component, without controls other than navigation. This is a `GridView` or `CoverageCanvas` together with their `StatusBar` and navigation controls for selecting the slice in a n-dimensional data cube. The `Region` subclass returned by this method is implementation dependent and may change in any future version.
    Parameters:
      `type` - whether to obtain a `GridView` or `CoverageCanvas`.
    Returns:
      the requested view for the value of `resourceProperty` or `coverageProperty`.

  - ### getControls

    public final TitledPane[] getControls(CoverageExplorer.View type)
    Returns the panes containing the controls, without data visualization component. The `TitledPane` contents are implementation dependent and may change in any future version.
    Parameters:
      `type` - whether to obtain controls for `GridView` or `CoverageCanvas`.
    Returns:
      the controls on specified data view.

  - ### getViewType

    public final CoverageExplorer.View getViewType()
    Returns the type of view (image or tabular data) shown in this explorer. The default value is `CoverageExplorer​.View​.TABLE`.
    Returns:
      the way to show coverages in this explorer.
    See Also:
      - `viewTypeProperty`

  - ### setViewType

    public final void setViewType(CoverageExplorer.View type)
    Sets the type of view to show in this explorer.
    Parameters:
      `type` - the new way to show coverages in this explorer.
    See Also:
      - `viewTypeProperty`

  - ### getResource

    public final GridCoverageResource getResource()
    Returns the source of coverages for this explorer. This method, like all other methods in this class, shall be invoked from the JavaFX thread.
    Returns:
      the source of coverages shown in this explorer, or `null` if none.
    Since:
      1.2
    See Also:
      - `resourceProperty`

  - ### setResource

    public final void setResource(GridCoverageResource resource)
    Sets the source of coverages shown in this explorer. This method shall be invoked from JavaFX thread and returns immediately. The new data are loaded in a background thread and the `coverageProperty` value will be updated after an undetermined amount of time.
    Parameters:
      `resource` - the source of data to show in this explorer, or `null` if none.
    Since:
      1.2
    See Also:
      - `resourceProperty`

  - ### getCoverage

    public final GridCoverage getCoverage()
    Returns the source of sample values for this explorer. This method, like all other methods in this class, shall be invoked from the JavaFX thread. Note that this value may change at any time (depending on user interaction) if the `resourceProperty` has a non-null value.
    Returns:
      the coverage shown in this explorer, or `null` if none.
    See Also:
      - `coverageProperty`
      - `CoverageCanvas​.getCoverage()`
      - `GridView​.getImage()`

  - ### setCoverage

    public final void setCoverage(GridCoverage coverage)
    Sets the coverage to show in this explorer. This method shall be invoked from JavaFX thread and returns immediately. The new data are loaded in a background thread and will appear after an undetermined amount of time.

    Invoking this method sets the `resourceProperty` value to `null`.

    Parameters:
      `coverage` - the data to show in this explorer, or `null` if none.
    See Also:
      - `coverageProperty`
      - `CoverageCanvas​.setCoverage(GridCoverage)`
      - `GridView​.setImage(RenderedImage)`

  - ### setCoverage

    public final void setCoverage(ImageRequest source)
    Loads coverage in a background thread from the given source. This method shall be invoked from JavaFX thread and returns immediately. The grid content may appear unmodified after this method returns; the modifications will appear after an undetermined amount of time.
    Parameters:
      `source` - the coverage or resource to load, or `null` if none.
    See Also:
      - `GridView​.setImage(ImageRequest)`