GtkAction

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

Functions

GtkAction * gtk_action_new ()
const gchar * gtk_action_get_name ()
gboolean gtk_action_is_sensitive ()
gboolean gtk_action_get_sensitive ()
void gtk_action_set_sensitive ()
gboolean gtk_action_is_visible ()
gboolean gtk_action_get_visible ()
void gtk_action_set_visible ()
void gtk_action_activate ()
GtkWidget * gtk_action_create_icon ()
GtkWidget * gtk_action_create_menu_item ()
GtkWidget * gtk_action_create_tool_item ()
GtkWidget * gtk_action_create_menu ()
void gtk_action_connect_proxy ()
void gtk_action_disconnect_proxy ()
GSList * gtk_action_get_proxies ()
void gtk_action_connect_accelerator ()
void gtk_action_disconnect_accelerator ()
void gtk_action_block_activate ()
void gtk_action_unblock_activate ()
void gtk_action_block_activate_from ()
void gtk_action_unblock_activate_from ()
gboolean gtk_action_get_always_show_image ()
void gtk_action_set_always_show_image ()
const gchar * gtk_action_get_accel_path ()
void gtk_action_set_accel_path ()
GClosure * gtk_action_get_accel_closure ()
void gtk_action_set_accel_group ()
void gtk_action_set_label ()
const gchar * gtk_action_get_label ()
void gtk_action_set_short_label ()
const gchar * gtk_action_get_short_label ()
void gtk_action_set_tooltip ()
const gchar * gtk_action_get_tooltip ()
void gtk_action_set_stock_id ()
const gchar * gtk_action_get_stock_id ()
void gtk_action_set_gicon ()
GIcon * gtk_action_get_gicon ()
void gtk_action_set_icon_name ()
const gchar * gtk_action_get_icon_name ()
void gtk_action_set_visible_horizontal ()
gboolean gtk_action_get_visible_horizontal ()
void gtk_action_set_visible_vertical ()
gboolean gtk_action_get_visible_vertical ()
void gtk_action_set_is_important ()
gboolean gtk_action_get_is_important ()

Properties

GtkActionGroup * action-group Read / Write
gboolean always-show-image Read / Write / Construct
GIcon * gicon Read / Write
gboolean hide-if-empty Read / Write
gchar * icon-name Read / Write
gboolean is-important Read / Write
gchar * label Read / Write
gchar * name Read / Write / Construct Only
gboolean sensitive Read / Write
gchar * short-label Read / Write
gchar * stock-id Read / Write
gchar * tooltip Read / Write
gboolean visible Read / Write
gboolean visible-horizontal Read / Write
gboolean visible-overflown Read / Write
gboolean visible-vertical Read / Write

Signals

Types and Values

struct GtkAction

Object Hierarchy

    GObject
    ╰── GtkAction
        ├── GtkToggleAction
        ╰── GtkRecentAction

Implemented Interfaces

GtkAction implements GtkBuildable.

Includes

#include <gtk/gtk.h>

Description

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:

  • 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)

The action will also have some state information:

  • 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 GtkAction 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.

Functions

gtk_action_new ()

GtkAction *
gtk_action_new (const gchar *name,
                const gchar *label,
                const gchar *tooltip,
                const gchar *stock_id);

Creates a new GtkAction object. To add the action to a GtkActionGroup and set the accelerator for the action, call gtk_action_group_add_action_with_accel(). See ??? for information on allowed action names.

Parameters

name

A unique name for the action

 

label

the label displayed in menu items and on buttons, or NULL.

[allow-none]

tooltip

a tooltip for the action, or NULL.

[allow-none]

stock_id

the stock icon to display in widgets representing the action, or NULL

 

Returns

a new GtkAction

Since: 2.4


gtk_action_get_name ()

const gchar *
gtk_action_get_name (GtkAction *action);

Returns the name of the action.

Parameters

action

the action object

 

Returns

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

Since: 2.4


gtk_action_is_sensitive ()

