Luciad Developer Platform

Each of the entries in the Lucy menu bar, tool bars and pop-up menus, is configured in a configuration file, such as the default front-end configuration file lucy.cfg, or the 2D/3D map configuration file TLcyLspMapAddOn.cfg. For example, you can use the configuration files to set the text and icon on the button, the tooltip and the location in the user interface. This guide explains the syntax used in those configuration files, and illustrates the various changes you can make to them.

For the remainder of this article, we will use the term action bar to refer in general to either the menu bar, tool bar or pop-up menu.

Structure of the config files key-value pairs

The options for an action in the configuration file are defined as key-value pairs. The key consists of multiple parts:

Program: Structure of a configuration option for an action

TLcyMain.exitAction.menuBar.shortDescription=Close application
|_________________| |_____| |______________| |________________|

 Action identifier   Action     Property          Property
                      bar         name              value
                      name

Action identifier: a unique identifier for the action.
Action bar name: in the example, the action is inserted in an action bar called menuBar, which is the main menu bar of Lucy.
Property name: the property of the action bar item that you want to configure. For example the shortDescription property refers to the tool tip shown when you hover your mouse over the item in the action bar.
Property value: the values you can fill in here depend on the property you are defining. In the example, it is the text of the tool tip.

To configure action bars, you need to find out which action bars are available, and what the names and properties of existing action bar items are. This allows you to determine in which configuration file you need to look to adjust a certain action.

See How to find the IDs of the available actions, tool bars, menu bars and pop-up menus for more information on how to obtain those IDs.

Overview of the properties available to configure an action

The following table lists all properties that you can use to configure an item from an action bar.

Property Required Description

Property	Required	Description
`item`	✓	A comma-separated list that describes the path in the action bar to the action. For a menu bar, this is the chain of menu, sub-menus, and eventually the name of the menu item itself.
`groups`	✗	Defines logical groups of items that belong together. Groups are typically visually separated from one another with horizontal or vertical line spacers. The value of this property is a comma-separated list with the same number of items as the list in the item property. It defines for each item at the corresponding index in the item property, in which group it is located.
`shortDescription`	✗	The tooltip. It describe the action in a few words.
`smallIcon`	✗	Identifier for a icon. The identifier is either a pre-defined constant such as `print` or `open`, or a relative file path. See `TLcdIconFactory` for all pre-defined constants, and `TLcdIconFactory.create` to learn which strings are accepted. The use of the icon depends on the type of action bar. For example, in a menu bar, Lucy displays the icon before the text. In a tool bar, Lucy only shows the icon.
`showActionName`	✗	Either `true` or `false`. This property is valid for tool bars only. When it is set to `true`, the tool bar buttons not only show the icon but also the action name. If this property is not specified, the default value is `false`.
`insert`	✗	Either `true` or `false`. Specifies whether the action is inserted into the action bar or not. If you set it to `false`, the item will not be added to the action bar. If this property is not specified, the item will be added to the action bar by default.
`acceleratorKey`	✗	Sets a keyboard stroke combination as a shortcut key for the action. Pressing that shortcut triggers the action. For example, the value `cmd O` is the shortcut keystroke combination for File → Open . Note that the letter in a keystroke combination, like the `O` of the previous example, must be in uppercase. See Accelerator keys for more information about the accelerator keys.
`default`	✗	The `default` property determines which action will be marked as the default action of an action bar. Each action bar in Lucy has a default action. For example, when you double-click an object on the map, the default action of the map pop-up menu is triggered. It shows the object properties. In a pop-up menu, the menu item for the default action is displayed in bold. The value for this property is either `true` or `false`. When it is set to `true`, the action bar item is used as the default item. It is not possible to have multiple default actions for the same action bar. Note that the standard Lucy framework cannot enforce that a double-click triggers the default action of an action bar. It is up to the component that owns the action bar to trigger the default action of that action bar when the component is double-clicked. In the previous example, it is the map component that triggers the default action when a map object is double-clicked.
`longDescription`	✗	A longer description of the action. Note that this property is currently not used in the user interface.

