Commit 7fdf2e0b authored by Allison Karlitskaya's avatar Allison Karlitskaya

document GtkActionable

This should have been done before it was merged...
parent ba2d3d14
......@@ -339,6 +339,7 @@
<title>Application support</title>
<xi:include href="xml/gtkapplication.xml" />
<xi:include href="xml/gtkapplicationwindow.xml" />
<xi:include href="xml/gtkactionable.xml" />
</chapter>
</part>
......
......@@ -7057,6 +7057,32 @@ gtk_application_window_get_type
GtkApplicationWindowPrivate
</SECTION>
<SECTION>
<FILE>gtkactionable</FILE>
<TITLE>GtkActionable</TITLE>
GtkActionable
GtkActionableInterface
<SUBSECTION>
gtk_actionable_get_action_name
gtk_actionable_set_action_name
<SUBSECTION>
gtk_actionable_get_action_target_value
gtk_actionable_set_action_target_value
gtk_actionable_set_action_target
<SUBSECTION>
gtk_actionable_set_detailed_action_name
<SUBSECTION Standard>
gtk_actionable_get_type
GTK_ACTIONABLE
GTK_ACTIONABLE_GET_IFACE
GTK_IS_ACTIONABLE
GTK_TYPE_ACTIONABLE
</SECTION>
<SECTION>
<FILE>gtkgrid</FILE>
<TITLE>GtkGrid</TITLE>
......
......@@ -6,6 +6,7 @@ gtk_accel_group_get_type
gtk_accel_label_get_type
gtk_accel_map_get_type
gtk_accessible_get_type
gtk_actionable_get_type
gtk_action_get_type
gtk_action_group_get_type
gtk_activatable_get_type
......
......@@ -26,6 +26,43 @@
#include "gtkwidget.h"
#include "gtkintl.h"
/**
* SECTION:gtkactionable
* @title: GtkActionable
* @short_description: an interface for widgets that can be associated
* with actions
*
* This interface provides a convenient way of associating widgets with
* actions on a #GtkApplicationWindow or #GtkApplication.
*
* It primarily consists of two properties: "action-name" and
* "action-target". There are also some convenience APIs for setting
* these properties.
*
* This interface is presently only meaningful if used on a widget that
* is (or will be) located inside of a #GtkApplicationWindow and can
* only be used to associate the widget with actions on that window, or
* its associated #GtkApplication.
*
* Since: 3.4
**/
/**
* GtkActionable:
*
* An opaque pointer type.
**/
/**
* GtkActionableInterface:
* @get_action_name: virtual pointer for gtk_actionable_get_action_name
* @set_action_name: virtual pointer for gtk_actionable_set_action_name
* @get_action_target_value: virtual pointer for gtk_actionable_get_action_target_value
* @set_action_target_value: virtual pointer for gtk_actionable_set_action_target_value
*
* The interface vtable for #GtkActionable.
**/
G_DEFINE_INTERFACE (GtkActionable, gtk_actionable, GTK_TYPE_WIDGET)
static void
......@@ -42,6 +79,18 @@ gtk_actionable_default_init (GtkActionableInterface *iface)
G_VARIANT_TYPE_ANY, NULL, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
}
/**
* gtk_actionable_get_action_name:
* @actionable: a #GtkActionable widget
*
* Gets the action name for @actionable.
*
* See gtk_actionable_set_action_name() for more information.
*
* Returns: the action name, or %NULL if none is set
*
* Since: 3.4
**/
const gchar *
gtk_actionable_get_action_name (GtkActionable *actionable)
{
......@@ -51,6 +100,25 @@ gtk_actionable_get_action_name (GtkActionable *actionable)
->get_action_name (actionable);
}
/**
* gtk_actionable_set_action_name:
* @actionable: a #GtkActionable widget
* @action_name: an action name, or %NULL
*
* Specifies the name of the action with which this widget should be
* associated. If @action_name is %NULL then the widget will be
* unassociated from any previous action.
*
* Usually this function is used when the widget is located (or will be
* located) within the hierarchy of a #GtkApplicationWindow.
*
* Names are of the form "win.save" or "app.quit" for actions on the
* containing #GtkApplicationWindow or its associated #GtkApplication,
* respectively. This is the same form used for actions in the #GMenu
* associated with the window.
*
* Since: 3.4
**/
void
gtk_actionable_set_action_name (GtkActionable *actionable,
const gchar *action_name)
......@@ -61,6 +129,18 @@ gtk_actionable_set_action_name (GtkActionable *actionable,
->set_action_name (actionable, action_name);
}
/**
* gtk_actionable_get_action_target_value:
* @actionable: a #GtkActionable widget
*
* Gets the current target value of @actionabe.
*
* See gtk_actionable_set_target_value() for more information.
*
* Returns: (transfer none): the current target value
*
* Since: 3.4
**/
GVariant *
gtk_actionable_get_action_target_value (GtkActionable *actionable)
{
......@@ -70,6 +150,33 @@ gtk_actionable_get_action_target_value (GtkActionable *actionable)
->get_action_target_value (actionable);
}
/**
* gtk_actionable_set_action_target_value:
* @actionable: a #GtkActionable widget
* @target_value: a #GVariant to set as the target value, or %NULL
*
* Sets the target value of an actionable widget.
*
* If @target_value is %NULL then the target value is unset.
*
* The target value has two purposes. First, it is used as the
* parameter to activation of the action associated with the
* #GtkActionable widget. Second, it is used to determine if the widget
* should be rendered as "active" -- the widget is active if the state
* is equal to the given target.
*
* Consider the example of associating a set of buttons with a #GAction
* with string state in a typical "radio button" situation. Each button
* will be associated with the same action, but with a different target
* value for that action. Clicking on a particular button will activate
* the action with the target of that button, which will typically cause
* the action's state to change to that value. Since the action's state
* is now equal to the target value of the button, the button will now
* be rendered as active (and the other buttons, with different targets,
* rendered inactive).
*
* Since: 3.4
**/
void
gtk_actionable_set_action_target_value (GtkActionable *actionable,
GVariant *target_value)
......@@ -80,6 +187,24 @@ gtk_actionable_set_action_target_value (GtkActionable *actionable,
->set_action_target_value (actionable, target_value);
}
/**
* gtk_actionable_set_action_target:
* @actionable: a #GtkActionable widget
* @format_string: a GVariant format string
* @...: arguments appropriate for @format_string
*
* Sets the target of an actionable widget.
*
* This is a convenience function that calls g_variant_new() for
* @format_string and uses the result to call
* gtk_actionable_set_action_target_value().
*
* If you are setting a string-valued target and want to set the action
* name at the same time, you can use
* gtk_actionable_set_detailed_action_name ().
*
* Since: 3.4
**/
void
gtk_actionable_set_action_target (GtkActionable *actionable,
const gchar *format_string,
......@@ -92,6 +217,25 @@ gtk_actionable_set_action_target (GtkActionable *actionable,
va_end (ap);
}
/**
* gtk_actionable_set_detailed_action_name:
* @actionable: a #GtkActionable widget
* @detailed_action_name: the detailed action name
*
* Sets the action-name and associated string target value of an
* actionable widget.
*
* This allows for the effect of both gtk_actionable_set_action_name()
* and gtk_actionable_set_target() in the common case that the target is
* string-valued.
*
* @detailed_action_name is a string of the form
* <literal>"action::target"</literal> where <literal>action</literal>
* is the action name and <literal>target</literal> is the string to use
* as the target.
*
* Since: 3.4
**/
void
gtk_actionable_set_detailed_action_name (GtkActionable *actionable,
const gchar *detailed_action_name)
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment