Overview of actions in GTK

Basics about actions
Action state and parameters
Action scopes
Action groups and action maps
Connecting actions to widgets
Activation
Built-in Actions

This chapter describes in detail how GTK uses actions to connect activatable UI elements to callbacks. GTK inherits the underlying architecture of GAction and GMe:u for describing abstract actions and menus from the GIO library.

A GAction is essentially a way to tell the toolkit about a piece of functionality in your program, and to give it a name.

Actions are purely functional. They do not contain any presentational information.

An action has four pieces of information associated with it:

  • a name as an identifier (usually all-lowercase, untranslated English string)

  • an enabled flag indicating if the action can be activated or not (like the “sensitive” property on widgets)

  • an optional state value, for stateful actions (like a boolean for toggles)

  • an optional parameter type, used when activating the action

An action supports two operations. You can activate it, which requires passing a parameter of the correct type And you can request to change the actions state (for stateful actions) to a new state value of the correct type.

Here are some rules about an action:

  • the name is immutable (in the sense that it will never change) and it is never NULL

  • the enabled flag can change

  • the parameter type is immutable

  • the parameter type is optional: it can be NULL

  • if the parameter type is NULL then action activation must be done without a parameter (ie: a NULL GVariant pointer)

  • if the parameter type is non-NULL then the parameter must have this type

  • the state can change, but it cannot change type

  • if the action was stateful when it was created, it will always have a state and it will always have exactly the same type (such as boolean or string)

  • if the action was stateless when it was created, it can never have a state

  • you can only request state changes on stateful actions and it is only possible to request that the state change to a value of the same type as the existing state

An action does not have any sort of presentational information such as a label, an icon or a way of creating a widget from it.

© 2005–2020 The GNOME Project
Licensed under the GNU Lesser General Public License version 2.1 or later.
https://developer.gnome.org/gtk4/4.0/actions-overview.html