item

✓

A comma-separated list that describes the path in the action bar to the action.

For a menu bar, this is the chain of menu, sub-menus, and eventually the name of the menu item itself.

groups

✗

Defines logical groups of items that belong together.

Groups are typically visually separated from one another with horizontal or vertical line spacers. The value of this property is a comma-separated list with the same number of items as the list in the item property. It defines for each item at the corresponding index in the item property, in which group it is located.

shortDescription

✗

The tooltip. It describe the action in a few words.

smallIcon

✗

Identifier for a icon.

The identifier is either a pre-defined constant such as print or open, or a relative file path. See TLcdIconFactory for all pre-defined constants, and TLcdIconFactory.create to learn which strings are accepted.

The use of the icon depends on the type of action bar. For example, in a menu bar, Lucy displays the icon before the text. In a tool bar, Lucy only shows the icon.

showActionName

✗

Either true or false. This property is valid for tool bars only. When it is set to true, the tool bar buttons not only show the icon but also the action name.

If this property is not specified, the default value is false.

insert

✗

Either true or false.

Specifies whether the action is inserted into the action bar or not. If you set it to false, the item will not be added to the action bar. If this property is not specified, the item will be added to the action bar by default.

acceleratorKey

✗

Sets a keyboard stroke combination as a shortcut key for the action. Pressing that shortcut triggers the action.

For example, the value cmd O is the shortcut keystroke combination for File → Open . Note that the letter in a keystroke combination, like the O of the previous example, must be in uppercase.
See Accelerator keys for more information about the accelerator keys.

default

✗

The default property determines which action will be marked as the default action of an action bar.

Each action bar in Lucy has a default action. For example, when you double-click an object on the map, the default action of the map pop-up menu is triggered. It shows the object properties. In a pop-up menu, the menu item for the default action is displayed in bold.

The value for this property is either true or false. When it is set to true, the action bar item is used as the default item. It is not possible to have multiple default actions for the same action bar.

Note that the standard Lucy framework cannot enforce that a double-click triggers the default action of an action bar. It is up to the component that owns the action bar to trigger the default action of that action bar when the component is double-clicked. In the previous example, it is the map component that triggers the default action when a map object is double-clicked.

longDescription

✗

A longer description of the action.

Note that this property is currently not used in the user interface.

Lucy also has the concept of toggle actions, with two states: active and inactive. When the action is triggered, a switch occurs between the active and inactive states. These actions are called active settables (ILcyActiveSettable). They have a few more configuration properties than regular actions:

Table 1. Extra properties only applicable for `ILcyActiveSettable` instances
Property	Required	Description
`smallSelectedIcon`	✗	Similar to the `smallIcon` property. This icon is used on a toggle button when the button is selected and the active settable is in its active state. When the active settable is in its inactive state and the button de-selected, the `smallIcon` is used. If this icon is not specified, the `smallIcon` is used as well.
`active`	✗	Either `true` or `false`. When `true`, the active settable is switched to its active state. When `false`, the active settable is switched to its inactive state.

Accelerator keys

For the full specification of all possible accelerator, see the documentation of javax.swing.KeyStroke.getKeyStroke(java.lang.String).

cmd has a special purpose; Lucy interprets it as ctrl on Windows and Linux platforms and as command on macOS. Therefore if you define a shortcut as cmd O, it means ctrl O on Windows and Linux, command O on Mac OS X. If the shortcut is defined as ctrl O, then it is always ctrl on all platforms. You can see the accelerator key mappings in the table below.

Table 2. Accelerator key mappings
Key	Windows and Linux	macOS
cmd	Ctrl	Command (Cmd)
ctrl	Ctrl	Ctrl
alt	Alt	Alt
meta	Meta	Command (Cmd)
shift	Shift	Shift

The available action bar configuration options

Structure of the config files key-value pairs

Overview of the properties available to configure an action

Accelerator keys