![]() |
![]() |
![]() |
GTK+ 3 Reference Manual | ![]() |
---|---|---|---|---|
Top | Description | Object Hierarchy | Implemented Interfaces | Properties | Signals |
#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
);
"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
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.
GtkAction * gtk_action_new (const gchar *name
,const gchar *label
,const gchar *tooltip
,const gchar *stock_id
);
gtk_action_new
is deprecated and should not be used in newly-written code. 3.10
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.
|
A unique name for the action |
|
the label displayed in menu items and on buttons,
or NULL . [allow-none]
|
|
a tooltip for the action, or NULL . [allow-none]
|
|
the stock icon to display in widgets representing
the action, or NULL . [allow-none]
|
Returns : |
a new GtkAction |
Since 2.4
const gchar * gtk_action_get_name (GtkAction *action
);
gtk_action_get_name
is deprecated and should not be used in newly-written code. 3.10
Returns the name of the action.
|
the action object |
Returns : |
the name of the action. The string belongs to GTK+ and should not be freed. |
Since 2.4
gboolean gtk_action_is_sensitive (GtkAction *action
);
gtk_action_is_sensitive
is deprecated and should not be used in newly-written code. 3.10
Returns whether the action is effectively sensitive.
|
the action object |
Returns : |
TRUE if the action and its associated action group
are both sensitive. |
Since 2.4
gboolean gtk_action_get_sensitive (GtkAction *action
);
gtk_action_get_sensitive
is deprecated and should not be used in newly-written code. 3.10
Returns whether the action itself is sensitive. Note that this doesn't
necessarily mean effective sensitivity. See gtk_action_is_sensitive()
for that.
|
the action object |
Returns : |
TRUE if the action itself is sensitive. |
Since 2.4
void gtk_action_set_sensitive (GtkAction *action
,gboolean sensitive
);
gtk_action_set_sensitive
is deprecated and should not be used in newly-written code. 3.10
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.
|
the action object |
|
TRUE to make the action sensitive |
Since 2.6
gboolean gtk_action_is_visible (GtkAction *action
);
gtk_action_is_visible
is deprecated and should not be used in newly-written code. 3.10
Returns whether the action is effectively visible.
|
the action object |
Returns : |
TRUE if the action and its associated action group
are both visible. |
Since 2.4
gboolean gtk_action_get_visible (GtkAction *action
);
gtk_action_get_visible
is deprecated and should not be used in newly-written code. 3.10
Returns whether the action itself is visible. Note that this doesn't
necessarily mean effective visibility. See gtk_action_is_sensitive()
for that.
|
the action object |
Returns : |
TRUE if the action itself is visible. |
Since 2.4
void gtk_action_set_visible (GtkAction *action
,gboolean visible
);
gtk_action_set_visible
is deprecated and should not be used in newly-written code. 3.10
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.
|
the action object |
|
TRUE to make the action visible |
Since 2.6
void gtk_action_activate (GtkAction *action
);
gtk_action_activate
is deprecated and should not be used in newly-written code. 3.10
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.
|
the action object |
Since 2.4
GtkWidget * gtk_action_create_icon (GtkAction *action
,GtkIconSize icon_size
);
gtk_action_create_icon
is deprecated and should not be used in newly-written code. 3.10
This function is intended for use by action implementations to create icons displayed in the proxy widgets.
|
the action object |
|
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
GtkWidget * gtk_action_create_menu_item (GtkAction *action
);
gtk_action_create_menu_item
is deprecated and should not be used in newly-written code. 3.10
Creates a menu item widget that proxies for the given action.
|
the action object |
Returns : |
a menu item connected to the action. [transfer none] |
Since 2.4
GtkWidget * gtk_action_create_tool_item (GtkAction *action
);
gtk_action_create_tool_item
is deprecated and should not be used in newly-written code. 3.10
Creates a toolbar item widget that proxies for the given action.
|
the action object |
Returns : |
a toolbar item connected to the action. [transfer none] |
Since 2.4
GtkWidget * gtk_action_create_menu (GtkAction *action
);
gtk_action_create_menu
is deprecated and should not be used in newly-written code. 3.10
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.
Since 2.12
GSList * gtk_action_get_proxies (GtkAction *action
);
gtk_action_get_proxies
is deprecated and should not be used in newly-written code. 3.10
Returns the proxy widgets for an action.
See also gtk_activatable_get_related_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
void gtk_action_connect_accelerator (GtkAction *action
);
gtk_action_connect_accelerator
is deprecated and should not be used in newly-written code. 3.10
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.
|
a GtkAction |
Since 2.4
void gtk_action_disconnect_accelerator (GtkAction *action
);
gtk_action_disconnect_accelerator
is deprecated and should not be used in newly-written code. 3.10
Undoes the effect of one call to gtk_action_connect_accelerator()
.
|
a GtkAction |
Since 2.4
void gtk_action_block_activate (GtkAction *action
);
gtk_action_block_activate
is deprecated and should not be used in newly-written code. 3.10
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).
|
a GtkAction |
Since 2.16
void gtk_action_unblock_activate (GtkAction *action
);
gtk_action_unblock_activate
is deprecated and should not be used in newly-written code. 3.10
Reenable activation signals from the action
|
a GtkAction |
Since 2.16
gboolean gtk_action_get_always_show_image (GtkAction *action
);
gtk_action_get_always_show_image
is deprecated and should not be used in newly-written code. 3.10
Returns whether action
's menu item proxies will always
show their image, if available.
Since 2.20
void gtk_action_set_always_show_image (GtkAction *action
,gboolean always_show
);
gtk_action_set_always_show_image
is deprecated and should not be used in newly-written code. 3.10
Sets whether action
's menu item proxies will 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
const gchar * gtk_action_get_accel_path (GtkAction *action
);
gtk_action_get_accel_path
is deprecated and should not be used in newly-written code. 3.10
Returns the accel path for this 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
void gtk_action_set_accel_path (GtkAction *action
,const gchar *accel_path
);
gtk_action_set_accel_path
is deprecated and should not be used in newly-written code. 3.10
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()
.
|
the action object |
|
the accelerator path |
Since 2.4
GClosure * gtk_action_get_accel_closure (GtkAction *action
);
gtk_action_get_accel_closure
is deprecated and should not be used in newly-written code. 3.10
Returns the accel closure for this 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
void gtk_action_set_accel_group (GtkAction *action
,GtkAccelGroup *accel_group
);
gtk_action_set_accel_group
is deprecated and should not be used in newly-written code. 3.10
Sets the GtkAccelGroup in which the accelerator for this action will be installed.
|
the action object |
|
a GtkAccelGroup or NULL . [allow-none]
|
Since 2.4
void gtk_action_set_label (GtkAction *action
,const gchar *label
);
gtk_action_set_label
is deprecated and should not be used in newly-written code. 3.10
Sets the label of action
.
|
a GtkAction |
|
the label text to set |
Since 2.16
const gchar * gtk_action_get_label (GtkAction *action
);
gtk_action_get_label
is deprecated and should not be used in newly-written code. 3.10
Gets the label text of action
.
|
a GtkAction |
Returns : |
the label text |
Since 2.16
void gtk_action_set_short_label (GtkAction *action
,const gchar *short_label
);
gtk_action_set_short_label
is deprecated and should not be used in newly-written code. 3.10
Sets a shorter label text on action
.
|
a GtkAction |
|
the label text to set |
Since 2.16
const gchar * gtk_action_get_short_label (GtkAction *action
);
gtk_action_get_short_label
is deprecated and should not be used in newly-written code. 3.10
Gets the short label text of action
.
|
a GtkAction |
Returns : |
the short label text. |
Since 2.16
void gtk_action_set_tooltip (GtkAction *action
,const gchar *tooltip
);
gtk_action_set_tooltip
is deprecated and should not be used in newly-written code. 3.10
Sets the tooltip text on action
|
a GtkAction |
|
the tooltip text |
Since 2.16
const gchar * gtk_action_get_tooltip (GtkAction *action
);
gtk_action_get_tooltip
is deprecated and should not be used in newly-written code. 3.10
Gets the tooltip text of action
.
|
a GtkAction |
Returns : |
the tooltip text |
Since 2.16
void gtk_action_set_stock_id (GtkAction *action
,const gchar *stock_id
);
gtk_action_set_stock_id
is deprecated and should not be used in newly-written code. 3.10
Sets the stock id on action
|
a GtkAction |
|
the stock id |
Since 2.16
const gchar * gtk_action_get_stock_id (GtkAction *action
);
gtk_action_get_stock_id
is deprecated and should not be used in newly-written code. 3.10
Gets the stock id of action
.
|
a GtkAction |
Returns : |
the stock id |
Since 2.16
void gtk_action_set_gicon (GtkAction *action
,GIcon *icon
);
gtk_action_set_gicon
is deprecated and should not be used in newly-written code. 3.10
Sets the icon of action
.
Since 2.16
GIcon * gtk_action_get_gicon (GtkAction *action
);
gtk_action_get_gicon
is deprecated and should not be used in newly-written code. 3.10
Gets the gicon of action
.
Since 2.16
void gtk_action_set_icon_name (GtkAction *action
,const gchar *icon_name
);
gtk_action_set_icon_name
is deprecated and should not be used in newly-written code. 3.10
Sets the icon name on action
|
a GtkAction |
|
the icon name to set |
Since 2.16
const gchar * gtk_action_get_icon_name (GtkAction *action
);
gtk_action_get_icon_name
is deprecated and should not be used in newly-written code. 3.10
Gets the icon name of action
.
|
a GtkAction |
Returns : |
the icon name |
Since 2.16
void gtk_action_set_visible_horizontal (GtkAction *action
,gboolean visible_horizontal
);
gtk_action_set_visible_horizontal
is deprecated and should not be used in newly-written code. 3.10
Sets whether action
is visible when horizontal
|
a GtkAction |
|
whether the action is visible horizontally |
Since 2.16
gboolean gtk_action_get_visible_horizontal (GtkAction *action
);
gtk_action_get_visible_horizontal
is deprecated and should not be used in newly-written code. 3.10
Checks whether action
is visible when horizontal
|
a GtkAction |
Returns : |
whether action is visible when horizontal |
Since 2.16
void gtk_action_set_visible_vertical (GtkAction *action
,gboolean visible_vertical
);
gtk_action_set_visible_vertical
is deprecated and should not be used in newly-written code. 3.10
Sets whether action
is visible when vertical
|
a GtkAction |
|
whether the action is visible vertically |
Since 2.16
gboolean gtk_action_get_visible_vertical (GtkAction *action
);
gtk_action_get_visible_vertical
is deprecated and should not be used in newly-written code. 3.10
Checks whether action
is visible when horizontal
|
a GtkAction |
Returns : |
whether action is visible when horizontal |
Since 2.16
void gtk_action_set_is_important (GtkAction *action
,gboolean is_important
);
gtk_action_set_is_important
is deprecated and should not be used in newly-written code. 3.10
Sets whether the action is important, this attribute is used primarily by toolbar items to decide whether to show a label or not.
|
the action object |
|
TRUE to make the action important |
Since 2.16
gboolean gtk_action_get_is_important (GtkAction *action
);
gtk_action_get_is_important
is deprecated and should not be used in newly-written code. 3.10
Checks whether action
is important or not
|
a GtkAction |
Returns : |
whether action is important |
Since 2.16
"action-group"
property"action-group" GtkActionGroup* : Read / Write
GtkAction:action-group
is deprecated and should not be used in newly-written code. 3.10
The GtkActionGroup this GtkAction is associated with, or NULL (for internal use).
"always-show-image"
property"always-show-image" gboolean : Read / Write / Construct
GtkAction:always-show-image
is deprecated and should not be used in newly-written code. 3.10
If TRUE
, the action's menu item proxies will 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
"gicon"
property"gicon" GIcon* : Read / Write
GtkAction:gicon
is deprecated and should not be used in newly-written code. 3.10
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
"hide-if-empty"
property"hide-if-empty" gboolean : Read / Write
GtkAction:hide-if-empty
is deprecated and should not be used in newly-written code. 3.10
When TRUE, empty menu proxies for this action are hidden.
Default value: TRUE
"icon-name"
property"icon-name" gchar* : Read / Write
GtkAction:icon-name
is deprecated and should not be used in newly-written code. 3.10
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
"is-important"
property"is-important" gboolean : Read / Write
GtkAction:is-important
is deprecated and should not be used in newly-written code. 3.10
Whether the action is considered important. When TRUE, toolitem proxies for this action show text in GTK_TOOLBAR_BOTH_HORIZ mode.
Default value: FALSE
"label"
property"label" gchar* : Read / Write
GtkAction:label
is deprecated and should not be used in newly-written code. 3.10
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
"name"
property"name" gchar* : Read / Write / Construct Only
GtkAction:name
is deprecated and should not be used in newly-written code. 3.10
A unique name for the action.
Default value: NULL
"sensitive"
property"sensitive" gboolean : Read / Write
GtkAction:sensitive
is deprecated and should not be used in newly-written code. 3.10
Whether the action is enabled.
Default value: TRUE
"short-label"
property"short-label" gchar* : Read / Write
GtkAction:short-label
is deprecated and should not be used in newly-written code. 3.10
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
"stock-id"
property"stock-id" gchar* : Read / Write
GtkAction:stock-id
is deprecated and should not be used in newly-written code. 3.10
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
"tooltip"
property"tooltip" gchar* : Read / Write
GtkAction:tooltip
is deprecated and should not be used in newly-written code. 3.10
A tooltip for this action.
Default value: NULL
"visible"
property"visible" gboolean : Read / Write
GtkAction:visible
is deprecated and should not be used in newly-written code. 3.10
Whether the action is visible.
Default value: TRUE
"visible-horizontal"
property"visible-horizontal" gboolean : Read / Write
GtkAction:visible-horizontal
is deprecated and should not be used in newly-written code. 3.10
Whether the toolbar item is visible when the toolbar is in a horizontal orientation.
Default value: TRUE
"visible-overflown"
property"visible-overflown" gboolean : Read / Write
GtkAction:visible-overflown
is deprecated and should not be used in newly-written code. 3.10
When TRUE
, toolitem proxies for this action are represented in the
toolbar overflow menu.
Default value: TRUE
Since 2.6
"visible-vertical"
property"visible-vertical" gboolean : Read / Write
GtkAction:visible-vertical
is deprecated and should not be used in newly-written code. 3.10
Whether the toolbar item is visible when the toolbar is in a vertical orientation.
Default value: TRUE
"activate"
signalvoid user_function (GtkAction *action,
gpointer user_data) : No Recursion
GtkAction::activate
is deprecated and should not be used in newly-written code. 3.10
The "activate" signal is emitted when the action is activated.
|
the GtkAction |
|
user data set when the signal handler was connected. |
Since 2.4