Pileus Git - ~andy/gtk/blob - gtk/gtkactionable.c

   1 /*
   2  * Copyright © 2012 Canonical Limited
   3  *
   4  * This program is free software: you can redistribute it and/or modify
   5  * it under the terms of the GNU Lesser General Public License as
   6  * published by the Free Software Foundation; either version 2 of the
   7  * licence or (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful, but
  10  * WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * Lesser General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Lesser General Public
  15  * License along with this library; if not, write to the Free Software
  16  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307,
  17  * USA.
  18  *
  19  * Authors: Ryan Lortie <desrt@desrt.ca>
  20  */
  21
  22 #include "config.h"
  23
  24 #include "gtkactionable.h"
  25
  26 #include "gtkwidget.h"
  27 #include "gtkintl.h"
  28
  29 /**
  30  * SECTION:gtkactionable
  31  * @title: GtkActionable
  32  * @short_description: An interface for widgets that can be associated
  33  *     with actions
  34  *
  35  * This interface provides a convenient way of associating widgets with
  36  * actions on a #GtkApplicationWindow or #GtkApplication.
  37  *
  38  * It primarily consists of two properties: #GtkActionable:action-name
  39  * and #GtkActionable:action-target. There are also some convenience APIs
  40  * for setting these properties.
  41  *
  42  * This interface is presently only meaningful if used on a widget that
  43  * is (or will be) located inside of a #GtkApplicationWindow and can
  44  * only be used to associate the widget with actions on that window, or
  45  * its associated #GtkApplication.
  46  *
  47  * Since: 3.4
  48  **/
  49
  50 /**
  51  * GtkActionable:
  52  *
  53  * An opaque pointer type.
  54  **/
  55
  56 /**
  57  * GtkActionableInterface:
  58  * @get_action_name: virtual pointer for gtk_actionable_get_action_name()
  59  * @set_action_name: virtual pointer for gtk_actionable_set_action_name()
  60  * @get_action_target_value: virtual pointer for gtk_actionable_get_action_target_value()
  61  * @set_action_target_value: virtual pointer for gtk_actionable_set_action_target_value
  62  *
  63  * The interface vtable for #GtkActionable.
  64  **/
  65
  66 G_DEFINE_INTERFACE (GtkActionable, gtk_actionable, GTK_TYPE_WIDGET)
  67
  68 static void
  69 gtk_actionable_default_init (GtkActionableInterface *iface)
  70 {
  71   g_object_interface_install_property (iface,
  72     g_param_spec_string ("action-name", P_("action name"),
  73                          P_("The name of the associated action, like 'app.quit'"),
  74                          NULL, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
  75
  76   g_object_interface_install_property (iface,
  77     g_param_spec_variant ("action-target", P_("action target value"),
  78                           P_("The parameter for action invocations"),
  79                           G_VARIANT_TYPE_ANY, NULL, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
  80 }
  81
  82 /**
  83  * gtk_actionable_get_action_name:
  84  * @actionable: a #GtkActionable widget
  85  *
  86  * Gets the action name for @actionable.
  87  *
  88  * See gtk_actionable_set_action_name() for more information.
  89  *
  90  * Returns: the action name, or %NULL if none is set
  91  *
  92  * Since: 3.4
  93  **/
  94 const gchar *
  95 gtk_actionable_get_action_name (GtkActionable *actionable)
  96 {
  97   g_return_val_if_fail (GTK_IS_ACTIONABLE (actionable), NULL);
  98
  99   return GTK_ACTIONABLE_GET_IFACE (actionable)
 100     ->get_action_name (actionable);
 101 }
 102
 103 /**
 104  * gtk_actionable_set_action_name:
 105  * @actionable: a #GtkActionable widget
 106  * @action_name: an action name, or %NULL
 107  *
 108  * Specifies the name of the action with which this widget should be
 109  * associated.  If @action_name is %NULL then the widget will be
 110  * unassociated from any previous action.
 111  *
 112  * Usually this function is used when the widget is located (or will be
 113  * located) within the hierarchy of a #GtkApplicationWindow.
 114  *
 115  * Names are of the form "win.save" or "app.quit" for actions on the
 116  * containing #GtkApplicationWindow or its associated #GtkApplication,
 117  * respectively.  This is the same form used for actions in the #GMenu
 118  * associated with the window.
 119  *
 120  * Since: 3.4
 121  **/
 122 void
 123 gtk_actionable_set_action_name (GtkActionable *actionable,
 124                                 const gchar   *action_name)
 125 {
 126   g_return_if_fail (GTK_IS_ACTIONABLE (actionable));
 127
 128   GTK_ACTIONABLE_GET_IFACE (actionable)
 129     ->set_action_name (actionable, action_name);
 130 }
 131
 132 /**
 133  * gtk_actionable_get_action_target_value:
 134  * @actionable: a #GtkActionable widget
 135  *
 136  * Gets the current target value of @actionabe.
 137  *
 138  * See gtk_actionable_set_target_value() for more information.
 139  *
 140  * Returns: (transfer none): the current target value
 141  *
 142  * Since: 3.4
 143  **/
 144 GVariant *
 145 gtk_actionable_get_action_target_value (GtkActionable *actionable)
 146 {
 147   g_return_val_if_fail (GTK_IS_ACTIONABLE (actionable), NULL);
 148
 149   return GTK_ACTIONABLE_GET_IFACE (actionable)
 150     ->get_action_target_value (actionable);
 151 }
 152
 153 /**
 154  * gtk_actionable_set_action_target_value:
 155  * @actionable: a #GtkActionable widget
 156  * @target_value: a #GVariant to set as the target value, or %NULL
 157  *
 158  * Sets the target value of an actionable widget.
 159  *
 160  * If @target_value is %NULL then the target value is unset.
 161  *
 162  * The target value has two purposes.  First, it is used as the
 163  * parameter to activation of the action associated with the
 164  * #GtkActionable widget. Second, it is used to determine if the widget
 165  * should be rendered as "active" - the widget is active if the state
 166  * is equal to the given target.
 167  *
 168  * Consider the example of associating a set of buttons with a #GAction
 169  * with string state in a typical "radio button" situation.  Each button
 170  * will be associated with the same action, but with a different target
 171  * value for that action.  Clicking on a particular button will activate
 172  * the action with the target of that button, which will typically cause
 173  * the action's state to change to that value.  Since the action's state
 174  * is now equal to the target value of the button, the button will now
 175  * be rendered as active (and the other buttons, with different targets,
 176  * rendered inactive).
 177  *
 178  * Since: 3.4
 179  **/
 180 void
 181 gtk_actionable_set_action_target_value (GtkActionable *actionable,
 182                                         GVariant      *target_value)
 183 {
 184   g_return_if_fail (GTK_IS_ACTIONABLE (actionable));
 185
 186   GTK_ACTIONABLE_GET_IFACE (actionable)
 187     ->set_action_target_value (actionable, target_value);
 188 }
 189
 190 /**
 191  * gtk_actionable_set_action_target:
 192  * @actionable: a #GtkActionable widget
 193  * @format_string: a GVariant format string
 194  * @...: arguments appropriate for @format_string
 195  *
 196  * Sets the target of an actionable widget.
 197  *
 198  * This is a convenience function that calls g_variant_new() for
 199  * @format_string and uses the result to call
 200  * gtk_actionable_set_action_target_value().
 201  *
 202  * If you are setting a string-valued target and want to set the action
 203  * name at the same time, you can use
 204  * gtk_actionable_set_detailed_action_name ().
 205  *
 206  * Since: 3.4
 207  **/
 208 void
 209 gtk_actionable_set_action_target (GtkActionable *actionable,
 210                                   const gchar   *format_string,
 211                                   ...)
 212 {
 213   va_list ap;
 214
 215   va_start (ap, format_string);
 216   gtk_actionable_set_action_target_value (actionable, g_variant_new_va (format_string, NULL, &ap));
 217   va_end (ap);
 218 }
 219
 220 /**
 221  * gtk_actionable_set_detailed_action_name:
 222  * @actionable: a #GtkActionable widget
 223  * @detailed_action_name: the detailed action name
 224  *
 225  * Sets the action-name and associated string target value of an
 226  * actionable widget.
 227  *
 228  * This allows for the effect of both gtk_actionable_set_action_name()
 229  * and gtk_actionable_set_target() in the common case that the target is
 230  * string-valued.
 231  *
 232  * @detailed_action_name is a string of the form
 233  * <literal>"action::target"</literal> where <literal>action</literal>
 234  * is the action name and <literal>target</literal> is the string to use
 235  * as the target.
 236  *
 237  * Since: 3.4
 238  **/
 239 void
 240 gtk_actionable_set_detailed_action_name (GtkActionable *actionable,
 241                                          const gchar   *detailed_action_name)
 242 {
 243   gchar **parts;
 244
 245   g_return_if_fail (GTK_IS_ACTIONABLE (actionable));
 246
 247   if (detailed_action_name == NULL)
 248     {
 249       gtk_actionable_set_action_name (actionable, NULL);
 250       gtk_actionable_set_action_target_value (actionable, NULL);
 251       return;
 252     }
 253
 254   parts = g_strsplit (detailed_action_name, "::", 2);
 255   gtk_actionable_set_action_name (actionable, parts[0]);
 256   if (parts[0] && parts[1])
 257     gtk_actionable_set_action_target (actionable, "s", parts[1]);
 258   else
 259     gtk_actionable_set_action_target_value (actionable, NULL);
 260   g_strfreev (parts);
 261 }