This guide highlights the API that is available for Lucy action bars, and illustrates how the classes work together. You need to use the API if you want to:
Create your own action bar which offers the same functionality as the standard Lucy action bars
Configure any of the standard Lucy action bar items into your own action bar
Add your own entries to the standard Lucy action bars
Gain programmatic access to existing actions
Use the Lucy action bar API if you want to work with a menu bar or tool bar, and allow Lucy add-ons to add actions and active settables to those bars, or if you want to configure some of the standard Lucy actions so that they appear in your action bar.
If you just want a tool bar or menu bar in your application, unrelated to the Lucy action bar mechanism, you
can use the standard classes from the JDK,
Main action bar API classes: ILcyActionBar, ILcdAction and ILcyActiveSettable
An action bar consists of two main components:
The action bar container itself: for example, the tool bar of the map
All individual entries of the action bar: for example, the entry to activate a controller
ILcyActionBar: action bar container
The action bar container is represented in the API by the
It is basically a high-level container for action bar entries, and provides the typical add and remove operations like other
Consult the Javadoc of this class for more information about the available methods.
All the items in an
ILcyActionBar are either an
ILcdAction or an
Both of these classes model the functionality behind a GUI widget, such as a tool bar button or a menu item.
Separating the widget from its functionality not only improves re-usability and readability of GUI code, but also allows you
to represent the same action through multiple GUI widgets, for example a menu item and a toolbar button that both allow users to open files.
ILcdAction: user actions
ILcdAction models an action that the user can perform, like opening a file. It is usually represented by
a regular toolbar button or a menu item. For example, the action behind the File→ Open menu item shows a file chooser, checks if
the input is valid, reads the file, and so on. For more detail about what an
ILcdAction is and how
to use it, see Working with GUI events and Working with GUI events in GXY views.
ILcyActiveSettable: toggle actions
ILcyActiveSettable represents a toggle action: an action that is either active or inactive. In a menu bar or a toolbar, an active settable is
usually represented by a toggle button or a radio button.
It is identical to an
ILcdAction except that it has an extra method that allows for a change of the active state: the
setActive( boolean aActive ) method must specify what needs to be done if the state of the
For example, if a check box associated with an
ILcyActiveSettable is selected or de-selected, the
setActive method of the
ILcyActiveSettable is called.
setActive method in turn performs the actual code.
TLcyActionBarManager: central repository for all actions
The Lucy back-end features a central repository for all actions and active settables: the
This central repository has two important functions:
It allows add-ons to register an action or active settable for insertion into one or more action bars. A unique identifier identifies the appropriate toolbars for the
It allows an action bar to ask the
TLcyActionBarManagerwhich actions have been registered for it, and insert those.
The main benefit of having such a central repository is that it prevents unnecessary dependencies between the individual add-ons.
To insert an undo/redo action for map changes, for example, the
TLcyUndoAddOn adds an undo and redo action into the tool bar of each map, without depending on the
The undo add-on registers the undo and redo actions at the
TLcyActionBarManagerand indicates that they belong in the tool bar of a map.
TLcyLspMapAddOnin turn creates the tool bar, and asks the
TLcyActionBarManagerwhich actions and active settables must be included in that tool bar.
The following sections explain the usage of the
TLcyActionBarManager in more detail, with pointers to the relevant API and code examples.
Retrieving the action bar manager
The action bar manager is available at the Lucy back-end:
TLcyActionBarManagerfrom the Lucy back-end.
ILcyLucyEnv lucy; TLcyActionBarManager actionBarManager = lucy.getUserInterfaceManager().getActionBarManager();
Registering an action with the central repository
To add an action or active settable, register it with the
TLcyActionBarManager for a specific action bar.
Identifying the action bar
You need to use a unique identifier to specify the action bar. This identifier consists of two parts: a name and a context:
name: the name is a simple String. Examples are "toolBar" and "menuBar".
context: the context indicates to what part of Lucy the action bar and its actions apply. The context is either:
nullfor a global action. A global action is the File→ Exit action which closes the whole application, for example.
A map instance for map-specific actions like the File→ Open action, which opens data on a specific map.
For more information about those contexts and their usages, see Working with the action bar contexts.
Registering the action
Once you have constructed the action bar identifier, you can register the action:
TLcyActionBarManager.getActionBarwith the action bar identifier to ask the action bar manager for an action bar container object containing all its actions and active settables. The returned container object is an
Use the API of the obtained
ILcyActionBarinterface to insert the action or active settable in the action bar. As a result, the action or active settable is registered with the action bar manager.
It is also possible to define the action bar location of the action in a configuration file. This is illustrated in the What is a configurable action bar in Lucy? article.
To verify which actions and active settables have been registered, you can use the
For more information about the
Working with the action bar contexts
As explained in Registering an action with the central repository, the context of an action bar indicates to what part of Lucy the action bar and its actions apply.
There are two types of action bar context:
A map component. An action bar contains entries that are applicable to one specific map. This map is used as context.
An example of such an action bar is the tool bar of a map. The standard tool bar contains an active settable to activate the select controller, for example. If the active settable is triggered, the controller is activated, but only for that specific map. Other maps in the application remain unaffected.
A null context. In this case, we refer to the action bar as a global action bar. A global action bar contains entries which are applicable to the whole Lucy application.
An example of such an action bar is the menu bar of the Lucy application. The menu bar contains the File→ Exit action. This action is not tied to any map, but rather to the whole Lucy application.
A global action bar also contains all entries for the currently active map. A map becomes active when it gains focus. For example, the File→ Open action is available in the menu bar, but it is an action that opens the data on the currently active map.