2 * Copyright © 2013 Canonical Limited
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 published
6 * by the Free Software Foundation; either version 2 of the licence or (at
7 * your option) any later version.
9 * This library is distributed in the hope that it will be useful,
10 * but 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.
14 * You should have received a copy of the GNU Lesser General
15 * Public License along with this library; if not, write to the
16 * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
17 * Boston, MA 02111-1307, USA.
19 * Authors: Ryan Lortie <desrt@desrt.ca>
24 #include "gpropertyaction.h"
26 #include "gsettings-mapping.h"
31 * SECTION:gpropertyaction
32 * @title: GPropertyAction
33 * @short_description: A GAction reflecting a GObject property
36 * A #GPropertyAction is a way to get a #GAction with a state value
37 * reflecting and controlling the value of a #GObject property.
39 * The state of the action will correspond to the value of the property.
40 * Changing it will change the property (assuming the requested value
41 * matches the requirements as specified in the #GParamSpec).
43 * Only the most common types are presently supported. Booleans are
44 * mapped to booleans, strings to strings, signed/unsigned integers to
45 * int32/uint32 and floats and doubles to doubles.
47 * If the property is an enum then the state will be string-typed and
48 * conversion will automatically be performed between the enum value and
49 * "nick" string as per the #GEnumValue table.
51 * Flags types are not currently supported.
53 * Properties of object types, boxed types and pointer types are not
54 * supported and probably never will be.
56 * Properties of #GVariant types are not currently supported.
58 * If the property is boolean-valued then the action will have a NULL
59 * parameter type, and activating the action (with no parameter) will
60 * toggle the value of the property.
62 * In all other cases, the parameter type will correspond to the type of
65 * The general idea here is to reduce the number of locations where a
66 * particular piece of state is kept (and therefore has to be
67 * synchronised between). #GPropertyAction does not have a separate
68 * state that is kept in sync with the property value -- its state
69 * <em>is</em> the property value.
71 * For example, it might be useful to create a #GAction corresponding to
72 * the "visible-child-name" property of a #GtkStack so that the current
73 * page can be switched from a menu. The active radio indication in the
74 * menu is then directly determined from the active page of the
77 * An anti-example would be binding the "active-id" property on a
78 * #GtkComboBox. This is because the state of the combobox itself is
79 * probably uninteresting and is actually being used to control
82 * Another anti-example would be to bind to the "visible-child-name"
83 * property of a #GtkStack if this value is actually stored in
84 * #GSettings. In that case, the real source of the value is
85 * #GSettings. If you want a #GAction to control a setting stored in
86 * #GSettings, see g_settings_create_action() instead, and possibly
87 * combine its use with g_settings_bind().
91 struct _GPropertyAction
93 GObject parent_instance;
98 const GVariantType *state_type;
104 * This type is opaque.
109 typedef GObjectClass GPropertyActionClass;
111 static void g_property_action_iface_init (GActionInterface *iface);
112 G_DEFINE_TYPE_WITH_CODE (GPropertyAction, g_property_action, G_TYPE_OBJECT,
113 G_IMPLEMENT_INTERFACE (G_TYPE_ACTION, g_property_action_iface_init))
128 g_property_action_get_name (GAction *action)
130 GPropertyAction *paction = G_PROPERTY_ACTION (action);
132 return paction->name;
135 static const GVariantType *
136 g_property_action_get_parameter_type (GAction *action)
138 GPropertyAction *paction = G_PROPERTY_ACTION (action);
140 return paction->pspec->value_type == G_TYPE_BOOLEAN ? NULL : paction->state_type;
143 static const GVariantType *
144 g_property_action_get_state_type (GAction *action)
146 GPropertyAction *paction = G_PROPERTY_ACTION (action);
148 return paction->state_type;
152 g_property_action_get_state_hint (GAction *action)
158 g_property_action_get_enabled (GAction *action)
164 g_property_action_set_state (GPropertyAction *paction,
167 GValue value = G_VALUE_INIT;
169 g_value_init (&value, paction->pspec->value_type);
170 g_settings_get_mapping (&value, variant, NULL);
171 g_object_set_property (paction->object, paction->pspec->name, &value);
172 g_value_unset (&value);
176 g_property_action_change_state (GAction *action,
179 GPropertyAction *paction = G_PROPERTY_ACTION (action);
181 g_return_if_fail (g_variant_is_of_type (value, paction->state_type));
183 g_property_action_set_state (paction, value);
187 g_property_action_get_state (GAction *action)
189 GPropertyAction *paction = G_PROPERTY_ACTION (action);
190 GValue value = G_VALUE_INIT;
193 g_value_init (&value, paction->pspec->value_type);
194 g_object_get_property (paction->object, paction->pspec->name, &value);
195 result = g_settings_set_mapping (&value, paction->state_type, NULL);
196 g_value_unset (&value);
198 return g_variant_ref_sink (result);
202 g_property_action_activate (GAction *action,
205 GPropertyAction *paction = G_PROPERTY_ACTION (action);
207 if (paction->pspec->value_type == G_TYPE_BOOLEAN)
211 g_return_if_fail (paction->pspec->value_type == G_TYPE_BOOLEAN && parameter == NULL);
213 g_object_get (paction->object, paction->pspec->name, &value, NULL);
215 g_object_set (paction->object, paction->pspec->name, value, NULL);
219 g_return_if_fail (parameter != NULL && g_variant_is_of_type (parameter, paction->state_type));
221 g_property_action_set_state (paction, parameter);
225 static const GVariantType *
226 g_property_action_determine_type (GParamSpec *pspec)
228 if (G_TYPE_IS_ENUM (pspec->value_type))
229 return G_VARIANT_TYPE_STRING;
231 switch (pspec->value_type)
234 return G_VARIANT_TYPE_BOOLEAN;
237 return G_VARIANT_TYPE_INT32;
240 return G_VARIANT_TYPE_UINT32;
244 return G_VARIANT_TYPE_DOUBLE;
247 return G_VARIANT_TYPE_STRING;
250 g_critical ("Unable to use GPropertyAction with property '%s::%s' of type '%s'",
251 g_type_name (pspec->owner_type), pspec->name, g_type_name (pspec->value_type));
257 g_property_action_notify (GObject *object,
261 GPropertyAction *paction = user_data;
263 g_assert (object == paction->object);
264 g_assert (pspec == paction->pspec);
266 g_object_notify (G_OBJECT (paction), "state");
270 g_property_action_set_property_name (GPropertyAction *paction,
271 const gchar *property_name)
276 pspec = g_object_class_find_property (G_OBJECT_GET_CLASS (paction->object), property_name);
280 g_critical ("Attempted to use non-existent property '%s::%s' for GPropertyAction",
281 G_OBJECT_TYPE_NAME (paction->object), property_name);
285 if (~pspec->flags & G_PARAM_READABLE || ~pspec->flags & G_PARAM_WRITABLE || pspec->flags & G_PARAM_CONSTRUCT_ONLY)
287 g_critical ("Property '%s::%s' used with GPropertyAction must be readable, writable, and not construct-only",
288 G_OBJECT_TYPE_NAME (paction->object), property_name);
292 paction->pspec = pspec;
294 detailed = g_strconcat ("notify::", paction->pspec->name, NULL);
295 paction->state_type = g_property_action_determine_type (paction->pspec);
296 g_signal_connect (paction->object, detailed, G_CALLBACK (g_property_action_notify), paction);
301 g_property_action_set_property (GObject *object,
306 GPropertyAction *paction = G_PROPERTY_ACTION (object);
311 paction->name = g_value_dup_string (value);
315 paction->object = g_value_dup_object (value);
318 case PROP_PROPERTY_NAME:
319 g_property_action_set_property_name (paction, g_value_get_string (value));
323 g_assert_not_reached ();
328 g_property_action_get_property (GObject *object,
333 GAction *action = G_ACTION (object);
338 g_value_set_string (value, g_property_action_get_name (action));
341 case PROP_PARAMETER_TYPE:
342 g_value_set_boxed (value, g_property_action_get_parameter_type (action));
346 g_value_set_boolean (value, g_property_action_get_enabled (action));
349 case PROP_STATE_TYPE:
350 g_value_set_boxed (value, g_property_action_get_state_type (action));
354 g_value_take_variant (value, g_property_action_get_state (action));
358 g_assert_not_reached ();
363 g_property_action_finalize (GObject *object)
365 GPropertyAction *paction = G_PROPERTY_ACTION (object);
367 g_signal_handlers_disconnect_by_func (paction->object, g_property_action_notify, paction);
368 g_object_unref (paction->object);
369 g_free (paction->name);
371 G_OBJECT_CLASS (g_property_action_parent_class)
376 g_property_action_init (GPropertyAction *property)
381 g_property_action_iface_init (GActionInterface *iface)
383 iface->get_name = g_property_action_get_name;
384 iface->get_parameter_type = g_property_action_get_parameter_type;
385 iface->get_state_type = g_property_action_get_state_type;
386 iface->get_state_hint = g_property_action_get_state_hint;
387 iface->get_enabled = g_property_action_get_enabled;
388 iface->get_state = g_property_action_get_state;
389 iface->change_state = g_property_action_change_state;
390 iface->activate = g_property_action_activate;
394 g_property_action_class_init (GPropertyActionClass *class)
396 GObjectClass *object_class = G_OBJECT_CLASS (class);
398 object_class->set_property = g_property_action_set_property;
399 object_class->get_property = g_property_action_get_property;
400 object_class->finalize = g_property_action_finalize;
403 * GPropertyAction:name:
405 * The name of the action. This is mostly meaningful for identifying
406 * the action once it has been added to a #GActionMap.
410 g_object_class_install_property (object_class, PROP_NAME,
411 g_param_spec_string ("name",
413 P_("The name used to invoke the action"),
416 G_PARAM_CONSTRUCT_ONLY |
417 G_PARAM_STATIC_STRINGS));
420 * GPropertyAction:parameter-type:
422 * The type of the parameter that must be given when activating the
427 g_object_class_install_property (object_class, PROP_PARAMETER_TYPE,
428 g_param_spec_boxed ("parameter-type",
429 P_("Parameter Type"),
430 P_("The type of GVariant passed to activate()"),
433 G_PARAM_STATIC_STRINGS));
436 * GPropertyAction:enabled:
438 * If @action is currently enabled.
440 * If the action is disabled then calls to g_action_activate() and
441 * g_action_change_state() have no effect.
445 g_object_class_install_property (object_class, PROP_ENABLED,
446 g_param_spec_boolean ("enabled",
448 P_("If the action can be activated"),
451 G_PARAM_STATIC_STRINGS));
454 * GPropertyAction:state-type:
456 * The #GVariantType of the state that the action has, or %NULL if the
457 * action is stateless.
461 g_object_class_install_property (object_class, PROP_STATE_TYPE,
462 g_param_spec_boxed ("state-type",
464 P_("The type of the state kept by the action"),
467 G_PARAM_STATIC_STRINGS));
470 * GPropertyAction:state:
472 * The state of the action, or %NULL if the action is stateless.
476 g_object_class_install_property (object_class, PROP_STATE,
477 g_param_spec_variant ("state",
479 P_("The state the action is in"),
483 G_PARAM_STATIC_STRINGS));
486 * GPropertyAction:object:
488 * The object to wrap a property on.
490 * The object must be a non-%NULL #GObject with properties.
494 g_object_class_install_property (object_class, PROP_OBJECT,
495 g_param_spec_object ("object",
497 P_("The object with the property to wrap"),
500 G_PARAM_CONSTRUCT_ONLY |
501 G_PARAM_STATIC_STRINGS));
504 * GPropertyAction:property-name:
506 * The name of the property to wrap on the object.
508 * The property must exist on the passed-in object and it must be
509 * readable and writable (and not construct-only).
513 g_object_class_install_property (object_class, PROP_PROPERTY_NAME,
514 g_param_spec_string ("property-name",
516 P_("The name of the property to wrap"),
519 G_PARAM_CONSTRUCT_ONLY |
520 G_PARAM_STATIC_STRINGS));
524 * g_property_action_new:
525 * @name: the name of the action to create
526 * @object: the object that has the property to wrap
527 * @property_name: the name of the property
529 * Creates a #GAction corresponding to the value of property
530 * @property_name on @object.
532 * The property must be existent and readable and writable (and not
535 * This function takes a reference on @object and doesn't release it
536 * until the action is destroyed.
538 * Returns: a new #GPropertyAction
543 g_property_action_new (const gchar *name,
545 const gchar *property_name)
547 g_return_val_if_fail (name != NULL, NULL);
548 g_return_val_if_fail (G_IS_OBJECT (object), NULL);
549 g_return_val_if_fail (property_name != NULL, NULL);
551 return g_object_new (G_TYPE_PROPERTY_ACTION,
554 "property-name", property_name,