View source for 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 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 for their execution. 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()).

== Storage format for action assignments ==
KEXI Form's XML file format, long ago forked from Qt Designer's .ui format, has been extended to store the action assignment information. Following two new ''Qt properties'' have been added to the button widget class:

* onClickAction
* onClickActionOption

This addition produces the following XML node:
  <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. Following cases are supported:

* '''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. The '''{actionOption}''' property should be empty in this case.
* '''currentForm:{actionName}''' - a local action related to the current form. This case corresponds with actions from the 'Window Category' as described above. The '''{actionOption}''' property should be empty in this case.
* '''{objectType}:{objectName}''' - an action executed in the context of an object pointed by name and type. Both name and type may be needed because, 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 (scripts will be opened in design view if possible)
** '''execute''' - executes the object (only available for 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

Using the properties and prefixes makes the assignment format open for extensions. For instance, adding new actions, contexts, and object types is possible.

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 for 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 [https://kexi-project.org/wiki/wikiview/index.php@Form%20Actions.html], updated in Jun 2023 for the current code of 2023, removed references to Macros by jstaniek
}}