1/*
2 * Copyright © 2013 Canonical Limited
3 *
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Lesser General Public
6 * License as published by the Free Software Foundation; either
7 * version 2.1 of the License, or (at your option) any later version.
8 *
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.
13 *
14 * You should have received a copy of the GNU Lesser General
15 * Public License along with this library; if not, see <http://www.gnu.org/licenses/>.
16 *
17 * Authors: Ryan Lortie <desrt@desrt.ca>
18 */
19
20#include "config.h"
21
22#include "gpropertyaction.h"
23
24#include "gsettings-mapping.h"
25#include "gaction.h"
26#include "glibintl.h"
27
28/**
29 * SECTION:gpropertyaction
30 * @title: GPropertyAction
31 * @short_description: A GAction reflecting a GObject property
32 * @include: gio/gio.h
33 *
34 * A #GPropertyAction is a way to get a #GAction with a state value
35 * reflecting and controlling the value of a #GObject property.
36 *
37 * The state of the action will correspond to the value of the property.
38 * Changing it will change the property (assuming the requested value
39 * matches the requirements as specified in the #GParamSpec).
40 *
41 * Only the most common types are presently supported. Booleans are
42 * mapped to booleans, strings to strings, signed/unsigned integers to
43 * int32/uint32 and floats and doubles to doubles.
44 *
45 * If the property is an enum then the state will be string-typed and
46 * conversion will automatically be performed between the enum value and
47 * "nick" string as per the #GEnumValue table.
48 *
49 * Flags types are not currently supported.
50 *
51 * Properties of object types, boxed types and pointer types are not
52 * supported and probably never will be.
53 *
54 * Properties of #GVariant types are not currently supported.
55 *
56 * If the property is boolean-valued then the action will have a NULL
57 * parameter type, and activating the action (with no parameter) will
58 * toggle the value of the property.
59 *
60 * In all other cases, the parameter type will correspond to the type of
61 * the property.
62 *
63 * The general idea here is to reduce the number of locations where a
64 * particular piece of state is kept (and therefore has to be synchronised
65 * between). #GPropertyAction does not have a separate state that is kept
66 * in sync with the property value -- its state is the property value.
67 *
68 * For example, it might be useful to create a #GAction corresponding to
69 * the "visible-child-name" property of a #GtkStack so that the current
70 * page can be switched from a menu. The active radio indication in the
71 * menu is then directly determined from the active page of the
72 * #GtkStack.
73 *
74 * An anti-example would be binding the "active-id" property on a
75 * #GtkComboBox. This is because the state of the combobox itself is
76 * probably uninteresting and is actually being used to control
77 * something else.
78 *
79 * Another anti-example would be to bind to the "visible-child-name"
80 * property of a #GtkStack if this value is actually stored in
81 * #GSettings. In that case, the real source of the value is
82 * #GSettings. If you want a #GAction to control a setting stored in
83 * #GSettings, see g_settings_create_action() instead, and possibly
84 * combine its use with g_settings_bind().
85 *
86 * Since: 2.38
87 **/
88struct _GPropertyAction
89{
90 GObject parent_instance;
91
92 gchar *name;
93 gpointer object;
94 GParamSpec *pspec;
95 const GVariantType *state_type;
96 gboolean invert_boolean;
97};
98
99/**
100 * GPropertyAction:
101 *
102 * This type is opaque.
103 *
104 * Since: 2.38
105 **/
106
107typedef GObjectClass GPropertyActionClass;
108
109static void g_property_action_iface_init (GActionInterface *iface);
110G_DEFINE_TYPE_WITH_CODE (GPropertyAction, g_property_action, G_TYPE_OBJECT,
111 G_IMPLEMENT_INTERFACE (G_TYPE_ACTION, g_property_action_iface_init))
112
113enum
114{
115 PROP_NONE,
116 PROP_NAME,
117 PROP_PARAMETER_TYPE,
118 PROP_ENABLED,
119 PROP_STATE_TYPE,
120 PROP_STATE,
121 PROP_OBJECT,
122 PROP_PROPERTY_NAME,
123 PROP_INVERT_BOOLEAN
124};
125
126static gboolean
127g_property_action_get_invert_boolean (GAction *action)
128{
129 GPropertyAction *paction = G_PROPERTY_ACTION (action);
130
131 return paction->invert_boolean;
132}
133
134static const gchar *
135g_property_action_get_name (GAction *action)
136{
137 GPropertyAction *paction = G_PROPERTY_ACTION (action);
138
139 return paction->name;
140}
141
142static const GVariantType *
143g_property_action_get_parameter_type (GAction *action)
144{
145 GPropertyAction *paction = G_PROPERTY_ACTION (action);
146
147 return paction->pspec->value_type == G_TYPE_BOOLEAN ? NULL : paction->state_type;
148}
149
150static const GVariantType *
151g_property_action_get_state_type (GAction *action)
152{
153 GPropertyAction *paction = G_PROPERTY_ACTION (action);
154
155 return paction->state_type;
156}
157
158static GVariant *
159g_property_action_get_state_hint (GAction *action)
160{
161 GPropertyAction *paction = G_PROPERTY_ACTION (action);
162
163 if (paction->pspec->value_type == G_TYPE_INT)
164 {
165 GParamSpecInt *pspec = (GParamSpecInt *)paction->pspec;
166 return g_variant_new (format_string: "(ii)", pspec->minimum, pspec->maximum);
167 }
168 else if (paction->pspec->value_type == G_TYPE_UINT)
169 {
170 GParamSpecUInt *pspec = (GParamSpecUInt *)paction->pspec;
171 return g_variant_new (format_string: "(uu)", pspec->minimum, pspec->maximum);
172 }
173 else if (paction->pspec->value_type == G_TYPE_FLOAT)
174 {
175 GParamSpecFloat *pspec = (GParamSpecFloat *)paction->pspec;
176 return g_variant_new (format_string: "(dd)", (double)pspec->minimum, (double)pspec->maximum);
177 }
178 else if (paction->pspec->value_type == G_TYPE_DOUBLE)
179 {
180 GParamSpecDouble *pspec = (GParamSpecDouble *)paction->pspec;
181 return g_variant_new (format_string: "(dd)", pspec->minimum, pspec->maximum);
182 }
183
184 return NULL;
185}
186
187static gboolean
188g_property_action_get_enabled (GAction *action)
189{
190 return TRUE;
191}
192
193static void
194g_property_action_set_state (GPropertyAction *paction,
195 GVariant *variant)
196{
197 GValue value = G_VALUE_INIT;
198
199 g_value_init (value: &value, g_type: paction->pspec->value_type);
200 g_settings_get_mapping (value: &value, variant, NULL);
201
202 if (paction->pspec->value_type == G_TYPE_BOOLEAN && paction->invert_boolean)
203 g_value_set_boolean (value: &value, v_boolean: !g_value_get_boolean (value: &value));
204
205 g_object_set_property (object: paction->object, property_name: paction->pspec->name, value: &value);
206 g_value_unset (value: &value);
207}
208
209static void
210g_property_action_change_state (GAction *action,
211 GVariant *value)
212{
213 GPropertyAction *paction = G_PROPERTY_ACTION (action);
214
215 g_return_if_fail (g_variant_is_of_type (value, paction->state_type));
216
217 g_property_action_set_state (paction, variant: value);
218}
219
220static GVariant *
221g_property_action_get_state (GAction *action)
222{
223 GPropertyAction *paction = G_PROPERTY_ACTION (action);
224 GValue value = G_VALUE_INIT;
225 GVariant *result;
226
227 g_value_init (value: &value, g_type: paction->pspec->value_type);
228 g_object_get_property (object: paction->object, property_name: paction->pspec->name, value: &value);
229
230 if (paction->pspec->value_type == G_TYPE_BOOLEAN && paction->invert_boolean)
231 g_value_set_boolean (value: &value, v_boolean: !g_value_get_boolean (value: &value));
232
233 result = g_settings_set_mapping (value: &value, expected_type: paction->state_type, NULL);
234 g_value_unset (value: &value);
235
236 return g_variant_ref_sink (value: result);
237}
238
239static void
240g_property_action_activate (GAction *action,
241 GVariant *parameter)
242{
243 GPropertyAction *paction = G_PROPERTY_ACTION (action);
244
245 if (paction->pspec->value_type == G_TYPE_BOOLEAN)
246 {
247 gboolean value;
248
249 g_return_if_fail (paction->pspec->value_type == G_TYPE_BOOLEAN && parameter == NULL);
250
251 g_object_get (object: paction->object, first_property_name: paction->pspec->name, &value, NULL);
252 value = !value;
253 g_object_set (object: paction->object, first_property_name: paction->pspec->name, value, NULL);
254 }
255 else
256 {
257 g_return_if_fail (parameter != NULL && g_variant_is_of_type (parameter, paction->state_type));
258
259 g_property_action_set_state (paction, variant: parameter);
260 }
261}
262
263static const GVariantType *
264g_property_action_determine_type (GParamSpec *pspec)
265{
266 if (G_TYPE_IS_ENUM (pspec->value_type))
267 return G_VARIANT_TYPE_STRING;
268
269 switch (pspec->value_type)
270 {
271 case G_TYPE_BOOLEAN:
272 return G_VARIANT_TYPE_BOOLEAN;
273
274 case G_TYPE_INT:
275 return G_VARIANT_TYPE_INT32;
276
277 case G_TYPE_UINT:
278 return G_VARIANT_TYPE_UINT32;
279
280 case G_TYPE_DOUBLE:
281 case G_TYPE_FLOAT:
282 return G_VARIANT_TYPE_DOUBLE;
283
284 case G_TYPE_STRING:
285 return G_VARIANT_TYPE_STRING;
286
287 default:
288 g_critical ("Unable to use GPropertyAction with property '%s::%s' of type '%s'",
289 g_type_name (pspec->owner_type), pspec->name, g_type_name (pspec->value_type));
290 return NULL;
291 }
292}
293
294static void
295g_property_action_notify (GObject *object,
296 GParamSpec *pspec,
297 gpointer user_data)
298{
299 GPropertyAction *paction = user_data;
300
301 g_assert (object == paction->object);
302 g_assert (pspec == paction->pspec);
303
304 g_object_notify (G_OBJECT (paction), property_name: "state");
305}
306
307static void
308g_property_action_set_property_name (GPropertyAction *paction,
309 const gchar *property_name)
310{
311 GParamSpec *pspec;
312 gchar *detailed;
313
314 pspec = g_object_class_find_property (G_OBJECT_GET_CLASS (paction->object), property_name);
315
316 if (pspec == NULL)
317 {
318 g_critical ("Attempted to use non-existent property '%s::%s' for GPropertyAction",
319 G_OBJECT_TYPE_NAME (paction->object), property_name);
320 return;
321 }
322
323 if (~pspec->flags & G_PARAM_READABLE || ~pspec->flags & G_PARAM_WRITABLE || pspec->flags & G_PARAM_CONSTRUCT_ONLY)
324 {
325 g_critical ("Property '%s::%s' used with GPropertyAction must be readable, writable, and not construct-only",
326 G_OBJECT_TYPE_NAME (paction->object), property_name);
327 return;
328 }
329
330 paction->pspec = pspec;
331
332 detailed = g_strconcat (string1: "notify::", paction->pspec->name, NULL);
333 paction->state_type = g_property_action_determine_type (pspec: paction->pspec);
334 g_signal_connect (paction->object, detailed, G_CALLBACK (g_property_action_notify), paction);
335 g_free (mem: detailed);
336}
337
338static void
339g_property_action_set_property (GObject *object,
340 guint prop_id,
341 const GValue *value,
342 GParamSpec *pspec)
343{
344 GPropertyAction *paction = G_PROPERTY_ACTION (object);
345
346 switch (prop_id)
347 {
348 case PROP_NAME:
349 paction->name = g_value_dup_string (value);
350 break;
351
352 case PROP_OBJECT:
353 paction->object = g_value_dup_object (value);
354 break;
355
356 case PROP_PROPERTY_NAME:
357 g_property_action_set_property_name (paction, property_name: g_value_get_string (value));
358 break;
359
360 case PROP_INVERT_BOOLEAN:
361 paction->invert_boolean = g_value_get_boolean (value);
362 break;
363
364 default:
365 g_assert_not_reached ();
366 }
367}
368
369static void
370g_property_action_get_property (GObject *object,
371 guint prop_id,
372 GValue *value,
373 GParamSpec *pspec)
374{
375 GAction *action = G_ACTION (object);
376
377 switch (prop_id)
378 {
379 case PROP_NAME:
380 g_value_set_string (value, v_string: g_property_action_get_name (action));
381 break;
382
383 case PROP_PARAMETER_TYPE:
384 g_value_set_boxed (value, v_boxed: g_property_action_get_parameter_type (action));
385 break;
386
387 case PROP_ENABLED:
388 g_value_set_boolean (value, v_boolean: g_property_action_get_enabled (action));
389 break;
390
391 case PROP_STATE_TYPE:
392 g_value_set_boxed (value, v_boxed: g_property_action_get_state_type (action));
393 break;
394
395 case PROP_STATE:
396 g_value_take_variant (value, variant: g_property_action_get_state (action));
397 break;
398
399 case PROP_INVERT_BOOLEAN:
400 g_value_set_boolean (value, v_boolean: g_property_action_get_invert_boolean (action));
401 break;
402
403 default:
404 g_assert_not_reached ();
405 }
406}
407
408static void
409g_property_action_finalize (GObject *object)
410{
411 GPropertyAction *paction = G_PROPERTY_ACTION (object);
412
413 g_signal_handlers_disconnect_by_func (paction->object, g_property_action_notify, paction);
414 g_object_unref (object: paction->object);
415 g_free (mem: paction->name);
416
417 G_OBJECT_CLASS (g_property_action_parent_class)
418 ->finalize (object);
419}
420
421void
422g_property_action_init (GPropertyAction *property)
423{
424}
425
426void
427g_property_action_iface_init (GActionInterface *iface)
428{
429 iface->get_name = g_property_action_get_name;
430 iface->get_parameter_type = g_property_action_get_parameter_type;
431 iface->get_state_type = g_property_action_get_state_type;
432 iface->get_state_hint = g_property_action_get_state_hint;
433 iface->get_enabled = g_property_action_get_enabled;
434 iface->get_state = g_property_action_get_state;
435 iface->change_state = g_property_action_change_state;
436 iface->activate = g_property_action_activate;
437}
438
439void
440g_property_action_class_init (GPropertyActionClass *class)
441{
442 GObjectClass *object_class = G_OBJECT_CLASS (class);
443
444 object_class->set_property = g_property_action_set_property;
445 object_class->get_property = g_property_action_get_property;
446 object_class->finalize = g_property_action_finalize;
447
448 /**
449 * GPropertyAction:name:
450 *
451 * The name of the action. This is mostly meaningful for identifying
452 * the action once it has been added to a #GActionMap.
453 *
454 * Since: 2.38
455 **/
456 g_object_class_install_property (oclass: object_class, property_id: PROP_NAME,
457 pspec: g_param_spec_string (name: "name",
458 P_("Action Name"),
459 P_("The name used to invoke the action"),
460 NULL,
461 flags: G_PARAM_READWRITE |
462 G_PARAM_CONSTRUCT_ONLY |
463 G_PARAM_STATIC_STRINGS));
464
465 /**
466 * GPropertyAction:parameter-type:
467 *
468 * The type of the parameter that must be given when activating the
469 * action.
470 *
471 * Since: 2.38
472 **/
473 g_object_class_install_property (oclass: object_class, property_id: PROP_PARAMETER_TYPE,
474 pspec: g_param_spec_boxed (name: "parameter-type",
475 P_("Parameter Type"),
476 P_("The type of GVariant passed to activate()"),
477 G_TYPE_VARIANT_TYPE,
478 flags: G_PARAM_READABLE |
479 G_PARAM_STATIC_STRINGS));
480
481 /**
482 * GPropertyAction:enabled:
483 *
484 * If @action is currently enabled.
485 *
486 * If the action is disabled then calls to g_action_activate() and
487 * g_action_change_state() have no effect.
488 *
489 * Since: 2.38
490 **/
491 g_object_class_install_property (oclass: object_class, property_id: PROP_ENABLED,
492 pspec: g_param_spec_boolean (name: "enabled",
493 P_("Enabled"),
494 P_("If the action can be activated"),
495 TRUE,
496 flags: G_PARAM_READABLE |
497 G_PARAM_STATIC_STRINGS));
498
499 /**
500 * GPropertyAction:state-type:
501 *
502 * The #GVariantType of the state that the action has, or %NULL if the
503 * action is stateless.
504 *
505 * Since: 2.38
506 **/
507 g_object_class_install_property (oclass: object_class, property_id: PROP_STATE_TYPE,
508 pspec: g_param_spec_boxed (name: "state-type",
509 P_("State Type"),
510 P_("The type of the state kept by the action"),
511 G_TYPE_VARIANT_TYPE,
512 flags: G_PARAM_READABLE |
513 G_PARAM_STATIC_STRINGS));
514
515 /**
516 * GPropertyAction:state:
517 *
518 * The state of the action, or %NULL if the action is stateless.
519 *
520 * Since: 2.38
521 **/
522 g_object_class_install_property (oclass: object_class, property_id: PROP_STATE,
523 pspec: g_param_spec_variant (name: "state",
524 P_("State"),
525 P_("The state the action is in"),
526 G_VARIANT_TYPE_ANY,
527 NULL,
528 flags: G_PARAM_READABLE |
529 G_PARAM_STATIC_STRINGS));
530
531 /**
532 * GPropertyAction:object:
533 *
534 * The object to wrap a property on.
535 *
536 * The object must be a non-%NULL #GObject with properties.
537 *
538 * Since: 2.38
539 **/
540 g_object_class_install_property (oclass: object_class, property_id: PROP_OBJECT,
541 pspec: g_param_spec_object (name: "object",
542 P_("Object"),
543 P_("The object with the property to wrap"),
544 G_TYPE_OBJECT,
545 flags: G_PARAM_WRITABLE |
546 G_PARAM_CONSTRUCT_ONLY |
547 G_PARAM_STATIC_STRINGS));
548
549 /**
550 * GPropertyAction:property-name:
551 *
552 * The name of the property to wrap on the object.
553 *
554 * The property must exist on the passed-in object and it must be
555 * readable and writable (and not construct-only).
556 *
557 * Since: 2.38
558 **/
559 g_object_class_install_property (oclass: object_class, property_id: PROP_PROPERTY_NAME,
560 pspec: g_param_spec_string (name: "property-name",
561 P_("Property name"),
562 P_("The name of the property to wrap"),
563 NULL,
564 flags: G_PARAM_WRITABLE |
565 G_PARAM_CONSTRUCT_ONLY |
566 G_PARAM_STATIC_STRINGS));
567
568 /**
569 * GPropertyAction:invert-boolean:
570 *
571 * If %TRUE, the state of the action will be the negation of the
572 * property value, provided the property is boolean.
573 *
574 * Since: 2.46
575 */
576 g_object_class_install_property (oclass: object_class, property_id: PROP_INVERT_BOOLEAN,
577 pspec: g_param_spec_boolean (name: "invert-boolean",
578 P_("Invert boolean"),
579 P_("Whether to invert the value of a boolean property"),
580 FALSE,
581 flags: G_PARAM_READWRITE |
582 G_PARAM_CONSTRUCT_ONLY |
583 G_PARAM_STATIC_STRINGS));
584}
585
586/**
587 * g_property_action_new:
588 * @name: the name of the action to create
589 * @object: (type GObject.Object): the object that has the property
590 * to wrap
591 * @property_name: the name of the property
592 *
593 * Creates a #GAction corresponding to the value of property
594 * @property_name on @object.
595 *
596 * The property must be existent and readable and writable (and not
597 * construct-only).
598 *
599 * This function takes a reference on @object and doesn't release it
600 * until the action is destroyed.
601 *
602 * Returns: a new #GPropertyAction
603 *
604 * Since: 2.38
605 **/
606GPropertyAction *
607g_property_action_new (const gchar *name,
608 gpointer object,
609 const gchar *property_name)
610{
611 g_return_val_if_fail (name != NULL, NULL);
612 g_return_val_if_fail (G_IS_OBJECT (object), NULL);
613 g_return_val_if_fail (property_name != NULL, NULL);
614
615 return g_object_new (G_TYPE_PROPERTY_ACTION,
616 first_property_name: "name", name,
617 "object", object,
618 "property-name", property_name,
619 NULL);
620}
621

source code of gtk/subprojects/glib/gio/gpropertyaction.c