# Class RecentReferenceSystems

Object
RecentReferenceSystems

public class RecentReferenceSystems extends Object
A short list (~10 items) of most recently used `ReferenceSystem`s. The list can be shown in a `ChoiceBox` or in a list of `MenuItem` controls. The last choice is an "Other…" item which, when selected, popups the `CRSChooser`.

The choices are listed in following order:

- The first choice is the native or preferred reference system of visualized data. That choice stay always in the first position.
- The last choice is "Other…" and stay always in the last position.
- All other choices between first and last are ordered with most recently used first.

Since:
  1.1

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `final ObjectProperty<Envelope>`
  `areaOfInterest`
  The area of interest, or `null` if none.
  `final ObjectProperty<ComparisonMode>`
  `duplicationCriterion`
  The comparison criterion for considering two reference systems as a duplication.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `RecentReferenceSystems()`
  Creates a builder which will use a default authority factory.
  `RecentReferenceSystems(CRSAuthorityFactory factory, Locale locale)`
  Creates a builder which will use the specified authority factory.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `final void`
  `addAlternatives(boolean replaceByAuthoritativeDefinition, ReferenceSystem... systems)`
  Adds the given reference systems to the list of alternative choices.
  `void`
  `addAlternatives(String... codes)`
  Adds the coordinate reference system identified by the given authority codes.
  `void`
  `addUserPreferences()`
  Adds the coordinate reference systems saved in user preferences.
  `ChoiceBox<ReferenceSystem>`
  `createChoiceBox(boolean filtered, ChangeListener<ReferenceSystem> action)`
  Creates a box offering choices among the reference systems specified to this `RecentReferenceSystems`.
  `Menu`
  `createMenuItems(boolean filtered, ChangeListener<ReferenceSystem> action)`
  Creates menu items offering choices among the reference systems specified to this `RecentReferenceSystems`.
  `protected void`
  `errorOccurred(FactoryException e)`
  Invoked when an error occurred while filtering a `ReferenceSystem` instance.
  `ObservableList<ReferenceSystem>`
  `getItems()`
  Returns all reference systems in the order they appear in JavaFX controls.
  `List<ReferenceSystem>`
  `getSelectedItems()`
  Returns all currently selected reference systems in the order they appear in JavaFX controls.
  `static ObjectProperty<ReferenceSystem>`
  `getSelectedProperty(Menu menu)`
  Returns the property for the selected value in a menu created by `createMenuItems(boolean, ChangeListener)`.
  `void`
  `setGridReferencing(boolean replaceByAuthoritativeDefinition, Map<String, GridGeometry> geometries)`
  Sets the reference systems, area of interest and "referencing by grid indices" systems.
  `final void`
  `setPreferred(boolean replaceByAuthoritativeDefinition, ReferenceSystem system)`
  Sets the native or preferred reference system.
  `void`
  `setPreferred(String code)`
  Sets the native or preferred reference system as an authority code.

  ### Methods inherited from class Object

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

- ## Field Details

  - ### areaOfInterest

    public final ObjectProperty<Envelope> areaOfInterest
    The area of interest, or `null` if none. This is used for filtering the reference systems added by `addAlternatives(…)` and for providing some guidance to user when `CRSChooser` is shown.

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

  - ### duplicationCriterion

    public final ObjectProperty<ComparisonMode> duplicationCriterion
    The comparison criterion for considering two reference systems as a duplication. The default value is `ComparisonMode​.ALLOW_VARIANT`, i.e. axis orders are ignored.

    #### 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

  - ### RecentReferenceSystems

    public RecentReferenceSystems()
    Creates a builder which will use a default authority factory. The factory will be capable to handle at least some EPSG codes.

  - ### RecentReferenceSystems

    public RecentReferenceSystems(CRSAuthorityFactory factory, Locale locale)
    Creates a builder which will use the specified authority factory.
    Parameters:
      `factory` - the factory to use for building CRS from authority codes, or `null` for the default.
      `locale` - the preferred locale for displaying object name, or `null` for the default locale.
    See Also:
      - `CRS​.getAuthorityFactory(String)`

