/GTK 4.0

Overview of actions in GTK

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.