The Lucy framework provides an application-wide preference mechanism, from which add-ons can retrieve certain user preferences or store their own, and be notified of changes in these preferences.

Those preferences typically represent a way in which the user wants to see a feature configured, for example the preferred look-and-feel of the Lucy application. As such, these preferences should not change when a new workspace is loaded. See here for more information about workspaces. This implies that the preferences are not saved in the workspace file. Instead, they are persisted by the TLcyPersistentPreferencesAddOn. Please refer to the persistent preferences add-on documentation for more details about its storage mechanism and behavior.

The preferences are divided in two sets of preferences:

  • The system preferences: these preferences apply in general to all users of the application.

  • The current user preferences: these are only applicable to the user currently running the application.

It is up to the client of the TLcyPreferencesManager to decide to which category a preference belongs. For instance, the look-and-feel of the application can be a user preference, while the time zone would be a good candidate for a system preference.

To retrieve the preferences, use the method getCurrentUserPreferences or getSystemPreferences of the TLcyPreferencesManager. You can retrieve this manager from ILcyLucyEnv using its method getPreferencesManager. The preferences are modeled as a TLcyStringProperties object, in which the preferences are stored as key-value pairs. TLcyStringProperties is String-based, which means that both the key and the value are String objects.

If you want to be notified of changes in the user preferences, you can add a PropertyChangeListener to TLcyStringProperties, using its method addPropertyChangeListener. The propertyChange method of PropertyChangeListener interface takes a PropertyChangeEvent as parameter, which contains an identifier of the preference that has changed, the old value and the new value.

Aside from these general user preferences, the Lucy back-end also has specific preferences concerning the use of measures and units. It is recommended to use these formats and units in your addon to get a display of measures and units that is consistent with the rest of Lucy. These properties are available:

getDefaultAltitudeFormat

Defines the altitude format that is used in Lucy to display and parse altitudes as String instances.

getDefaultDistanceFormat

Default format for displaying distances.

getDefaultSpeedFormat

Default format for displaying speeds.

getDefaultLonLatPointFormat

Default format for displaying geodetic coordinates. This format can be changed with the method setDefaultLonLatPointFormat.

getDefaultAzimuthFormat

Default format used for displaying and parsing angles. This format can be changed with the setDefaultAzimuthFormat.

getDefaultUserAltitudeUnit

Defines the default altitude unit. Note that this is the unit that the user wants to see in the user interface. It is not how the altitude information present in the models should be interpreted. This means that this setting only has an effect on how the altitudes are displayed. This unit can be changed with the method setDefaultUserAltitudeUnit.

getDefaultUserDistanceUnit

Default unit for the distance display. This unit can be changed with the method setDefaultUserDistanceUnit.

getDefaultUserSpeedUnit

Default unit for the speed display. This unit can be changed with the method setDefaultUserDistanceUnit.

getDefaultModelReference

Provides the default model reference in which coordinates are displayed. When you are displaying coordinates in the user interface, the units should be converted to this default model reference. This ensures a consistent display of coordinates. For more information about converting coordinates, see Coordinate systems and transformations.

The Lucy back-end sends out events to notify listeners of format and unit changes. A PropertyChangeListener needs to be added to the Lucy back-end itself, not its preferences manager. When one of these properties changes, the PropertyChangeListener is notified with a PropertyChangeEvent containing the name of the property, the old value and the new value. Note that the name of the property can be derived from the getter method according to the JavaBeans specification. For instance, when the value of getDefaultUserAltitudeUnit() changes, the property name of the event will be "defaultUserAltitudeUnit". Typically, any component displaying coordinates, altitudes or other measures will listen to these changes and update itself according to the new setting.