Module org.apache.sis.gui
Package org.apache.sis.gui.referencing

Class RecentReferenceSystems

Object
RecentReferenceSystems
public class RecentReferenceSystems extends Object
A short list (~10 items) of most recently used Reference­Systems. The list can be shown in a Choice­Box or in a list of Menu­Item 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 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 add­Alternatives(…) and for providing some guidance to user when CRSChooser is shown.

      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.

    • duplicationCriterion

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

      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

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

  • 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:
      Parameters:
      replace­By­Authoritative­Definition - 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 Coordinate­Reference­System of visualized data. If a previous preferred system existed, the previous system will be moved to alternative choices.

      The replace­By­Authoritative­Definition 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:
      replace­By­Authoritative­Definition - 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 Coordinate­Reference­System 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 error­Occurred(Factory­Exception) 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 replace­By­Authoritative­Definition 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:
      replace­By­Authoritative­Definition - 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 error­Occurred(Factory­Exception) 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 create­XXX(…) 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 Recent­Reference­Systems. 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 Coordinate­Reference­Systems).

      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 Coordinate­Reference­System 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 Choice­Box, this Recent­Reference­Systems must be garbage-collected as well.
      Parameters:
      filtered - whether the choice box should contain only Coordinate­Reference­System instances.
      action - the action to execute when a reference system is selected.
      Returns:
      a choice box with reference systems specified by set­Preferred(…) and add­Alternatives(…) 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 Recent­Reference­Systems. 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 Coordinate­Reference­System 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 Recent­Reference­Systems must be garbage-collected as well.
      Parameters:
      filtered - whether the menu should contain only Coordinate­Reference­System 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 create­Menu­Items(boolean, Change­Listener).
      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 Reference­System instance. The error may be a failure to convert an EPSG code to a Coordinate­Reference­System 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.