## GtkAction

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

## Synopsis

    #include <gtk/gtk.h>

    struct              GtkAction;
    GtkAction *         gtk_action_new                      (const gchar *name,
                                                             const gchar *label,
                                                             const gchar *tooltip,
                                                             const gchar *stock_id);
    const gchar *       gtk_action_get_name                 (GtkAction *action);
    gboolean            gtk_action_is_sensitive             (GtkAction *action);
    gboolean            gtk_action_get_sensitive            (GtkAction *action);
    void                gtk_action_set_sensitive            (GtkAction *action,
                                                             gboolean sensitive);
    gboolean            gtk_action_is_visible               (GtkAction *action);
    gboolean            gtk_action_get_visible              (GtkAction *action);
    void                gtk_action_set_visible              (GtkAction *action,
                                                             gboolean visible);
    void                gtk_action_activate                 (GtkAction *action);
    GtkWidget *         gtk_action_create_icon              (GtkAction *action,
                                                             GtkIconSize icon_size);
    GtkWidget *         gtk_action_create_menu_item         (GtkAction *action);
    GtkWidget *         gtk_action_create_tool_item         (GtkAction *action);
    GtkWidget *         gtk_action_create_menu              (GtkAction *action);
    GSList *            gtk_action_get_proxies              (GtkAction *action);
    void                gtk_action_connect_accelerator      (GtkAction *action);
    void                gtk_action_disconnect_accelerator   (GtkAction *action);
    void                gtk_action_block_activate           (GtkAction *action);
    void                gtk_action_unblock_activate         (GtkAction *action);
    gboolean            gtk_action_get_always_show_image    (GtkAction *action);
    void                gtk_action_set_always_show_image    (GtkAction *action,
                                                             gboolean always_show);
    const gchar *       gtk_action_get_accel_path           (GtkAction *action);
    void                gtk_action_set_accel_path           (GtkAction *action,
                                                             const gchar *accel_path);
    GClosure *          gtk_action_get_accel_closure        (GtkAction *action);
    void                gtk_action_set_accel_group          (GtkAction *action,
                                                             GtkAccelGroup *accel_group);
    void                gtk_action_set_label                (GtkAction *action,
                                                             const gchar *label);
    const gchar *       gtk_action_get_label                (GtkAction *action);
    void                gtk_action_set_short_label          (GtkAction *action,
                                                             const gchar *short_label);
    const gchar *       gtk_action_get_short_label          (GtkAction *action);
    void                gtk_action_set_tooltip              (GtkAction *action,
                                                             const gchar *tooltip);
    const gchar *       gtk_action_get_tooltip              (GtkAction *action);
    void                gtk_action_set_stock_id             (GtkAction *action,
                                                             const gchar *stock_id);
    const gchar *       gtk_action_get_stock_id             (GtkAction *action);
    void                gtk_action_set_gicon                (GtkAction *action,
                                                             GIcon *icon);
    GIcon *             gtk_action_get_gicon                (GtkAction *action);
    void                gtk_action_set_icon_name            (GtkAction *action,
                                                             const gchar *icon_name);
    const gchar *       gtk_action_get_icon_name            (GtkAction *action);
    void                gtk_action_set_visible_horizontal   (GtkAction *action,
                                                             gboolean visible_horizontal);
    gboolean            gtk_action_get_visible_horizontal   (GtkAction *action);
    void                gtk_action_set_visible_vertical     (GtkAction *action,
                                                             gboolean visible_vertical);
    gboolean            gtk_action_get_visible_vertical     (GtkAction *action);
    void                gtk_action_set_is_important         (GtkAction *action,
                                                             gboolean is_important);
    gboolean            gtk_action_get_is_important         (GtkAction *action);

## Object Hierarchy

      GObject
       +----GtkAction
             +----GtkToggleAction
             +----GtkRecentAction

## Implemented Interfaces

GtkAction implements GtkBuildable.

## Properties

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

## Signals

      "activate"                                       : No Recursion

