gtkactionable.c 8.3 KB
Newer Older
1 2 3
/*
 * Copyright © 2012 Canonical Limited
 *
Javier Jardón's avatar
Javier Jardón committed
4
 * This library is free software: you can redistribute it and/or modify
5 6 7 8 9 10 11 12 13 14
 * 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
Javier Jardón's avatar
Javier Jardón committed
15
 * License along with this library. If not, see <http://www.gnu.org/licenses/>.
16 17 18 19 20 21 22 23 24 25 26
 *
 * Authors: Ryan Lortie <desrt@desrt.ca>
 */

#include "config.h"

#include "gtkactionable.h"

#include "gtkwidget.h"
#include "gtkintl.h"

27 28 29
/**
 * SECTION:gtkactionable
 * @title: GtkActionable
Matthias Clasen's avatar
Matthias Clasen committed
30 31
 * @short_description: An interface for widgets that can be associated
 *     with actions
32 33 34 35
 *
 * This interface provides a convenient way of associating widgets with
 * actions on a #GtkApplicationWindow or #GtkApplication.
 *
Matthias Clasen's avatar
Matthias Clasen committed
36 37 38
 * It primarily consists of two properties: #GtkActionable:action-name
 * and #GtkActionable:action-target. There are also some convenience APIs
 * for setting these properties.
39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55
 *
 * 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:
Matthias Clasen's avatar
Matthias Clasen committed
56 57 58
 * @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()
59 60 61 62 63
 * @set_action_target_value: virtual pointer for gtk_actionable_set_action_target_value
 *
 * The interface vtable for #GtkActionable.
 **/

64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79
G_DEFINE_INTERFACE (GtkActionable, gtk_actionable, GTK_TYPE_WIDGET)

static void
gtk_actionable_default_init (GtkActionableInterface *iface)
{
  g_object_interface_install_property (iface,
    g_param_spec_string ("action-name", P_("action name"),
                         P_("The name of the associated action, like 'app.quit'"),
                         NULL, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));

  g_object_interface_install_property (iface,
    g_param_spec_variant ("action-target", P_("action target value"),
                          P_("The parameter for action invocations"),
                          G_VARIANT_TYPE_ANY, NULL, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
}

80 81 82 83 84 85 86 87 88 89 90 91
/**
 * 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
 **/
92 93 94 95 96 97 98 99 100
const gchar *
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);
}

101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119
/**
 * 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
 **/
120 121 122 123 124 125 126 127 128 129
void
gtk_actionable_set_action_name (GtkActionable *actionable,
                                const gchar   *action_name)
{
  g_return_if_fail (GTK_IS_ACTIONABLE (actionable));

  GTK_ACTIONABLE_GET_IFACE (actionable)
    ->set_action_name (actionable, action_name);
}

130 131 132 133 134 135
/**
 * gtk_actionable_get_action_target_value:
 * @actionable: a #GtkActionable widget
 *
 * Gets the current target value of @actionabe.
 *
136
 * See gtk_actionable_set_action_target_value() for more information.
137 138 139 140 141
 *
 * Returns: (transfer none): the current target value
 *
 * Since: 3.4
 **/
142 143 144 145 146 147 148 149 150
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);
}

151 152 153 154 155 156 157 158 159 160 161
/**
 * 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
Matthias Clasen's avatar
Matthias Clasen committed
162 163
 * #GtkActionable widget. Second, it is used to determine if the widget
 * should be rendered as "active" - the widget is active if the state
164 165 166 167 168 169 170 171 172 173 174 175 176 177
 * 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
 **/
178 179 180 181 182 183 184 185 186 187
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);
}

188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205
/**
 * 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
 **/
206 207 208 209 210 211 212 213 214 215 216 217
void
gtk_actionable_set_action_target (GtkActionable *actionable,
                                  const gchar   *format_string,
                                  ...)
{
  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);
}

218 219 220 221 222 223 224 225 226
/**
 * 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()
227 228
 * and gtk_actionable_set_action_target_value() in the common case that
 * the target is string-valued.
229 230 231 232 233 234 235 236
 *
 * @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
 **/
237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259
void
gtk_actionable_set_detailed_action_name (GtkActionable *actionable,
                                         const gchar   *detailed_action_name)
{
  gchar **parts;

  g_return_if_fail (GTK_IS_ACTIONABLE (actionable));

  if (detailed_action_name == NULL)
    {
      gtk_actionable_set_action_name (actionable, NULL);
      gtk_actionable_set_action_target_value (actionable, NULL);
      return;
    }

  parts = g_strsplit (detailed_action_name, "::", 2);
  gtk_actionable_set_action_name (actionable, parts[0]);
  if (parts[0] && parts[1])
    gtk_actionable_set_action_target (actionable, "s", parts[1]);
  else
    gtk_actionable_set_action_target_value (actionable, NULL);
  g_strfreev (parts);
}