Action state and parameters

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 alpha-numeric, 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_parse_detailed_name() and g_action_print_detailed_name() but usually you will not need to. Most APIs will provide both ways of specifying actions with targets.