## 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 widgets. To act as an action proxy, widget needs to implement GtkActivatable interface. Proxies mirror the state of the action and should change when the action's state changes. Properties that are always mirrored by proxies are "sensitive" and "visible". "gicon", "icon-name", "label", "short-label" and "stock-id" properties are only mirorred if proxy widget has "use-action-appearance" property set to `TRUE`.

When the proxy is activated, it should activate its action.

## Details

### struct GtkAction

    struct GtkAction;

### 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 the section called “UI Definitions” for information on allowed action names.

`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`. [allow-none]
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.

`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.

`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.

`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.

`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.

`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.

`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.

`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.

`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.

`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.

`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.

`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.

`action` : | a GtkAction
Returns : | the menu item provided by the action, or `NULL`. [transfer none]

Since 2.12

### gtk_action_get_proxies ()

    GSList *            gtk_action_get_proxies              (GtkAction *action);

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

`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.

`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()`.

`action` : | a GtkAction

Since 2.4

### gtk_action_block_activate ()

    void                gtk_action_block_activate           (GtkAction *action);

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

`action` : | a GtkAction

Since 2.16

### gtk_action_unblock_activate ()

    void                gtk_action_unblock_activate         (GtkAction *action);

Reenable activation signals from the action

`action` : | a GtkAction

Since 2.16

### 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.

`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.

`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.

`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()`.

`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.

`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.

`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`.

`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`.

`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`.

`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`.

`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`

`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`.

`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`

`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`.

`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`.

`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`.

`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`

`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`.

`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

`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

`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

`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

`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.

`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

`action` : | a GtkAction
Returns : | whether `action` is important

Since 2.16

## Property Details

### The `"action-group"` property

      "action-group"             GtkActionGroup*       : Read / Write

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

### The `"always-show-image"` property

      "always-show-image"        gboolean              : Read / Write / Construct

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.

Default value: FALSE

Since 2.20

### The `"gicon"` property

      "gicon"                    GIcon*                : Read / Write

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`.

Since 2.16

### The `"hide-if-empty"` property

      "hide-if-empty"            gboolean              : Read / Write

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

Default value: TRUE

### The `"icon-name"` property

      "icon-name"                gchar*                : Read / Write

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`.

Default value: NULL

Since 2.10

### The `"is-important"` property

      "is-important"             gboolean              : Read / Write

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

Default value: FALSE

### The `"label"` property

      "label"                    gchar*                : Read / Write

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`.

Default value: NULL

### The `"name"` property

      "name"                     gchar*                : Read / Write / Construct Only

A unique name for the action.

Default value: NULL

### The `"sensitive"` property

      "sensitive"                gboolean              : Read / Write

Whether the action is enabled.

Default value: TRUE

### The `"short-label"` property

      "short-label"              gchar*                : Read / Write

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`.

Default value: NULL

### The `"stock-id"` property

      "stock-id"                 gchar*                : Read / Write

The stock icon displayed in widgets representing this action.

This is an appearance property and thus only applies if "use-action-appearance" is `TRUE`.

Default value: NULL

### The `"tooltip"` property

      "tooltip"                  gchar*                : Read / Write

A tooltip for this action.

Default value: NULL

### The `"visible"` property

      "visible"                  gboolean              : Read / Write

Whether the action is visible.

Default value: TRUE

### The `"visible-horizontal"` property

      "visible-horizontal"       gboolean              : Read / Write

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

Default value: TRUE

### The `"visible-overflown"` property

      "visible-overflown"        gboolean              : Read / Write

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

Default value: TRUE

Since 2.6

### The `"visible-vertical"` property

      "visible-vertical"         gboolean              : Read / Write

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

Default value: TRUE

## Signal Details

### The `"activate"` signal

    void                user_function                      (GtkAction *action,
                                                            gpointer   user_data)      : No Recursion

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

`action` : | the GtkAction
`user_data` : | user data set when the signal handler was connected.

Since 2.4

## See Also

GtkActionGroup, GtkUIManager, GtkActivatable