HOWTO Add new bookmark properties - GeoscienceAustralia/earthsci GitHub Wiki

Bookmarks are used to capture information about the world state that can be persisted, edited and/or re-applied. They can be created by users to bookmark interesting locations, or could be provided by a third party to communicate some sort of information to the user.

The bookmark concept in EarthSci is highly extensible. It uses configurable bookmark properties to store information about a specific aspect of the world state. A standard, basic set of properties is provided with the core framework (e.g. camera position, layer state, vertical exaggeration etc.). Additional properties can be provided by plugin authors to capture additional state (e.g. the state of a newly added feature etc.).

This HOWTO gives a quick introduction to the steps to go through to add new bookmark properties.

1. Implement a new IBookmarkProperty

This should contain all of the fields required to capture and store the property state. Optionally, the property can be marked up with persistence annotations (if the framework persistence mechanism is to be used.

In order to participate in dependency injection, a no-args constructor must be provided.

2. Implement a new IBookmarkPropertyExporter

This class should be able to export the new bookmark property to an XML structure. This can either be hand-coded, or can make use of the framework persistence mechanism (@Persistent etc.). The exported XML should be self-contained (i.e. should not rely on the presence of any other elements in the DOM).

3. Implement a new IBookmarkPropertyCreator

This should perform the opposite of the IBookmarkPropertyExporter - that is, instantiate a new property instance using the stored information in the XML structure. It is left to the author's discretion how tolerant of missing XML elements this process is.

Importantly, this class should also be able to create a new property instance from the current world state.

Note: In many cases it will make sense to combine the IBookmarkPropertyExporter and IBookmarkPropertyCreator together into a single class.

4. Create a new IBookmarkPropertyApplicator

This class should be able to apply the state captured in a property to the world. This class may make use of a framework-provided IBookmarkPropertyAnimator for animation of values, or a new IBookmarkPropertyAnimator class may be created to perform property-specific animation (e.g. the CameraPropertyAnimator makes use of the WorldWind animator mechanism to perform camera/viewport animation)

The framework provides a core.math.interpolation package that contains useful interpolators that may be used.

5. Register the classes against the appropriate extension points

For the creator: au.gov.ga.earthsci.bookmark.creators

For the exporter: au.gov.ga.earthsci.bookmark.exporters

For the applicator: au.gov.ga.earthsci.bookmark.applicators

6. Create a new IBookmarkPropertyEditor

This is the UI component used by the user to edit the fields of the property. It can use any SWT/JFace widget, and should be laid out in a simple, uncluttered manner.

The editor should detect validation errors and respond appropriately so that the user has enough information to correct the problem.

Consider extending the AbstractBookmarkPropertyEditor class, which provides convenience implementations of some methods, and provides a convenient way of registering field-level validation errors.

7. Register the editor against the appropriate extension point

au.gov.ga.earthsci.application.bookmarkPropertyEditor