Class RecentReferenceSystems

Object
RecentReferenceSystems
public class RecentReferenceSystems extends Object
A short list (~10 items) of most recently used Reference­Systems. The reference systems can be listed in Choice­Box or iMenu 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

  • 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<Identifier, GridGeometry> geometries)
      Sets the reference systems, area of interest and "referencing by grid indices" systems. Contrary to other methods in this class, this method can be invoked from any thread. This method performs the following tasks, where the methods cited below are invoked from the JavaFX thread: Above information are derived from the values of the geometries map. For each entry, the map key should be the identifier of the resource that provided the Grid­Geometry value, or other text allowing the user to identify the resource. Those keys are used for naming the CRSs of cell coordinates, which are different for each grid coverage. See the grid grid CRS documentation for more details.

      The replace­By­Authoritative­Definition argument specifies whether the coordinate reference systems should be replaced by authoritative definitions when such definitions are found. If true then, for example, a WGS 84 geographic CRS with (λ, ϕ) axis order may be replaced by the "EPSG::4326" definition with (ϕ, λ) axis order.

      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 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 an authoritative definition when such definition is found. If true then, for example, a WGS 84 geographic CRS with (λ, ϕ) axis order may be replaced by the "EPSG::4326" definition with (ϕ, λ) 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 void addAlternatives(boolean replaceByAuthoritativeDefinition, ReferenceSystem... systems)
      Adds the given reference systems to the list of alternative choices. If there are 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 when such definitions are found. If true then, for example, a WGS 84 geographic CRS with (λ, ϕ) axis order may be replaced by the "EPSG::4326" definition with (ϕ, λ) 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 are 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 renderable, 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 and be automatically populated at a later time, after a background thread finished to process the list of reference systems.

      If the renderable argument is true, then the choice box will contain only reference systems that can be used for rendering purposes. The list includes Coordinate­Reference­System instances but not reference systems by identifiers such as MGRS.

      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:
      renderable - whether the choice box should be restricted to items that can be used for rendering maps.
      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 renderable, ChangeListener<ReferenceSystem> action)
      Creates a menu offering choices among the reference systems specified to this Recent­Reference­Systems. The returned control may be initially empty and be automatically populated at a later time, after a background thread finished to process the list of reference systems.

      If the renderable argument is true, then the menu will contain only reference systems that can be used for rendering purposes. The list includes Coordinate­Reference­System instances but not reference systems by identifiers such as MGRS.

      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:
      renderable - whether the menu should be restricted to items that can be used for rendering maps.
      action - the action to execute when a reference system is selected.
      Returns:
      a menu with reference systems specified by set­Preferred(…) and add­Alternatives(…) methods.
      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(…).
      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.