3.5.5. Actions. The Action Interface

API DOCS

Action is an interface that abstracts an action (in other words, some function) from a visual component. It is particularly useful when the same action can be invoked from different visual components (for example, from button and table context menu). In addition, this interface allows you to provide the action with additional properties, such as name, flags of accessibility and visibility, etc.

Below are the Action interface methods:

  • actionPerform() is invoked by a visual component associated with this action. An instance of the caller is passed to the method.

  • getId() returns an identifier of the action. The identifier is usually set by a constructor of a class that implements Action and does not change throughout the lifecycle of the created action object.

  • Methods for getting and setting caption, description, shortcut, icon, enabled, visible properties. Typically, all these properties are used by related visual components to set their own corresponding properties.

  • addPropertyChangeListener(), removePropertyChangeListener() methods used to add and remove listeners which handle changes to the abovementioned properties. A listener receives notification of java.beans.PropertyChangeEvent type, which contains the name of the changed property, its old and new values.

  • refreshState() - a method that can be implemented in a particular action class to initialize the abovementioned properties in accordance to some external factors, such as user rights. It is usually invoked in constructors of implementing classes or from related visual components.

  • addOwner(), removeOwner(), getOwner(), getOwners() – methods used to control relation between the action and visual components.

It is recommended to implement actions using the declarative creation or by inheriting from the BaseAction class. Furthermore, there is a set of standard actions applicable for tables and picker components.

Visual components associated with an action can be of two types:

  • Visual components with a single action implement the Component.ActionOwner interface. These are Button and LinkButton.

    An action is linked to the component by invoking the ActionOwner.setAction() method of the component. At this point, the component replaces its properties with corresponding properties of the action (see components overview for details).

  • Visual components containing several actions implement the Component.ActionsHolder interface. These are Window, Fragment, DataGrid, Table and its inheritors, Tree, PopupButton, PickerField, LookupPickerField.

    The ActionsHolder.addAction() method is used to add actions to the component. Implementation of this method in the component checks whether it already contains an action with the same identifier. If yes, then the existing action will be replaced with the new one. Therefore, it is possible, for example, to declare a standard action in a screen descriptor and then create a new one in the controller with different properties and add it to the component.