Next: , Previous: GtkActionGroup, Up: Top

74 GtkAction

An action which can be triggered by a menu or toolbar item

74.1 Overview

Actions represent operations that the user can be perform, along with some information how it should be presented in the interface. Each action provides methods to create icons, menu items and toolbar items representing itself.

As well as the callback that is called when the action gets activated, the following also gets associated with the action: The action will also have some state information:

a name (not translated, for path lookup)

a label (translated, for display)

an accelerator

whether label indicates a stock id

a tooltip (optional, translated)

a toolbar label (optional, shorter than label)

visible (shown/hidden)

sensitive (enabled/disabled)

Apart from regular actions, there are toggle actions, which can be toggled between two states and radio actions, of which only one in a group can be in the "active" state. Other actions can be implemented as <gtk-action> subclasses.

Each action can have one or more proxy menu item, toolbar button or other proxy widgets. Proxies mirror the state of the action (text label, tooltip, icon, visible, sensitive, etc), and should change when the action's state changes. When the proxy is activated, it should activate its action.

74.2 Usage

— Class: <gtk-action>

Derives from <gtk-buildable>, <gobject>.

This class defines the following slots:

name
A unique name for the action.
label
The label used for menu items and buttons that activate this action.
short-label
A shorter label that may be used on toolbar buttons.
tooltip
A tooltip for this action.
stock-id
The stock icon displayed in widgets representing this action.
icon-name
The name of the icon from the icon theme
visible-horizontal
Whether the toolbar item is visible when the toolbar is in a horizontal orientation.
visible-vertical
Whether the toolbar item is visible when the toolbar is in a vertical orientation.
visible-overflown
When TRUE, toolitem proxies for this action are represented in the toolbar overflow menu.
is-important
Whether the action is considered important. When TRUE, toolitem proxies for this action show text in GTK_TOOLBAR_BOTH_HORIZ mode.
hide-if-empty
When TRUE, empty menu proxies for this action are hidden.
sensitive
Whether the action is enabled.
visible
Whether the action is visible.
action-group
The GtkActionGroup this GtkAction is associated with, or NULL (for internal use).
— Signal on <gtk-action>: activate

The "activate" signal is emitted when the action is activated.

Since 2.4

— Function: gtk-action-new (name mchars) (label mchars) (tooltip mchars) (stock_id mchars) ⇒  (ret <gtk-action>)

