Why do it ?

Lucy users can choose what formatting they want to show certain physical values in: for example, the user can choose to show speed in kilometers/hour or in knots, altitudes in meters or in feet, distances in kilometers or in miles, and so on. The default Lucy configuration contains some pre-defined units, but you may need to add another unit for your application.

How to do it ?

The TLcyMapEditUnitAddOn adds the UI elements that allows users to switch formatting. The configuration file of that add-on allows removing certain units and contains brief instructions for the addition of units. The type of unit determines which steps you need to take. There is a distinction between formats related to distance, altitude and speed, formats related to lon-lat points, and date-time formats.

Distances, altitudes and speed formats

The instructions for distances, altitudes and speeds are all very similar. For example, for distances the configuration file specifies: 

# Distance units: must be a subset of those defined in TLcdDistanceUnit.getAllDistanceUnits.
# When adding custom units below, it must be added to TLcdDistanceUnit using
# TLcdDistanceUnit.addDistanceUnit before this add-on is plugged.

This article illustrates the addition of a distance unit by adding an option to show distances in centimeters:

  1. Ensure that the unit is available before the TLcyMapEditUnitAddOn is plugged in.
    The configuration file of the TLcyMapEditUnitAddOn only allows the configuration of distance units registered with TLcdDistanceUnit. The default distance units are listed as constants in TLcdDistanceUnit. Because the centimeter unit is not available, we must create it first, and register it with TLcdDistanceUnit.
    You must complete the registration before the TLcyMapEditUnitAddOn is plugged in, and you must register the unit only once for each JVM. A good place to call this code from is the main method of your application. 

    static{
  TLcdDistanceUnit centimetreUnit = new TLcdDistanceUnit("Centimetre", "cm", 0.01);
  TLcdDistanceUnit.addDistanceUnit(centimetreUnit);
}

    This step is only needed for units that are not yet available.

  2. Configure the unit in the configuration file of the TLcyMapEditUnitAddOn.
    Add the extra unit to the configuration file of the TLcyMapEditUnitAddOn to make the unit available in the UI. You can do so by creating a custom configuration file that overrides and adds some properties:

    custom_map_units.cfg
    # Include all the options from the original configuration file
includeConfig =  lucy/map/map_units.cfg

# Adjust the available distance units to include Centimetre
# This is done by adding the name of the unit (Centimetre) to the list of possible distance_units
TLcyMapEditUnitAddOn.distance_units=Centimetre, Metre, Kilometre, NauticalMile, MileUS, Feet

# Configure the UI element which allows the user to choose the centimetre unit
TLcyMapEditUnitAddOn.distance_units.Centimetre.menuBar.item=Edit, Distance unit, Centimetre
TLcyMapEditUnitAddOn.distance_units.Centimetre.menuBar.groups=EditGroup, EditSubMenuGroup, UnitsGroup

    Once the custom file is available, make sure that the TLcyMapEditUnitAddOn uses it by adjusting the corresponding entry in the addons.xml file.

Longitude-latitude point formats

You can add more lon-lat point formats by altering the configuration file, without writing any extra code. The TLcyMapEditUnitsAddOn_LonLatPointsFormats.cfg file offers instructions for the addition of lon-lat point formats, and contains the configuration options for the default formats.

As an illustration, we add a format that uses degrees only to display the point location. We use a custom configuration file that:

  • Defines the pattern used for the formatting of the points. The pattern must be a valid TLcdLonLatPointFormat pattern

  • Adds our degrees-only format to the list of available formats

  • Configures the UI element corresponding to our degrees-only format

custom_map_units.cfg
# Include all the options from the original configuration file
includeConfig =  lucy/map/map_units.cfg

# Adjust the available lon lat point formats to include a format which only displays degrees
# The degrees_only is our custom entries, the other entries are copied from the original configuration file
TLcyMapEditUnitAddOn.LonLatPointFormats.formatNames = N_DDMMSS_E_DDDMMSS,\
                                                      N_DDMMSSss_E_DDDMMSSss,\
                                                      DDMMSS_N_DDDMMSS_E,\
                                                      DDMMSSss_N_DDDMMSSss_E, \
                                                      DDMMSS,\
                                                      DDMMSSss,\
                                                      DDdddddddd,\
                                                      DDMMmm,\
                                                      degrees_only

# Pattern of our degrees only format
TLcyMapEditUnitAddOn.LonLatPointFormats.degrees_only.pattern=Lat(+D),lon(+D)

# Configuration of the UI element which allows the user to activate our degrees only format
TLcyMapEditUnitAddOn.LonLatPointFormats.degrees_only.active_settable.menuBar.item=Edit, Point Format, Lat Lon, DD\u00b0\\,DDD\u00b0
TLcyMapEditUnitAddOn.LonLatPointFormats.degrees_only.active_settable.menuBar.groups=EditGroup, EditSubMenuGroup, DefaultGroup, DefaultGroup

Date-time formats

The steps for adding date-time formats are similar to the steps for adding lon-lat point formats. It is a matter of:

  • Defining the pattern in the configuration file. For date time formats, this must be a pattern accepted by java.text.SimpleDateFormat.

  • Configuring the UI element for the format.

To find examples, see the properties starting with TLcyMapEditUnitAddOn.datetime_formats in the map_units.cfg file.

Duration Formats

To add a custom duration format, you follow the same steps as for the addition of a lon-lat format:

  1. Define a pattern in the configuration file. This pattern must be accepted by the TLcdDurationFormat class.

  2. Add its name to the TLcyMapEditUnitAddOn.DurationFormat.duration_formats list.

  3. Configure the UI elements in the TLcyMapEditUnitAddOn.DurationFormat.<pattern_name>.active_settable.menuBar.item and TLcyMapEditUnitAddOn.DurationFormat.<pattern_name>.active_settable.menuBar.groups properties.

You can use the default patterns located in the file TLcyMapEditUnitAddOn_DurationFormats.cfg as examples.