- ## Method Details

  - ### setGridReferencing

    public void setGridReferencing(boolean replaceByAuthoritativeDefinition, Map<String, GridGeometry> geometries)
    Sets the reference systems, area of interest and "referencing by grid indices" systems. This method performs all the following work:
    - Invokes `setPreferred(boolean, ReferenceSystem)` with the first CRS in iteration order.
    - Invokes `addAlternatives(boolean, ReferenceSystem...)` for all other CRS (single call).
    - Sets the `areaOfInterest` to the union of all envelopes.
    - Sets the content of "Referencing by cell indices" sub-menu.
    Parameters:
      `replaceByAuthoritativeDefinition` - whether the reference systems should be replaced by authoritative definition.
      `geometries` - grid coverage names together with their grid geometry. May be empty.
    Since:
      1.3

  - ### setPreferred

    public final void setPreferred(boolean replaceByAuthoritativeDefinition, ReferenceSystem system)
    Sets the native or preferred reference system. This is the system to always show as the first choice and should typically be the native `CoordinateReferenceSystem` of visualized data. If a previous preferred system existed, the previous system will be moved to alternative choices.

    The `replaceByAuthoritativeDefinition` argument specifies whether the given reference system should be replaced by authoritative definition. If `true` then for example a WGS 84 geographic CRS with (longitude, latitude) axis order may be replaced by "EPSG::4326" definition with (latitude, longitude) axis order.

    Parameters:
      `replaceByAuthoritativeDefinition` - whether the given system should be replaced by authoritative definition.
      `system` - the native or preferred reference system to show as the first choice.

  - ### setPreferred

    public void setPreferred(String code)
    Sets the native or preferred reference system as an authority code. This is the system to always show as the first choice and should typically be the native `CoordinateReferenceSystem` of visualized data. If a previous preferred system existed, the previous system will be moved to alternative choices.

    If the given code is not recognized, then the error will be notified at some later time by a call to `errorOccurred(FactoryException)` in a background thread and the given code will be silently ignored. This behavior allows the use of codes that depend on whether an optional dependency is present or not, in particular the EPSG dataset.

    Parameters:
      `code` - authority code of the native of preferred reference system to show as the first choice.

  - ### addAlternatives

    public final void addAlternatives(boolean replaceByAuthoritativeDefinition, ReferenceSystem... systems)
    Adds the given reference systems to the list of alternative choices. If there is duplicated values in the given list or with previously added systems, then only the first occurrence of duplicated values is retained. If an area of interest (AOI) is specified, then reference systems that do not intersect the AOI will be hidden.

    The `replaceByAuthoritativeDefinition` argument specifies whether the given reference systems should be replaced by authoritative definitions. If `true` then for example a WGS 84 geographic CRS with (longitude, latitude) axis order may be replaced by "EPSG::4326" definition with (latitude, longitude) axis order.

    Parameters:
      `replaceByAuthoritativeDefinition` - whether the given systems should be replaced by authoritative definitions.
      `systems` - the reference systems to add as alternative choices. Null elements are ignored.

  - ### addAlternatives

    public void addAlternatives(String... codes)
    Adds the coordinate reference system identified by the given authority codes. If there is duplicated values in the given list or with previously added systems, then only the first occurrence of duplicated values is retained. If an area of interest (AOI) is specified, then reference systems that do not intersect the AOI will be hidden.

    If a code is not recognized, then the error will be notified at some later time by a call to `errorOccurred(FactoryException)` in a background thread and the code will be silently ignored. This behavior allows the use of codes that depend on whether an optional dependency is present or not, in particular the EPSG dataset.

    Parameters:
      `codes` - authority codes of the coordinate reference systems to add as alternative choices. Null or empty elements are ignored.

  - ### addUserPreferences

    public void addUserPreferences()
    Adds the coordinate reference systems saved in user preferences. The user preferences are determined from the reference systems observed during current execution or previous executions of JavaFX application. If an area of interest (AOI) is specified, then reference systems that do not intersect the AOI will be ignored.

  - ### getItems

    public ObservableList<ReferenceSystem> getItems()
    Returns all reference systems in the order they appear in JavaFX controls. The first element is the `preferred` (or native) reference system. All other elements are alternatives.
    Returns:
      all reference systems in the order they appear in JavaFX controls.

  - ### getSelectedItems

    public List<ReferenceSystem> getSelectedItems()
    Returns all currently selected reference systems in the order they appear in JavaFX controls. This method collects selected values of all controls created by a `createXXX(…)` method. The returned list does not contain duplicated values.
    Returns:
      currently selected values of all controls, without duplicated values and in the order they appear in choice lists.

  - ### createChoiceBox

    public ChoiceBox<ReferenceSystem> createChoiceBox(boolean filtered, ChangeListener<ReferenceSystem> action)
    Creates a box offering choices among the reference systems specified to this `RecentReferenceSystems`. The returned control may be initially empty, in which case its content will be automatically set at a later time (after a background thread finished to process the `CoordinateReferenceSystem`s).

    If the `filtered` argument is `true`, then the choice box will contain only reference systems that can be used for rendering purposes. That filtered list can contain `CoordinateReferenceSystem` instances but not reference systems by identifiers such as MGRS. The latter are usable only for the purposes of formatting coordinate values as texts.

    #### Limitations

    There is currently no mechanism for disposing the returned control. For garbage collecting the returned `ChoiceBox`, this `RecentReferenceSystems` must be garbage-collected as well.
    Parameters:
      `filtered` - whether the choice box should contain only `CoordinateReferenceSystem` instances.
      `action` - the action to execute when a reference system is selected.
    Returns:
      a choice box with reference systems specified by `setPreferred(…)` and `addAlternatives(…)` methods.
    Since:
      1.3

  - ### createMenuItems

    public Menu createMenuItems(boolean filtered, ChangeListener<ReferenceSystem> action)
    Creates menu items offering choices among the reference systems specified to this `RecentReferenceSystems`. The items will be inserted in the menu list. The content of that list will change at any time after this method returned: items will be added or removed as a result of user actions.

    If the `filtered` argument is `true`, then the menu items will contain only reference systems that can be used for rendering purposes. That filtered list can contain `CoordinateReferenceSystem` instances but not reference systems by identifiers such as MGRS. The latter are usable only for the purposes of formatting coordinate values as texts.

    #### Limitations

    There is currently no mechanism for disposing the returned control. For garbage collecting the returned `Menu`, this `RecentReferenceSystems` must be garbage-collected as well.
    Parameters:
      `filtered` - whether the menu should contain only `CoordinateReferenceSystem` instances.
      `action` - the action to execute when a reference system is selected.
    Returns:
      the menu containing items for reference systems.
    Since:
      1.3

  - ### getSelectedProperty

    public static ObjectProperty<ReferenceSystem> getSelectedProperty(Menu menu)
    Returns the property for the selected value in a menu created by `createMenuItems(boolean, ChangeListener)`.
    Parameters:
      `menu` - the menu, or `null` if none.
    Returns:
      the property for the selected value, or `null` if none.

  - ### errorOccurred

    protected void errorOccurred(FactoryException e)
    Invoked when an error occurred while filtering a `ReferenceSystem` instance. The error may be a failure to convert an EPSG code to a `CoordinateReferenceSystem` instance, or an error during a CRS verification. Some errors may be normal, for example because EPSG dataset is not expected to be present in every runtime environments. The consequence of this error is "only" that the CRS will not be listed among the reference systems that the user can choose.

    The default implementation popups an alert dialog only if the error occurred after the user accepted to download optional dependencies, because the error may be caused by a problem related to the download operation. Otherwise this method only logs the error at `Level​.FINE`. No other processing is done; user is not notified unless (s)he paid attention to loggings.

    Parameters:
      `e` - the error that occurred.