2012-01-06 03:22:06 +00:00
|
|
|
|
/*
|
|
|
|
|
* Copyright © 2012 Canonical Limited
|
|
|
|
|
*
|
2012-02-27 13:01:10 +00:00
|
|
|
|
* This library is free software: you can redistribute it and/or modify
|
2012-01-06 03:22:06 +00:00
|
|
|
|
* it under the terms of the GNU Lesser General Public License as
|
|
|
|
|
* published by the Free Software Foundation; either version 2 of the
|
|
|
|
|
* licence or (at your option) any later version.
|
|
|
|
|
*
|
|
|
|
|
* This library is distributed in the hope that it will be useful, but
|
|
|
|
|
* WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
|
|
|
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
|
|
|
|
* Lesser General Public License for more details.
|
|
|
|
|
*
|
|
|
|
|
* You should have received a copy of the GNU Lesser General Public
|
2012-02-27 13:01:10 +00:00
|
|
|
|
* License along with this library. If not, see <http://www.gnu.org/licenses/>.
|
2012-01-06 03:22:06 +00:00
|
|
|
|
*
|
|
|
|
|
* Authors: Ryan Lortie <desrt@desrt.ca>
|
|
|
|
|
*/
|
|
|
|
|
|
|
|
|
|
#include "config.h"
|
|
|
|
|
|
|
|
|
|
#include "gtkactionable.h"
|
|
|
|
|
|
|
|
|
|
#include "gtkwidget.h"
|
|
|
|
|
#include "gtkintl.h"
|
|
|
|
|
|
2012-01-11 11:56:35 +00:00
|
|
|
|
/**
|
|
|
|
|
* SECTION:gtkactionable
|
|
|
|
|
* @title: GtkActionable
|
2012-01-25 03:41:36 +00:00
|
|
|
|
* @short_description: An interface for widgets that can be associated
|
|
|
|
|
* with actions
|
2012-01-11 11:56:35 +00:00
|
|
|
|
*
|
|
|
|
|
* This interface provides a convenient way of associating widgets with
|
|
|
|
|
* actions on a #GtkApplicationWindow or #GtkApplication.
|
|
|
|
|
*
|
2012-01-25 03:41:36 +00:00
|
|
|
|
* It primarily consists of two properties: #GtkActionable:action-name
|
|
|
|
|
* and #GtkActionable:action-target. There are also some convenience APIs
|
|
|
|
|
* for setting these properties.
|
2012-01-11 11:56:35 +00:00
|
|
|
|
*
|
2014-05-30 11:05:50 +00:00
|
|
|
|
* The action will be looked up in action groups that are found among
|
|
|
|
|
* the widgets ancestors. Most commonly, these will be the actions with
|
2015-04-21 12:07:51 +00:00
|
|
|
|
* the “win.” or “app.” prefix that are associated with the #GtkApplicationWindow
|
2016-04-08 18:13:07 +00:00
|
|
|
|
* or #GtkApplication, but other action groups that are added with
|
2014-05-30 11:05:50 +00:00
|
|
|
|
* gtk_widget_insert_action_group() will be consulted as well.
|
2012-01-11 11:56:35 +00:00
|
|
|
|
**/
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* GtkActionable:
|
|
|
|
|
*
|
|
|
|
|
* An opaque pointer type.
|
|
|
|
|
**/
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* GtkActionableInterface:
|
2015-04-21 12:07:51 +00:00
|
|
|
|
* @get_action_name: virtual function for gtk_actionable_get_action_name()
|
|
|
|
|
* @set_action_name: virtual function for gtk_actionable_set_action_name()
|
|
|
|
|
* @get_action_target_value: virtual function for gtk_actionable_get_action_target_value()
|
|
|
|
|
* @set_action_target_value: virtual function for gtk_actionable_set_action_target_value()
|
2012-01-11 11:56:35 +00:00
|
|
|
|
*
|
|
|
|
|
* The interface vtable for #GtkActionable.
|
|
|
|
|
**/
|
|
|
|
|
|
2012-01-06 03:22:06 +00:00
|
|
|
|
G_DEFINE_INTERFACE (GtkActionable, gtk_actionable, GTK_TYPE_WIDGET)
|
|
|
|
|
|
|
|
|
|
static void
|
|
|
|
|
gtk_actionable_default_init (GtkActionableInterface *iface)
|
|
|
|
|
{
|
|
|
|
|
g_object_interface_install_property (iface,
|
2016-03-10 02:13:44 +00:00
|
|
|
|
g_param_spec_string ("action-name", P_("Action name"),
|
2016-10-03 16:20:03 +00:00
|
|
|
|
P_("The name of the associated action, like “app.quit”"),
|
2012-01-06 03:22:06 +00:00
|
|
|
|
NULL, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
|
|
|
|
|
|
|
|
|
|
g_object_interface_install_property (iface,
|
2016-03-10 02:13:44 +00:00
|
|
|
|
g_param_spec_variant ("action-target", P_("Action target value"),
|
2012-01-06 03:22:06 +00:00
|
|
|
|
P_("The parameter for action invocations"),
|
|
|
|
|
G_VARIANT_TYPE_ANY, NULL, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
|
|
|
|
|
}
|
|
|
|
|
|
2012-01-11 11:56:35 +00:00
|
|
|
|
/**
|
|
|
|
|
* gtk_actionable_get_action_name:
|
|
|
|
|
* @actionable: a #GtkActionable widget
|
|
|
|
|
*
|
|
|
|
|
* Gets the action name for @actionable.
|
|
|
|
|
*
|
|
|
|
|
* See gtk_actionable_set_action_name() for more information.
|
|
|
|
|
*
|
2015-12-28 20:14:08 +00:00
|
|
|
|
* Returns: (nullable): the action name, or %NULL if none is set
|
2012-01-11 11:56:35 +00:00
|
|
|
|
**/
|
2020-07-24 18:40:36 +00:00
|
|
|
|
const char *
|
2012-01-06 03:22:06 +00:00
|
|
|
|
gtk_actionable_get_action_name (GtkActionable *actionable)
|
|
|
|
|
{
|
|
|
|
|
g_return_val_if_fail (GTK_IS_ACTIONABLE (actionable), NULL);
|
|
|
|
|
|
|
|
|
|
return GTK_ACTIONABLE_GET_IFACE (actionable)
|
|
|
|
|
->get_action_name (actionable);
|
|
|
|
|
}
|
|
|
|
|
|
2012-01-11 11:56:35 +00:00
|
|
|
|
/**
|
|
|
|
|
* gtk_actionable_set_action_name:
|
|
|
|
|
* @actionable: a #GtkActionable widget
|
2016-09-22 11:56:47 +00:00
|
|
|
|
* @action_name: (nullable): an action name, or %NULL
|
2012-01-11 11:56:35 +00:00
|
|
|
|
*
|
|
|
|
|
* 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.
|
|
|
|
|
*
|
2014-02-05 18:07:34 +00:00
|
|
|
|
* Names are of the form “win.save” or “app.quit” for actions on the
|
2012-01-11 11:56:35 +00:00
|
|
|
|
* containing #GtkApplicationWindow or its associated #GtkApplication,
|
|
|
|
|
* respectively. This is the same form used for actions in the #GMenu
|
|
|
|
|
* associated with the window.
|
|
|
|
|
**/
|
2012-01-06 03:22:06 +00:00
|
|
|
|
void
|
|
|
|
|
gtk_actionable_set_action_name (GtkActionable *actionable,
|
2020-07-24 18:40:36 +00:00
|
|
|
|
const char *action_name)
|
2012-01-06 03:22:06 +00:00
|
|
|
|
{
|
|
|
|
|
g_return_if_fail (GTK_IS_ACTIONABLE (actionable));
|
|
|
|
|
|
|
|
|
|
GTK_ACTIONABLE_GET_IFACE (actionable)
|
|
|
|
|
->set_action_name (actionable, action_name);
|
|
|
|
|
}
|
|
|
|
|
|
2012-01-11 11:56:35 +00:00
|
|
|
|
/**
|
|
|
|
|
* gtk_actionable_get_action_target_value:
|
|
|
|
|
* @actionable: a #GtkActionable widget
|
|
|
|
|
*
|
2016-07-28 09:12:54 +00:00
|
|
|
|
* Gets the current target value of @actionable.
|
2012-01-11 11:56:35 +00:00
|
|
|
|
*
|
2012-07-02 06:19:06 +00:00
|
|
|
|
* See gtk_actionable_set_action_target_value() for more information.
|
2012-01-11 11:56:35 +00:00
|
|
|
|
*
|
2020-11-21 15:33:40 +00:00
|
|
|
|
* Returns: (nullable) (transfer none): the current target value
|
2012-01-11 11:56:35 +00:00
|
|
|
|
**/
|
2012-01-06 03:22:06 +00:00
|
|
|
|
GVariant *
|
|
|
|
|
gtk_actionable_get_action_target_value (GtkActionable *actionable)
|
|
|
|
|
{
|
|
|
|
|
g_return_val_if_fail (GTK_IS_ACTIONABLE (actionable), NULL);
|
|
|
|
|
|
|
|
|
|
return GTK_ACTIONABLE_GET_IFACE (actionable)
|
|
|
|
|
->get_action_target_value (actionable);
|
|
|
|
|
}
|
|
|
|
|
|
2012-01-11 11:56:35 +00:00
|
|
|
|
/**
|
|
|
|
|
* gtk_actionable_set_action_target_value:
|
|
|
|
|
* @actionable: a #GtkActionable widget
|
2018-11-18 12:36:50 +00:00
|
|
|
|
* @target_value: (nullable): a #GVariant to set as the target value, or %NULL
|
2012-01-11 11:56:35 +00:00
|
|
|
|
*
|
|
|
|
|
* 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
|
2012-01-25 03:41:36 +00:00
|
|
|
|
* #GtkActionable widget. Second, it is used to determine if the widget
|
2015-04-21 12:07:51 +00:00
|
|
|
|
* should be rendered as “active” — the widget is active if the state
|
2012-01-11 11:56:35 +00:00
|
|
|
|
* is equal to the given target.
|
|
|
|
|
*
|
|
|
|
|
* Consider the example of associating a set of buttons with a #GAction
|
2014-02-05 18:07:34 +00:00
|
|
|
|
* with string state in a typical “radio button” situation. Each button
|
2012-01-11 11:56:35 +00:00
|
|
|
|
* 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
|
2018-02-05 19:13:20 +00:00
|
|
|
|
* the action’s state to change to that value. Since the action’s state
|
2012-01-11 11:56:35 +00:00
|
|
|
|
* 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).
|
|
|
|
|
**/
|
2012-01-06 03:22:06 +00:00
|
|
|
|
void
|
|
|
|
|
gtk_actionable_set_action_target_value (GtkActionable *actionable,
|
|
|
|
|
GVariant *target_value)
|
|
|
|
|
{
|
|
|
|
|
g_return_if_fail (GTK_IS_ACTIONABLE (actionable));
|
|
|
|
|
|
|
|
|
|
GTK_ACTIONABLE_GET_IFACE (actionable)
|
|
|
|
|
->set_action_target_value (actionable, target_value);
|
|
|
|
|
}
|
|
|
|
|
|
2012-01-11 11:56:35 +00:00
|
|
|
|
/**
|
|
|
|
|
* 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 ().
|
|
|
|
|
**/
|
2012-01-06 03:22:06 +00:00
|
|
|
|
void
|
|
|
|
|
gtk_actionable_set_action_target (GtkActionable *actionable,
|
2020-07-24 18:40:36 +00:00
|
|
|
|
const char *format_string,
|
2012-01-06 03:22:06 +00:00
|
|
|
|
...)
|
|
|
|
|
{
|
|
|
|
|
va_list ap;
|
|
|
|
|
|
|
|
|
|
va_start (ap, format_string);
|
|
|
|
|
gtk_actionable_set_action_target_value (actionable, g_variant_new_va (format_string, NULL, &ap));
|
|
|
|
|
va_end (ap);
|
|
|
|
|
}
|
|
|
|
|
|
2012-01-11 11:56:35 +00:00
|
|
|
|
/**
|
|
|
|
|
* 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.
|
|
|
|
|
*
|
2017-10-11 18:43:19 +00:00
|
|
|
|
* @detailed_action_name is a string in the format accepted by
|
|
|
|
|
* g_action_parse_detailed_name().
|
2012-01-11 11:56:35 +00:00
|
|
|
|
*
|
2017-10-11 18:43:19 +00:00
|
|
|
|
* (Note that prior to version 3.22.25,
|
|
|
|
|
* this function is only usable for actions with a simple "s" target, and
|
|
|
|
|
* @detailed_action_name must be of the form `"action::target"` where
|
|
|
|
|
* `action` is the action name and `target` is the string to use
|
|
|
|
|
* as the target.)
|
2012-01-11 11:56:35 +00:00
|
|
|
|
**/
|
2012-01-06 03:22:06 +00:00
|
|
|
|
void
|
|
|
|
|
gtk_actionable_set_detailed_action_name (GtkActionable *actionable,
|
2020-07-24 18:40:36 +00:00
|
|
|
|
const char *detailed_action_name)
|
2012-01-06 03:22:06 +00:00
|
|
|
|
{
|
2017-10-11 18:43:19 +00:00
|
|
|
|
GError *error = NULL;
|
|
|
|
|
GVariant *target;
|
2020-07-24 18:40:36 +00:00
|
|
|
|
char *name;
|
2012-01-06 03:22:06 +00:00
|
|
|
|
|
|
|
|
|
if (detailed_action_name == NULL)
|
|
|
|
|
{
|
|
|
|
|
gtk_actionable_set_action_name (actionable, NULL);
|
|
|
|
|
gtk_actionable_set_action_target_value (actionable, NULL);
|
|
|
|
|
return;
|
|
|
|
|
}
|
|
|
|
|
|
2017-10-11 18:43:19 +00:00
|
|
|
|
if (!g_action_parse_detailed_name (detailed_action_name, &name, &target, &error))
|
|
|
|
|
g_error ("gtk_actionable_set_detailed_action_name: %s", error->message);
|
|
|
|
|
|
|
|
|
|
gtk_actionable_set_action_name (actionable, name);
|
|
|
|
|
gtk_actionable_set_action_target_value (actionable, target);
|
|
|
|
|
|
|
|
|
|
if (target)
|
|
|
|
|
g_variant_unref (target);
|
|
|
|
|
g_free (name);
|
2012-01-06 03:22:06 +00:00
|
|
|
|
}
|
2015-12-28 20:14:08 +00:00
|
|
|
|
|