Most actions in your application will be stateless actions with no parameters. These typically appear as menu items with no special decoration. An example is “quit”.
Stateful actions are used to represent an action which has a closely-associated state of some kind. A good example is a “fullscreen” action. For this case, you would expect to see a checkmark next to the menu item when the fullscreen option is active. This is usually called a toggle action, and it has a boolean state. By convention, toggle actions have no parameter type for activation: activating the action always toggles the state.
Another common case is to have an action representing a enumeration of possible values of a given type (typically string). This is often called a radio action and is usually represented in the user interface with radio buttons or radio menu items, or sometimes a combobox. A good example is “text-justify” with possible values “left”, “center”, and “right”. By convention, these types of actions have a parameter type equal to their state type, and activating them with a particular parameter value is equivalent to changing their state to that value.
This approach to handling radio buttons is different than many other action systems such as GtkAction. With GAction, there is only one action for “text-justify” and “left”, “center” and “right” are possible states on that action. There are not three separate “justify-left”, “justify-center” and “justify-right” actions.
The final common type of action is a stateless action with a parameter. This is typically used for actions like “open-bookmark” where the parameter to the action would be the identifier of the bookmark to open.
Because some types of actions cannot be invoked without a parameter, it is often important to specify a parameter when referring to the action from a place where it will be invoked (such as from a radio button that sets the state to a particular value or from a menu item that opens a specific bookmark). In these contexts, the value used for the action parameter is typically called the target of the action.
Even though toggle actions have a state, they do not have a parameter. Therefore, a target value is not needed when referring to them — they will always be toggled on activation.
Most APIs that allow using a GAction (such as GMenuModel and GtkActionable) allow use of detailed action names. This is a convenient way of specifying an action name and an action target with a single string.
In the case that the action target is a string with no unusual characters (ie: only alphanumeric, plus “-” and “.”) then you can use a detailed action name of the form “justify::left” to specify the justify action with a target of left.
In the case that the action target is not a string, or contains unusual characters, you can use the more general format “action-name(5)”, where the “5” here is any valid text-format GVariant (ie: a string that can be parsed by
g_variant_parse()). Another example is “open-bookmark(‘http://gnome.org/’)”.
You can convert between detailed action names and split-out action names and target values using
g_action_print_detailed_name() but usually you will not need to. Most APIs will provide both ways of specifying actions with targets.
© 2005–2020 The GNOME Project
Licensed under the GNU Lesser General Public License version 2.1 or later.