Kexi/Plugins/Forms/Actions

At the moment it's possible to connect a button with "Assign Action" with a shared action brovided by Kexi provides in order to execute a predefined (global - shared or local) action. The action is invoked when the button is clicked.

Action Categories

It's not productive to execute a global action. Sometimes there's a need for executing action in a context of a given object. This makes the existence of so called action categories useful. The following categories have been identified and implemented:

• No Category - the action will not be visible at all
• Global Category - for global actions like "edit_copy", available in the main menu and context menus; can be also applied to focused widget (of many types)
• Part Item Category - action related to a part item (e.g. a context menu's action within the project navigator); example: "data_execute" which executes a macro or script; actions of this category require context, used only in the navigator
• Window Category - action related to active window, which can display a table, query, form, report; actions like "move to next row" belong to this category; currently only forms are be supported; while this category is being declared for an action, it must be specified what types of objects are supported (KexiPart::ObjectType, eg. TableObjectType, QueryObjectType, FormObjectType). There can be more than one type supported by the same action.

These categories can be combined. For example, "edit_delete" is supported both by Part Item and Global action categories. Actions must belong at least to one category called "No category" -- actions without categories will not be visible within the actions selection dialog.

Usage of the action categories

Action categories can be defined using Kexi::ActionCategories helper class from the kexicore library. There is a singleton object available using Kexi::ActionCategories* Kexi::actionCategories() function, used by KexiMainWindow::setupActions(). All shared actions should be maintained by assigning them to categoris, possibly multiple.

The reason for configuring action categories at the top level (main window) is that the assignment to be performed once and have references to shared actions.

The action selection dialog

The Action Selection dialog enables assignment of action to a button widget. Currently, the only way to show the dialog is to select the 'Assign Action...' command from the button's context menu in the form's Design View.

The dialog is implemented by KexiActionSelectionDialog class of kexiformutils library.

Actions assignments at runtime

The KexiFormEventHandler class implements (signal-slot) assignments for predefined design-time assignments defined in a form design. KexiFormEventAction class takes care of decoding the storege format (e.g. "table:cars") into a set of strictly defined data members. It also provides activation routine KexiFormEventAction::slotTrigger() for actions that require a context to be executed. Global actions are executed automatically as a response to previously performed signal-slot connection between button's clicked() signal and shared (global) action's activate() slot (see KexiFormEventHandler::setMainWidgetForEventHandling()).

^ toc

Storage format for action assignments

Kexi Form's XML file format (which is in turn Qt Designer-based) has been utilized to store action assignment information. The extenstion is an effect of using two additional Qt properties of the button widget class:

• onClickAction
• onClickActionOption

This gives the following XML chunk:

 <widget class="KexiPushButton" >
   ...
   <property name="onClickAction" >
      <string>{actionCategoryAndName}</string>
   </property>
   <property name="onClickActionOption" >
      <string>{actionOption}</string>
   </property>
   ....
 </widget>

where {actionCategoryAndName} and {actionOption} denote action name and optional category. There are following cases:

• kaction:{actionName} - a global action with name {actionName} specified without parameters; example: kaction:data_cancel_row_changes. This case corresponds with actions from 'Global Category' as described above. {actionOption} property should be empty for this case.
• currentForm:{actionName} - a local action related to the current form. This case corresponds with actions from 'Window Category' as described above. {actionOption} property should be empty for this case.
• {objectType}:{objectName} - an action executed in context of an object pointed by name and type (as for instance there can be table and field with the same name). Example type/name pair stored as the onClickAction property value is table:cars. The {objectType} is in fact a part of Kexi object's mime types, e.g. 'table' for 'kexi/table' mime type. This case corresponds with actions from 'Part Item Category' as described above. {actionOption} property provides action name to be executed for the specified object. Possible actions names are in this case:
  • open - opens the object in data view (macros and scripts will be opened in design view if possible)
  • execute - executes the object (only available for macros and scripts)
  • print - shows the system print dialog for simple printout of the object (actually only table or query)
  • printPreview - like for print but shows the "Print preview" window
  • pageSetup - like for print but shows the "Print Setup" window
  • exportToCSV - shows the "Export To CSV" dialog that provides options for exporting data from the pointed table or query to a CSV file (actually only available for tables and queries)
  • copyToClipboardAsCSV - like for exportToCSV but shows the "Copy To CSV" dialog
  • new - creates a window for new object of given type, without saving it (objectName is ignored)
  • design - opens the object in design view
  • editText - opens the object in text view (actually available only for queries)
  • close - closes window with the object if it's opened

Thanks to using properties and prefixes, the assignment format is open for future extensions (e.g. for adding new actions or contexts and object types).

For backward compatibility with Kexi < 1.1.2, where there were no action options available: if there is no {actionOption} property provided, open is assumed for all object types except macros and scripts, for whose execute action is assumed.

Note

Change log:

• Started in 2005 by jstaniek.
• Macros support added in 2006 by dipesh.
• Updated in Dec 2006 for Kexi 1.1.2 by jstaniek
• Migrated from [1], updated in Jun 2023 for the current code of 2023, removed references to Macros by jstaniek