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:
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.
Functions
gtk_action_get_name ()
const gchar *
gtk_action_get_name (GtkAction *action);
gtk_action_get_name has been deprecated since version 3.10 and should not be used in newly-written code.
Use g_action_get_name() on a GAction instead
Returns the name of the action.
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);
gtk_action_is_sensitive has been deprecated since version 3.10 and should not be used in newly-written code.
Use g_action_get_enabled() on a GAction
instead
Returns whether the action is effectively sensitive.
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);
gtk_action_get_sensitive has been deprecated since version 3.10 and should not be used in newly-written code.
Use g_action_get_enabled() on a GAction
instead
Returns whether the action itself is sensitive. Note that this doesn’t
necessarily mean effective sensitivity. See gtk_action_is_sensitive()
for that.
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.
Since: 2.6
gtk_action_is_visible ()
gboolean
gtk_action_is_visible (GtkAction *action);
gtk_action_is_visible has been deprecated since version 3.10 and should not be used in newly-written code.
Use GAction instead, and control and monitor the state of
GtkActionable widgets directly
Returns whether the action is effectively visible.
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);
gtk_action_get_visible has been deprecated since version 3.10 and should not be used in newly-written code.
Use GAction instead, and control and monitor the state of
GtkActionable widgets directly
Returns whether the action itself is visible. Note that this doesn’t
necessarily mean effective visibility. See gtk_action_is_sensitive()
for that.
Returns
TRUE if the action itself is visible.
Since: 2.4
gtk_action_set_visible ()
void
gtk_action_set_visible (GtkAction *action,
gboolean visible);
gtk_action_set_visible has been deprecated since version 3.10 and should not be used in newly-written code.
Use GAction instead, and control and monitor the state of
GtkActionable widgets directly
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.
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.
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.
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);
gtk_action_create_menu_item has been deprecated since version 3.10 and should not be used in newly-written code.
Use g_menu_item_new() and associate it with a GAction
instead.
Creates a menu item widget that proxies for the given action.
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.
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.
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);
gtk_action_get_proxies has been deprecated since version 3.10 and should not be used in newly-written code.
Returns the proxy widgets for an action.
See also gtk_activatable_get_related_action().
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);
gtk_action_connect_accelerator has been deprecated since version 3.10 and should not be used in newly-written code.
Use GAction and the accelerator group on an associated
GtkMenu instead
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.
Since: 2.4
gtk_action_disconnect_accelerator ()
void
gtk_action_disconnect_accelerator (GtkAction *action);
gtk_action_disconnect_accelerator has been deprecated since version 3.10 and should not be used in newly-written code.
Use GAction and the accelerator group on an associated
GtkMenu instead
Undoes the effect of one call to gtk_action_connect_accelerator().
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).
Since: 2.16
gtk_action_unblock_activate ()
void
gtk_action_unblock_activate (GtkAction *action);
Reenable activation signals from the action
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 always
show their image, if available.
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);
gtk_action_set_always_show_image has been deprecated since version 3.10 and should not be used in newly-written code.
Use g_menu_item_set_icon() on a GMenuItem instead, if the
item should have an image
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.
Since: 2.20
gtk_action_get_accel_path ()
const gchar *
gtk_action_get_accel_path (GtkAction *action);
gtk_action_get_accel_path has been deprecated since version 3.10 and should not be used in newly-written code.
Use GAction and the accelerator path on an associated
GtkMenu instead
Returns the accel path for this action.
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);
gtk_action_set_accel_path has been deprecated since version 3.10 and should not be used in newly-written code.
Use GAction and the accelerator path on an associated
GtkMenu instead
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().
Since: 2.4
gtk_action_get_accel_closure ()
GClosure *
gtk_action_get_accel_closure (GtkAction *action);
gtk_action_get_accel_closure has been deprecated since version 3.10 and should not be used in newly-written code.
Use GAction and GtkMenu instead, which have no
equivalent for getting the accel closure
Returns the accel closure for this action.
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);
gtk_action_set_accel_group has been deprecated since version 3.10 and should not be used in newly-written code.
Use GAction and the accelerator group on an associated
GtkMenu instead
Sets the GtkAccelGroup in which the accelerator for this action
will be installed.
Since: 2.4
gtk_action_set_label ()
void
gtk_action_set_label (GtkAction *action,
const gchar *label);
gtk_action_set_label has been deprecated since version 3.10 and should not be used in newly-written code.
Use GAction instead, and set a label on a menu item with
g_menu_item_set_label(). For GtkActionable widgets, use the widget-specific
API to set a label
Sets the label of action
.
Since: 2.16
gtk_action_get_label ()
const gchar *
gtk_action_get_label (GtkAction *action);
gtk_action_get_label has been deprecated since version 3.10 and should not be used in newly-written code.
Use GAction instead, and get a label from a menu item
with g_menu_item_get_attribute_value(). For GtkActionable widgets, use the
widget-specific API to get a label
Gets the label text of action
.
Since: 2.16
gtk_action_set_short_label ()
void
gtk_action_set_short_label (GtkAction *action,
const gchar *short_label);
gtk_action_set_short_label has been deprecated since version 3.10 and should not be used in newly-written code.
Use GAction instead, which has no equivalent of short
labels
Sets a shorter label text on action
.
Since: 2.16
gtk_action_get_short_label ()
const gchar *
gtk_action_get_short_label (GtkAction *action);
gtk_action_get_short_label has been deprecated since version 3.10 and should not be used in newly-written code.
Use GAction instead, which has no equivalent of short
labels
Gets the short label text of action
.
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
Since: 2.16
gtk_action_get_tooltip ()
const gchar *
gtk_action_get_tooltip (GtkAction *action);
Gets the tooltip text of action
.
Since: 2.16
gtk_action_set_stock_id ()
void
gtk_action_set_stock_id (GtkAction *action,
const gchar *stock_id);
gtk_action_set_stock_id has been deprecated since version 3.10 and should not be used in newly-written code.
Use GAction instead, which has no equivalent of stock
items
Sets the stock id on action
Since: 2.16
gtk_action_get_stock_id ()
const gchar *
gtk_action_get_stock_id (GtkAction *action);
gtk_action_get_stock_id has been deprecated since version 3.10 and should not be used in newly-written code.
Use GAction instead, which has no equivalent of stock
items
Gets the stock id of action
.
Since: 2.16
gtk_action_set_gicon ()
void
gtk_action_set_gicon (GtkAction *action,
GIcon *icon);
Sets the icon of action
.
Since: 2.16
gtk_action_get_gicon ()
GIcon *
gtk_action_get_gicon (GtkAction *action);
Gets the gicon of action
.
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
Since: 2.16
gtk_action_get_icon_name ()
const gchar *
gtk_action_get_icon_name (GtkAction *action);
Gets the icon name of action
.
Since: 2.16
gtk_action_set_visible_horizontal ()
void
gtk_action_set_visible_horizontal (GtkAction *action,
gboolean visible_horizontal);
gtk_action_set_visible_horizontal has been deprecated since version 3.10 and should not be used in newly-written code.
Use GAction instead, and control and monitor the
visibility of associated widgets and menu items directly
Sets whether action
is visible when horizontal
Since: 2.16
gtk_action_get_visible_horizontal ()
gboolean
gtk_action_get_visible_horizontal (GtkAction *action);
gtk_action_get_visible_horizontal has been deprecated since version 3.10 and should not be used in newly-written code.
Use GAction instead, and control and monitor the
visibility of associated widgets and menu items directly
Checks whether action
is visible when horizontal
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);
gtk_action_set_visible_vertical has been deprecated since version 3.10 and should not be used in newly-written code.
Use GAction instead, and control and monitor the
visibility of associated widgets and menu items directly
Sets whether action
is visible when vertical
Since: 2.16
gtk_action_get_visible_vertical ()
gboolean
gtk_action_get_visible_vertical (GtkAction *action);
gtk_action_get_visible_vertical has been deprecated since version 3.10 and should not be used in newly-written code.
Use GAction instead, and control and monitor the
visibility of associated widgets and menu items directly
Checks whether action
is visible when horizontal
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);
gtk_action_set_is_important has been deprecated since version 3.10 and should not be used in newly-written code.
Use GAction instead, and control and monitor whether
labels are shown directly
Sets whether the action is important, this attribute is used
primarily by toolbar items to decide whether to show a label
or not.
Since: 2.16
gtk_action_get_is_important ()
gboolean
gtk_action_get_is_important (GtkAction *action);
gtk_action_get_is_important has been deprecated since version 3.10 and should not be used in newly-written code.
Use GAction instead, and control and monitor whether
labels are shown directly
Checks whether action
is important or not
Returns
whether action
is important
Since: 2.16
Property Details
The “action-group” property
“action-group” GtkActionGroup *
The GtkActionGroup this GtkAction is associated with, or NULL
(for internal use).
Owner: GtkAction
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.
GtkAction:always-show-image has been deprecated since version 3.10 and should not be used in newly-written code.
There is no corresponding replacement when using
GAction
Owner: GtkAction
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.
GtkAction:gicon has been deprecated since version 3.10 and should not be used in newly-written code.
Use the "icon" attribute on a GMenuItem instead
Owner: GtkAction
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.
GtkAction:hide-if-empty has been deprecated since version 3.10 and should not be used in newly-written code.
There is no corresponding replacement when using
GAction
Owner: GtkAction
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.
GtkAction:icon-name has been deprecated since version 3.10 and should not be used in newly-written code.
Use the "icon" attribute on a GMenuItem instead
Owner: GtkAction
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.
GtkAction:is-important has been deprecated since version 3.10 and should not be used in newly-written code.
There is no corresponding replacement when using
GAction
Owner: GtkAction
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.
GtkAction:label has been deprecated since version 3.10 and should not be used in newly-written code.
Use the "label" attribute on GMenuItem instead
Owner: GtkAction
Flags: Read / Write
Default value: NULL
The “name” property
“name” gchar *
A unique name for the action.
GtkAction:name has been deprecated since version 3.10 and should not be used in newly-written code.
Use “name” instead
Owner: GtkAction
Flags: Read / Write / Construct Only
Default value: NULL
The “sensitive” property
“sensitive” gboolean
Whether the action is enabled.
GtkAction:sensitive has been deprecated since version 3.10 and should not be used in newly-written code.
Use “enabled” and “enabled”
instead
Owner: GtkAction
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.
GtkAction:short-label has been deprecated since version 3.10 and should not be used in newly-written code.
There is no corresponding replacement when using
GAction
Owner: GtkAction
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.
GtkAction:stock-id has been deprecated since version 3.10 and should not be used in newly-written code.
There is no corresponding replacement when using
GAction
Owner: GtkAction
Flags: Read / Write
Default value: NULL
The “tooltip” property
“tooltip” gchar *
A tooltip for this action.
Owner: GtkAction
Flags: Read / Write
Default value: NULL
The “visible” property
“visible” gboolean
Whether the action is visible.
GtkAction:visible has been deprecated since version 3.10 and should not be used in newly-written code.
There is no corresponding replacement when using
GAction
Owner: GtkAction
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.
GtkAction:visible-horizontal has been deprecated since version 3.10 and should not be used in newly-written code.
There is no corresponding replacement when using
GAction
Owner: GtkAction
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.
GtkAction:visible-overflown has been deprecated since version 3.10 and should not be used in newly-written code.
There is no corresponding replacement when using
GAction
Owner: GtkAction
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.
GtkAction:visible-vertical has been deprecated since version 3.10 and should not be used in newly-written code.
There is no corresponding replacement when using
GAction
Owner: GtkAction
Flags: Read / Write
Default value: TRUE