![]() | ![]() | ![]() | GTK+ Reference Manual | ![]() |
---|
GtkAction — an action which can be triggered by a menu or toolbar item
#include <gtk/gtk.h> struct GtkAction; const gchar* gtk_action_get_name (GtkAction *action); 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); void gtk_action_set_accel_path (GtkAction *action, const gchar *accel_path); void gtk_action_set_accel_group (GtkAction *action, GtkAccelGroup *accel_group);
GObject +----GtkAction +----GtkToggleAction
"hide-if-empty" gboolean : 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
"activate" void user_function (GtkAction *action, gpointer user_data); "connect-proxy" void user_function (GtkAction *action, GtkWidget *proxy, gpointer user_data); "disconnect-proxy" void user_function (GtkAction *action, GtkWidget *proxy, gpointer user_data);
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.
struct GtkAction;
The GtkAction struct contains only private members and should not be accessed directly.
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
void gtk_action_activate (GtkAction *action);
Emits the "activate" signal on the specified action. 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
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
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
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
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
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
GSList* gtk_action_get_proxies (GtkAction *action);
Returns the proxy widgets for an action.
action : | the action object |
Returns : | a GSList of proxy widgets. The list is owned by the action and must not be modified. |
Since 2.4
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
void gtk_action_disconnect_accelerator (GtkAction *action);
Undoes the effect of one call to gtk_action_connect_accelerator().
action : | a GtkAction |
Since 2.4
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
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
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
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
"hide-if-empty" (gboolean : Read / Write) | When TRUE, empty menu proxies for this action are hidden. |
"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. |
"label" (gchararray : Read / Write) | The label used for menu items and buttons that activate this action. |
"name" (gchararray : Read / Write / Construct Only) | A unique name for the action. |
"sensitive" (gboolean : Read / Write) | Whether the action is enabled. |
"short-label" (gchararray : Read / Write) | A shorter label that may be used on toolbar buttons. |
"stock-id" (gchararray : Read / Write) | The stock icon displayed in widgets representing this action. |
"tooltip" (gchararray : Read / Write) | A tooltip for this action. |
"visible" (gboolean : Read / Write) | Whether the action is visible. |
void user_function (GtkAction *action, gpointer user_data);
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
void user_function (GtkAction *action, GtkWidget *proxy, gpointer user_data);
The connect_proxy signal is emitted after connecting a proxy to an action. Note that the proxy may have been connected to a different action before.
This is intended for simple customizations for which a custom action class would be too clumsy, e.g. showing tooltips for menuitems in the statusbar.
action : | the action |
proxy : | the proxy |
user_data : | user data set when the signal handler was connected. |
Since 2.4
void user_function (GtkAction *action, GtkWidget *proxy, gpointer user_data);
The disconnect_proxy signal is emitted after disconnecting a proxy from an action.
action : | the action |
proxy : | the proxy |
user_data : | user data set when the signal handler was connected. |
Since 2.4
<< GtkActionGroup | GtkToggleAction >> |