gboolean
gtk_action_is_sensitive (GtkAction *action);

Returns whether the action is effectively sensitive.

Parameters

action

the action object

 

Returns

TRUE if the action and its associated action group are both sensitive.

Since: 2.4


gtk_action_get_sensitive ()

gboolean
gtk_action_get_sensitive (GtkAction *action);

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

Parameters

action

the action object

 

Returns

TRUE if the action itself is sensitive.

Since: 2.4


gtk_action_set_sensitive ()

void
gtk_action_set_sensitive (GtkAction *action,
                          gboolean 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.

Parameters

action

the action object

 

sensitive

TRUE to make the action sensitive

 

Since: 2.6


gtk_action_is_visible ()

gboolean
gtk_action_is_visible (GtkAction *action);

Returns whether the action is effectively visible.

Parameters

action

the action object

 

Returns

TRUE if the action and its associated action group are both visible.

Since: 2.4


gtk_action_get_visible ()

gboolean
gtk_action_get_visible (GtkAction *action);

Returns whether the action itself is visible. Note that this doesn't necessarily mean effective visibility. See gtk_action_is_sensitive() for that.

Parameters

action

the action object

 

Returns

TRUE if the action itself is visible.

Since: 2.4


gtk_action_set_visible ()

void
gtk_action_set_visible (GtkAction *action,
                        gboolean 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.

Parameters

action

the action object

 

visible

TRUE to make the action visible

 

Since: 2.6


gtk_action_activate ()

void
gtk_action_activate (GtkAction *action);

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.

Parameters

action

the action object

 

Since: 2.4


gtk_action_create_icon ()

GtkWidget *
gtk_action_create_icon (GtkAction *action,
                        GtkIconSize icon_size);

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

Parameters

action

the action object

 

icon_size

the size of the icon that should be created.

[type int]

Returns

a widget that displays the icon for this action.

[transfer none]

Since: 2.4


gtk_action_create_menu_item ()

GtkWidget *
gtk_action_create_menu_item (GtkAction *action);

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

Parameters

action

the action object

 

Returns

a menu item connected to the action.

[transfer none]

Since: 2.4


gtk_action_create_tool_item ()

GtkWidget *
gtk_action_create_tool_item (GtkAction *action);

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

Parameters

action

the action object

 

Returns

a toolbar item connected to the action.

[transfer none]

Since: 2.4


gtk_action_create_menu ()

GtkWidget *
gtk_action_create_menu (GtkAction *action);

If action provides a GtkMenu widget as a submenu for the menu item or the toolbar item it creates, this function returns an instance of that menu.

Parameters

action

a GtkAction

 

Returns

the menu item provided by the action, or NULL.

[transfer none]

Since: 2.12


gtk_action_connect_proxy ()

void
gtk_action_connect_proxy (GtkAction *action,
                          GtkWidget *proxy);

gtk_action_connect_proxy has been deprecated since version 2.16 and should not be used in newly-written code.

Use gtk_activatable_set_related_action() instead.

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.

Parameters

action

the action object

 

proxy

the proxy widget

 

Since: 2.4


gtk_action_disconnect_proxy ()

void
gtk_action_disconnect_proxy (GtkAction *action,
                             GtkWidget *proxy);

gtk_action_disconnect_proxy has been deprecated since version 2.16 and should not be used in newly-written code.

Use gtk_activatable_set_related_action() instead.

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

Parameters

action

the action object

 

proxy

the proxy widget

 

Since: 2.4


gtk_action_get_proxies ()

GSList *
gtk_action_get_proxies (GtkAction *action);

Returns the proxy widgets for an action. See also gtk_widget_get_action().

Parameters

action

the action object

 

Returns

a GSList of proxy widgets. The list is owned by GTK+ and must not be modified.

[element-type GtkWidget][transfer none]

Since: 2.4


gtk_action_connect_accelerator ()

void
gtk_action_connect_accelerator (GtkAction *action);

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.

Parameters

action

a GtkAction

 

Since: 2.4


gtk_action_disconnect_accelerator ()

void
gtk_action_disconnect_accelerator (GtkAction *action);

Undoes the effect of one call to gtk_action_connect_accelerator().

Parameters

action

a GtkAction

 

Since: 2.4


gtk_action_block_activate ()

void
gtk_action_block_activate (GtkAction *action);

gtk_action_block_activate is deprecated and should not be used in newly-written code.

Disable activation signals from the action

This is needed when updating the state of your proxy GtkActivatable widget could result in calling gtk_action_activate(), this is a convenience function to avoid recursing in those cases (updating toggle state for instance).

Parameters

action

a GtkAction

 

Since: 2.16


gtk_action_unblock_activate ()

void
gtk_action_unblock_activate (GtkAction *action);

Reenable activation signals from the action

Parameters

action

a GtkAction

 

Since: 2.16


gtk_action_block_activate_from ()

void
gtk_action_block_activate_from (GtkAction *action,
                                GtkWidget *proxy);

gtk_action_block_activate_from has been deprecated since version 2.16 and should not be used in newly-written code.

activatables are now responsible for activating the action directly so this doesnt apply anymore.

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.

Parameters

action

the action object

 

proxy

a proxy widget

 

Since: 2.4


gtk_action_unblock_activate_from ()

void
gtk_action_unblock_activate_from (GtkAction *action,
                                  GtkWidget *proxy);

gtk_action_unblock_activate_from has been deprecated since version 2.16 and should not be used in newly-written code.

activatables are now responsible for activating the action directly so this doesnt apply anymore.

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.

Parameters

action

the action object

 

proxy

a proxy widget

 

Since: 2.4


gtk_action_get_always_show_image ()

gboolean
gtk_action_get_always_show_image (GtkAction *action);

Returns whether action 's menu item proxies will ignore the “gtk-menu-images” setting and always show their image, if available.

Parameters

action

a GtkAction

 

Returns

TRUE if the menu item proxies will always show their image

Since: 2.20


gtk_action_set_always_show_image ()

void
gtk_action_set_always_show_image (GtkAction *action,
                                  gboolean always_show);

Sets whether action 's menu item proxies will ignore the “gtk-menu-images” setting and always show their image, if available.

Use this if the menu item would be useless or hard to use without their image.

Parameters

action

a GtkAction

 

always_show

TRUE if menuitem proxies should always show their image

 

Since: 2.20


gtk_action_get_accel_path ()

const gchar *
gtk_action_get_accel_path (GtkAction *action);

Returns the accel path for this action.

Parameters

action

the action object

 

Returns

the accel path for this action, or NULL if none is set. The returned string is owned by GTK+ and must not be freed or modified.

Since: 2.6


gtk_action_set_accel_path ()

void
gtk_action_set_accel_path (GtkAction *action,
                           const gchar *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.

Note that accel_path string will be stored in a GQuark. Therefore, if you pass a static string, you can save some memory by interning it first with g_intern_static_string().

Parameters

action

the action object

 

accel_path

the accelerator path

 

Since: 2.4


gtk_action_get_accel_closure ()

GClosure *
gtk_action_get_accel_closure (GtkAction *action);

Returns the accel closure for this action.

Parameters

action

the action object

 

Returns

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

[transfer none]

Since: 2.8


gtk_action_set_accel_group ()

void
gtk_action_set_accel_group (GtkAction *action,
                            GtkAccelGroup *accel_group);

Sets the GtkAccelGroup in which the accelerator for this action will be installed.

Parameters

action

the action object

 

accel_group

a GtkAccelGroup or NULL.

[allow-none]

Since: 2.4


gtk_action_set_label ()

void
gtk_action_set_label (GtkAction *action,
                      const gchar *label);

Sets the label of action .

Parameters

action

a GtkAction

 

label

the label text to set

 

Since: 2.16


gtk_action_get_label ()

const gchar *
gtk_action_get_label (GtkAction *action);

Gets the label text of action .

Parameters

action

a GtkAction

 

Returns

the label text

Since: 2.16


gtk_action_set_short_label ()

void
gtk_action_set_short_label (GtkAction *action,
                            const gchar *short_label);

Sets a shorter label text on action .

Parameters

action

a GtkAction

 

short_label

the label text to set

 

Since: 2.16


gtk_action_get_short_label ()

const gchar *
gtk_action_get_short_label (GtkAction *action);

Gets the short label text of action .

Parameters

action

a GtkAction

 

Returns

the short label text.

Since: 2.16


gtk_action_set_tooltip ()

void
gtk_action_set_tooltip (GtkAction *action,
                        const gchar *tooltip);

Sets the tooltip text on action

Parameters

action

a GtkAction

 

tooltip

the tooltip text

 

Since: 2.16


gtk_action_get_tooltip ()

const gchar *
gtk_action_get_tooltip (GtkAction *action);

Gets the tooltip text of action .

Parameters

action

a GtkAction

 

Returns

the tooltip text

Since: 2.16


gtk_action_set_stock_id ()

void
gtk_action_set_stock_id (GtkAction *action,
                         const gchar *stock_id);

Sets the stock id on action

Parameters

action

a GtkAction

 

stock_id

the stock id

 

Since: 2.16


gtk_action_get_stock_id ()

const gchar *
gtk_action_get_stock_id (GtkAction *action);

Gets the stock id of action .

Parameters

action

a GtkAction

 

Returns

the stock id

Since: 2.16


gtk_action_set_gicon ()

void
gtk_action_set_gicon (GtkAction *action,
                      GIcon *icon);

Sets the icon of action .

Parameters

action

a GtkAction

 

icon

the GIcon to set

 

Since: 2.16


gtk_action_get_gicon ()

GIcon *
gtk_action_get_gicon (GtkAction *action);

Gets the gicon of action .

Parameters

action

a GtkAction

 

Returns

The action's GIcon if one is set.

[transfer none]

Since: 2.16


gtk_action_set_icon_name ()

void
gtk_action_set_icon_name (GtkAction *action,
                          const gchar *icon_name);

Sets the icon name on action

Parameters

action

a GtkAction

 

icon_name

the icon name to set

 

Since: 2.16


gtk_action_get_icon_name ()

const gchar *
gtk_action_get_icon_name (GtkAction *action);

Gets the icon name of action .

Parameters

action

a GtkAction

 

Returns

the icon name

Since: 2.16


gtk_action_set_visible_horizontal ()

void
gtk_action_set_visible_horizontal (GtkAction *action,
                                   gboolean visible_horizontal);

Sets whether action is visible when horizontal

Parameters

action

a GtkAction

 

visible_horizontal

whether the action is visible horizontally

 

Since: 2.16


gtk_action_get_visible_horizontal ()

gboolean
gtk_action_get_visible_horizontal (GtkAction *action);

Checks whether action is visible when horizontal

Parameters

action

a GtkAction

 

Returns

whether action is visible when horizontal

Since: 2.16


gtk_action_set_visible_vertical ()

void
gtk_action_set_visible_vertical (GtkAction *action,
                                 gboolean visible_vertical);

Sets whether action is visible when vertical

Parameters

action

a GtkAction

 

visible_vertical

whether the action is visible vertically

 

Since: 2.16


gtk_action_get_visible_vertical ()

gboolean
gtk_action_get_visible_vertical (GtkAction *action);

Checks whether action is visible when horizontal

Parameters

action

a GtkAction

 

Returns

whether action is visible when horizontal

Since: 2.16


gtk_action_set_is_important ()

void
gtk_action_set_is_important (GtkAction *action,
                             gboolean is_important);

Sets whether the action is important, this attribute is used primarily by toolbar items to decide whether to show a label or not.

Parameters

action

the action object

 

is_important

TRUE to make the action important

 

Since: 2.16


gtk_action_get_is_important ()

gboolean
gtk_action_get_is_important (GtkAction *action);

Checks whether action is important or not

Parameters

action

a GtkAction

 

Returns

whether action is important

Since: 2.16

Types and Values

struct GtkAction

struct GtkAction;

Property Details

The “action-group” property

  “action-group”             GtkActionGroup *

The GtkActionGroup this GtkAction is associated with, or NULL (for internal use).

Flags: Read / Write


The “always-show-image” property

  “always-show-image”        gboolean

If TRUE, the action's menu item proxies will ignore the “gtk-menu-images” setting and always show their image, if available.

Use this property if the menu item would be useless or hard to use without their image.

Flags: Read / Write / Construct

Default value: FALSE

Since: 2.20


The “gicon” property

  “gicon”                    GIcon *

The GIcon displayed in the GtkAction.

Note that the stock icon is preferred, if the “stock-id” property holds the id of an existing stock icon.

This is an appearance property and thus only applies if “use-action-appearance” is TRUE.

Flags: Read / Write

Since: 2.16


The “hide-if-empty” property

  “hide-if-empty”            gboolean

When TRUE, empty menu proxies for this action are hidden.

Flags: Read / Write

Default value: TRUE


The “icon-name” property

  “icon-name”                gchar *

The name of the icon from the icon theme.

Note that the stock icon is preferred, if the “stock-id” property holds the id of an existing stock icon, and the GIcon is preferred if the “gicon” property is set.

This is an appearance property and thus only applies if “use-action-appearance” is TRUE.

Flags: Read / Write

Default value: NULL

Since: 2.10


The “is-important” property

  “is-important”             gboolean

Whether the action is considered important. When TRUE, toolitem proxies for this action show text in GTK_TOOLBAR_BOTH_HORIZ mode.

Flags: Read / Write

Default value: FALSE


The “label” property

  “label”                    gchar *

The label used for menu items and buttons that activate this action. If the label is NULL, GTK+ uses the stock label specified via the stock-id property.

This is an appearance property and thus only applies if “use-action-appearance” is TRUE.

Flags: Read / Write

Default value: NULL


The “name” property

  “name”                     gchar *

A unique name for the action.

Flags: Read / Write / Construct Only

Default value: NULL


The “sensitive” property

  “sensitive”                gboolean

Whether the action is enabled.

Flags: Read / Write

Default value: TRUE


The “short-label” property

  “short-label”              gchar *

A shorter label that may be used on toolbar buttons.

This is an appearance property and thus only applies if “use-action-appearance” is TRUE.

Flags: Read / Write

Default value: NULL


The “stock-id” property

  “stock-id”                 gchar *

The stock icon displayed in widgets representing this action.

This is an appearance property and thus only applies if “use-action-appearance” is TRUE.

Flags: Read / Write

Default value: NULL


The “tooltip” property

  “tooltip”                  gchar *

A tooltip for this action.

Flags: Read / Write

Default value: NULL


The “visible” property

  “visible”                  gboolean

Whether the action is visible.

Flags: Read / Write

Default value: TRUE


The “visible-horizontal” property

  “visible-horizontal”       gboolean

Whether the toolbar item is visible when the toolbar is in a horizontal orientation.

Flags: Read / Write

Default value: TRUE


The “visible-overflown” property

  “visible-overflown”        gboolean

When TRUE, toolitem proxies for this action are represented in the toolbar overflow menu.

Flags: Read / Write

Default value: TRUE

Since: 2.6


The “visible-vertical” property

  “visible-vertical”         gboolean

Whether the toolbar item is visible when the toolbar is in a vertical orientation.

Flags: Read / Write

Default value: TRUE

Signal Details

The “activate” signal

void
user_function (GtkAction *action,
               gpointer   user_data)

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

Parameters

action

the GtkAction

 

user_data

user data set when the signal handler was connected.

 

Flags: No Recursion

Since: 2.4