* GTK+ at ftp://ftp.gtk.org/pub/gtk/.
*/
+/**
+ * SECTION:gtkaction
+ * @Short_description: An action which can be triggered by a menu or toolbar item
+ * @Title: GtkAction
+ * @See_also: #GtkActionGroup, #GtkUIManager, #GtkActivatable
+ *
+ * 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:
+ * <itemizedlist>
+ * <listitem><para>a name (not translated, for path lookup)</para></listitem>
+ * <listitem><para>a label (translated, for display)</para></listitem>
+ * <listitem><para>an accelerator</para></listitem>
+ * <listitem><para>whether label indicates a stock id</para></listitem>
+ * <listitem><para>a tooltip (optional, translated)</para></listitem>
+ * <listitem><para>a toolbar label (optional, shorter than label)</para></listitem>
+ * </itemizedlist>
+ * The action will also have some state information:
+ * <itemizedlist>
+ * <listitem><para>visible (shown/hidden)</para></listitem>
+ * <listitem><para>sensitive (enabled/disabled)</para></listitem>
+ * </itemizedlist>
+ * Apart from regular actions, there are <link linkend="GtkToggleAction">toggle
+ * actions</link>, which can be toggled between two states and <link
+ * linkend="GtkRadioAction">radio actions</link>, 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 #GtkAction:sensitive and
+ * #GtkAction:visible. #GtkAction:gicon, #GtkAction:icon-name, #GtkAction:label,
+ * #GtkAction:short-label and #GtkAction:stock-id properties are only mirorred
+ * if proxy widget has #GtkActivatable:use-action-appearance property set to
+ * %TRUE.
+ *
+ * When the proxy is activated, it should activate its action.
+ */
+
#include "config.h"
#include "gtkaction.h"
#include "gtkprivate.h"
#include "gtkbuildable.h"
#include "gtkactivatable.h"
-#include "gtkalias.h"
-
-#define GTK_ACTION_GET_PRIVATE(obj) (G_TYPE_INSTANCE_GET_PRIVATE ((obj), GTK_TYPE_ACTION, GtkActionPrivate))
struct _GtkActionPrivate
{
static void
gtk_action_init (GtkAction *action)
{
- action->private_data = GTK_ACTION_GET_PRIVATE (action);
+ action->private_data = G_TYPE_INSTANCE_GET_PRIVATE (action,
+ GTK_TYPE_ACTION,
+ GtkActionPrivate);
action->private_data->name = NULL;
action->private_data->label = NULL;
/**
* gtk_action_new:
* @name: A unique name for the action
- * @label: the label displayed in menu items and on buttons, or %NULL
- * @tooltip: a tooltip for the action, or %NULL
+ * @label: (allow-none): the label displayed in menu items and on buttons, or %NULL
+ * @tooltip: (allow-none): a tooltip for the action, or %NULL
* @stock_id: the stock icon to display in widgets representing the
* action, or %NULL
*
/**
* _gtk_action_sync_menu_visible:
- * @action: a #GtkAction, or %NULL to determine the action from @proxy
+ * @action: (allow-none): a #GtkAction, or %NULL to determine the action from @proxy
* @proxy: a proxy menu item
* @empty: whether the submenu attached to @proxy is empty
*
/**
* gtk_action_create_icon:
* @action: the action object
- * @icon_size: the size of the icon that should be created.
+ * @icon_size: (type int): the size of the icon that should be created.
*
* This function is intended for use by action implementations to
* create icons displayed in the proxy widgets.
GTK_ACTION_GET_CLASS (action)->disconnect_proxy (action, proxy);
}
-/**
- * gtk_action_connect_proxy:
- * @action: the action object
- * @proxy: the proxy widget
- *
- * 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.
- *
- * Since: 2.4
- *
- * Deprecated: 2.16: Use gtk_activatable_set_related_action() instead.
- */
-void
-gtk_action_connect_proxy (GtkAction *action,
- GtkWidget *proxy)
-{
- g_return_if_fail (GTK_IS_ACTION (action));
- g_return_if_fail (GTK_IS_WIDGET (proxy));
- g_return_if_fail (GTK_IS_ACTIVATABLE (proxy));
-
- gtk_activatable_set_use_action_appearance (GTK_ACTIVATABLE (proxy), TRUE);
-
- gtk_activatable_set_related_action (GTK_ACTIVATABLE (proxy), action);
-}
-
-/**
- * gtk_action_disconnect_proxy:
- * @action: the action object
- * @proxy: the proxy widget
- *
- * Disconnects a proxy widget from an action.
- * Does <emphasis>not</emphasis> destroy the widget, however.
- *
- * Since: 2.4
- *
- * Deprecated: 2.16: Use gtk_activatable_set_related_action() instead.
- */
-void
-gtk_action_disconnect_proxy (GtkAction *action,
- GtkWidget *proxy)
-{
- g_return_if_fail (GTK_IS_ACTION (action));
- g_return_if_fail (GTK_IS_WIDGET (proxy));
-
- gtk_activatable_set_related_action (GTK_ACTIVATABLE (proxy), NULL);
-}
-
/**
* gtk_action_get_proxies:
* @action: the action object
*
* Returns the proxy widgets for an action.
- * See also gtk_widget_get_action().
+ * See also gtk_activatable_get_related_action().
*
* Return value: (element-type GtkWidget) (transfer none): a #GSList of proxy widgets. The list is owned by GTK+
* and must not be modified.
return action->private_data->proxies;
}
-
-/**
- * gtk_widget_get_action:
- * @widget: a #GtkWidget
- *
- * Returns the #GtkAction that @widget is a proxy for.
- * See also gtk_action_get_proxies().
- *
- * Returns: the action that a widget is a proxy for, or
- * %NULL, if it is not attached to an action.
- *
- * Since: 2.10
- *
- * Deprecated: 2.16: Use gtk_activatable_get_related_action() instead.
- */
-GtkAction*
-gtk_widget_get_action (GtkWidget *widget)
-{
- g_return_val_if_fail (GTK_IS_WIDGET (widget), NULL);
-
- if (GTK_IS_ACTIVATABLE (widget))
- return gtk_activatable_get_related_action (GTK_ACTIVATABLE (widget));
-
- return NULL;
-}
-
/**
* gtk_action_get_name:
* @action: the action object
return action->private_data->gicon;
}
-/**
- * gtk_action_block_activate_from:
- * @action: the action object
- * @proxy: a proxy widget
- *
- * 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.
- *
- * Since: 2.4
- *
- * Deprecated: 2.16: activatables are now responsible for activating the
- * action directly so this doesnt apply anymore.
- */
-void
-gtk_action_block_activate_from (GtkAction *action,
- GtkWidget *proxy)
-{
- g_return_if_fail (GTK_IS_ACTION (action));
-
- g_signal_handlers_block_by_func (proxy, G_CALLBACK (gtk_action_activate),
- action);
-
- gtk_action_block_activate (action);
-}
-
-/**
- * gtk_action_unblock_activate_from:
- * @action: the action object
- * @proxy: a proxy widget
- *
- * 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.
- *
- * Since: 2.4
- *
- * Deprecated: 2.16: activatables are now responsible for activating the
- * action directly so this doesnt apply anymore.
- */
-void
-gtk_action_unblock_activate_from (GtkAction *action,
- GtkWidget *proxy)
-{
- g_return_if_fail (GTK_IS_ACTION (action));
-
- g_signal_handlers_unblock_by_func (proxy, G_CALLBACK (gtk_action_activate),
- action);
-
- gtk_action_unblock_activate (action);
-}
-
static void
closure_accel_activate (GClosure *closure,
GValue *return_value,
return NULL;
}
-
-#define __GTK_ACTION_C__
-#include "gtkaliasdef.c"
projects / ~andy / gtk / blobdiff