GtkAction

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

Synopsis


#include <gtk/gtk.h>


                    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);
void                gtk_action_connect_proxy            (GtkAction *action,
                                                         GtkWidget *proxy);
void                gtk_action_disconnect_proxy         (GtkAction *action,
                                                         GtkWidget *proxy);
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_from      (GtkAction *action,
                                                         GtkWidget *proxy);
void                gtk_action_unblock_activate_from    (GtkAction *action,
                                                         GtkWidget *proxy);
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);

Object Hierarchy


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

Properties


  "action-group"             GtkActionGroup        : Read / Write
  "hide-if-empty"            gboolean              : Read / Write
  "icon-name"                gchararray            : Read / Write
  "is-important"             gboolean              : Read / Write
  "label"                    gchararray            : Read / Write
  "name"                     gchararray            : Read / Write / Construct Only
  "sensitive"                gboolean              : Read / Write
  "short-label"              gchararray            : Read / Write
  "stock-id"                 gchararray            : Read / Write
  "tooltip"                  gchararray            : Read / Write
  "visible"                  gboolean              : Read / Write
  "visible-horizontal"       gboolean              : Read / Write
  "visible-overflown"        gboolean              : Read / Write
  "visible-vertical"         gboolean              : Read / Write

Signals


  "activate"                                       : Run First / 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 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.

Details

GtkAction

typedef struct _GtkAction GtkAction;

The GtkAction struct contains only private members and should not be accessed directly.

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
`tooltip` :	a tooltip for the action
`stock_id` :	the stock icon to display in widgets representing the action
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.
Returns :	a widget that displays the icon for this action.

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.

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.

Since 2.4

gtk_action_connect_proxy ()

void                gtk_action_connect_proxy            (GtkAction *action,
                                                         GtkWidget *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

gtk_action_disconnect_proxy ()

void                gtk_action_disconnect_proxy         (GtkAction *action,
                                                         GtkWidget *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

gtk_action_get_proxies ()

GSList*             gtk_action_get_proxies              (GtkAction *action);

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

`action` :	the action object
Returns :	a GSList of proxy widgets. The list is owned by GTK+ and must not be modified.

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_from ()

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

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

gtk_action_unblock_activate_from ()

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

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

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.

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

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`

Since 2.4

Property Details

The "`action-group`" property

  "action-group"             GtkActionGroup        : Read / Write

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

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"                gchararray            : 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.

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"                    gchararray            : Read / Write

The label used for menu items and buttons that activate this action.

Default value: NULL

The "`name`" property

  "name"                     gchararray            : 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"              gchararray            : Read / Write

A shorter label that may be used on toolbar buttons.

Default value: NULL

The "`stock-id`" property

  "stock-id"                 gchararray            : Read / Write

The stock icon displayed in widgets representing this action.

Default value: NULL

The "`tooltip`" property

  "tooltip"                  gchararray            : 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)      : Run First / 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

			GTK+ Reference Manual
Top \| Description \| Object Hierarchy \| Properties \| Signals

GtkAction

Synopsis

Object Hierarchy

Properties

Signals

Description

Details

GtkAction

gtk_action_new ()

gtk_action_get_name ()

gtk_action_is_sensitive ()

gtk_action_get_sensitive ()

gtk_action_set_sensitive ()

gtk_action_is_visible ()

gtk_action_get_visible ()

gtk_action_set_visible ()

gtk_action_activate ()

gtk_action_create_icon ()

gtk_action_create_menu_item ()

gtk_action_create_tool_item ()

gtk_action_connect_proxy ()

gtk_action_disconnect_proxy ()

gtk_action_get_proxies ()

gtk_action_connect_accelerator ()

gtk_action_disconnect_accelerator ()

gtk_action_block_activate_from ()

gtk_action_unblock_activate_from ()

gtk_action_get_accel_path ()

gtk_action_set_accel_path ()

gtk_action_get_accel_closure ()

gtk_action_set_accel_group ()

Property Details

The "action-group" property

The "hide-if-empty" property

The "icon-name" property

The "is-important" property

The "label" property

The "name" property

The "sensitive" property

The "short-label" property

The "stock-id" property

The "tooltip" property

The "visible" property

The "visible-horizontal" property

The "visible-overflown" property

The "visible-vertical" property

Signal Details

The "activate" signal

See Also

The "`action-group`" property

The "`hide-if-empty`" property

The "`icon-name`" property

The "`is-important`" property

The "`label`" property

The "`name`" property

The "`sensitive`" property

The "`short-label`" property

The "`stock-id`" property

The "`tooltip`" property

The "`visible`" property

The "`visible-horizontal`" property

The "`visible-overflown`" property

The "`visible-vertical`" property