Creates a new <gtk-action> object. To add the action to a <gtk-action-group> and set the accelerator for the action, call gtk-action-group-add-action-with-accel. See (the missing figure, XML-UI for information on allowed action names.

name
A unique name for the action
label
the label displayed in menu items and on buttons
tooltip
a tooltip for the action
stock-id
the stock icon to display in widgets representing the action
ret
a new <gtk-action>

Since 2.4

— Function: gtk-action-get-name (self <gtk-action>) ⇒  (ret mchars)
— Method: get-name

Returns the name of the action.

action
the action object
ret
the name of the action. The string belongs to GTK+ and should not be freed.

Since 2.4

— Function: gtk-action-is-sensitive (self <gtk-action>) ⇒  (ret bool)
— Method: is-sensitive

Returns whether the action is effectively sensitive.

action
the action object
ret
‘#t’ if the action and its associated action group are both sensitive.

Since 2.4

— Function: gtk-action-get-sensitive (self <gtk-action>) ⇒  (ret bool)
— Method: get-sensitive

Returns whether the action itself is sensitive. Note that this doesn't necessarily mean effective sensitivity. See gtk-action-is-sensitive for that.

action
the action object
ret
‘#t’ if the action itself is sensitive.

Since 2.4

— Function: gtk-action-set-sensitive (self <gtk-action>) (sensitive bool)
— Method: set-sensitive

Sets the ::sensitive property of the action to sensitive. Note that this doesn't necessarily mean effective sensitivity. See gtk-action-is-sensitive for that.

action
the action object
sensitive
‘#t’ to make the action sensitive

Since 2.6

— Function: gtk-action-is-visible (self <gtk-action>) ⇒  (ret bool)
— Method: is-visible

Returns whether the action is effectively visible.

action
the action object
ret
‘#t’ if the action and its associated action group are both visible.

Since 2.4

— Function: gtk-action-get-visible (self <gtk-action>) ⇒  (ret bool)
— Method: get-visible

Returns whether the action itself is visible. Note that this doesn't necessarily mean effective visibility. See gtk-action-is-sensitive for that.

action
the action object
ret
‘#t’ if the action itself is visible.

Since 2.4

— Function: gtk-action-set-visible (self <gtk-action>) (visible bool)
— Method: set-visible

Sets the ::visible property of the action to visible. Note that this doesn't necessarily mean effective visibility. See gtk-action-is-visible for that.

action
the action object
visible
‘#t’ to make the action visible

Since 2.6

— Function: gtk-action-activate (self <gtk-action>)
— Method: activate

Emits the "activate" signal on the specified action, if it isn't insensitive. This gets called by the proxy widgets when they get activated.

It can also be used to manually activate an action.

action
the action object

Since 2.4

— Function: gtk-action-create-icon (self <gtk-action>) (icon_size <gtk-icon-size>) ⇒  (ret <gtk-widget>)
— Method: create-icon

This function is intended for use by action implementations to create icons displayed in the proxy widgets.

action
the action object
icon-size
the size of the icon that should be created.
ret
a widget that displays the icon for this action.

Since 2.4

— Function: gtk-action-create-menu-item (self <gtk-action>) ⇒  (ret <gtk-widget>)
— Method: create-menu-item

Creates a menu item widget that proxies for the given action.

action
the action object
ret
a menu item connected to the action.

Since 2.4

— Function: gtk-action-create-tool-item (self <gtk-action>) ⇒  (ret <gtk-widget>)
— Method: create-tool-item

Creates a toolbar item widget that proxies for the given action.

action
the action object
ret
a toolbar item connected to the action.

Since 2.4

— Function: gtk-action-connect-proxy (self <gtk-action>) (proxy <gtk-widget>)
— Method: connect-proxy

Connects a widget to an action object as a proxy. Synchronises various properties of the action with the widget (such as label text, icon, tooltip, etc), and attaches a callback so that the action gets activated when the proxy widget does.

If the widget is already connected to an action, it is disconnected first.

action
the action object
proxy
the proxy widget

Since 2.4

— Function: gtk-action-disconnect-proxy (self <gtk-action>) (proxy <gtk-widget>)
— Method: disconnect-proxy

Disconnects a proxy widget from an action. Does not destroy the widget, however.

action
the action object
proxy
the proxy widget

Since 2.4

— Function: gtk-action-get-proxies (self <gtk-action>) ⇒  (ret gslist-of)
— Method: get-proxies

Returns the proxy widgets for an action. See also gtk-widget-get-action.

action
the action object
ret
a <gs-list> of proxy widgets. The list is owned by GTK+ and must not be modified.

Since 2.4

— Function: gtk-action-connect-accelerator (self <gtk-action>)
— Method: connect-accelerator

Installs the accelerator for action if action has an accel path and group. See gtk-action-set-accel-path and gtk-action-set-accel-group

Since multiple proxies may independently trigger the installation of the accelerator, the action counts the number of times this function has been called and doesn't remove the accelerator until gtk-action-disconnect-accelerator has been called as many times.

action
a <gtk-action>

Since 2.4

— Function: gtk-action-disconnect-accelerator (self <gtk-action>)
— Method: disconnect-accelerator

Undoes the effect of one call to gtk-action-connect-accelerator.

action
a <gtk-action>

Since 2.4

— Function: gtk-action-block-activate-from (self <gtk-action>) (proxy <gtk-widget>)
— Method: block-activate-from

Disables calls to the gtk-action-activate function by signals on the given proxy widget. This is used to break notification loops for things like check or radio actions.

This function is intended for use by action implementations.

action
the action object
proxy
a proxy widget

Since 2.4

— Function: gtk-action-unblock-activate-from (self <gtk-action>) (proxy <gtk-widget>)
— Method: unblock-activate-from

Re-enables calls to the gtk-action-activate function by signals on the given proxy widget. This undoes the blocking done by gtk-action-block-activate-from.

This function is intended for use by action implementations.

action
the action object
proxy
a proxy widget

Since 2.4

— Function: gtk-action-get-accel-path (self <gtk-action>) ⇒  (ret mchars)
— Method: get-accel-path

Returns the accel path for this action.

action
the action object
ret
the accel path for this action, or ‘#f’ if none is set. The returned string is owned by GTK+ and must not be freed or modified.

Since 2.6

— Function: gtk-action-set-accel-path (self <gtk-action>) (accel_path mchars)
— Method: set-accel-path

Sets the accel path for this action. All proxy widgets associated with the action will have this accel path, so that their accelerators are consistent.

action
the action object
accel-path
the accelerator path

Since 2.4

— Function: gtk-action-get-accel-closure (self <gtk-action>) ⇒  (ret <gclosure>)
— Method: get-accel-closure

Returns the accel closure for this action.

action
the action object
ret
the accel closure for this action. The returned closure is owned by GTK+ and must not be unreffed or modified.

Since 2.8

— Function: gtk-action-set-accel-group (self <gtk-action>) (accel_group <gtk-accel-group>)
— Method: set-accel-group

Sets the <gtk-accel-group> in which the accelerator for this action will be installed.

action
the action object
accel-group
a <gtk-accel-group> or ‘#f’

Since 2.4