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,
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
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 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 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.
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.
The following sections explain the usage of the
TLcyActionBarManager in more detail, with pointers to the relevant API and code examples.
The action bar manager is available at the Lucy back-end:
TLcyActionBarManagerfrom the Lucy back-end.
ILcyLucyEnv lucy; TLcyActionBarManager actionBarManager = lucy.getUserInterfaceManager().getActionBarManager();
To add an action or active settable, register it with the
TLcyActionBarManager for a specific 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.
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
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.