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, JToolBar for example. There is no need to integrate it with the Lucy action bar mechanism.

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 ILcyActionBar class. It is basically a high-level container for action bar entries, and provides the typical add and remove operations like other containers. 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 ILcyActiveSettable. 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

An 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

An 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 ILcyActiveSettable changes. For example, if a check box associated with an ILcyActiveSettable is selected or de-selected, the setActive method of the ILcyActiveSettable is called. The setActive method in turn performs the actual code.

An ILcdAction is more or less equivalent to the standard javax.swing.Action interface in the JDK. You can best compare the ILcyActiveSettable to a standard javax.swing.Action, combined with the javax.swing.Action.SELECTED_KEY to toggle between an on and off state.

TLcyActionBarManager: central repository for all actions

The Lucy back-end features a central repository for all actions and active settables: the TLcyActionBarManager. 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 TLcyActionBarManager.

  • It allows an action bar to ask the TLcyActionBarManager which 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 TLcyLspMapAddOn:

  1. The undo add-on registers the undo and redo actions at the TLcyActionBarManager and indicates that they belong in the tool bar of a map.

  2. The TLcyLspMapAddOn in turn creates the tool bar, and asks the TLcyActionBarManager which 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:

Program: Retrieving the TLcyActionBarManager from 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:

    • null for 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:

  1. Call TLcyActionBarManager.getActionBar with 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 ILcyActionBar.

  2. Use the API of the obtained ILcyActionBar interface 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.

Consider the ILcyActionBar instances returned by TLcyActionBarManager.getActionBar as container objects for actions and active settables. They are not suited for display in the UI. Any attempt to add them to the UI will result in exceptions. See Working with the action bar contexts for more information about creating an action bar that you can add to the UI.

To verify which actions and active settables have been registered, you can use the TLcyDebugAddOn. It allows you to print all registered actions and active settables in the console. To start the printout, select the Print action bar manager contents item from the Debug menu. This output allows you to examine which actions and active settables are known in the TLcyActionBarManager, and can facilitate debugging when an action does not show up in the UI.

For more information about the TLcyDebugAddOn, see the the debug add-on documentation.

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.

The TLcyDebugAddOn provides a visual aid for identifying the available action bars and their contexts. If you select the Debug actions item in the Debug menu, and restart the application, it will add a blue border around every action bar. The tooltip of such an action bar reveals its ID and its context, an ILcyMapComponent for example. For more information about the TLcyDebugAddOn, see the the debug add-on documentation.