1 /* gbinding.c: Binding for object properties
3 * Copyright (C) 2010 Intel Corp.
5 * This library is free software; you can redistribute it and/or
6 * modify it under the terms of the GNU Lesser General Public
7 * License as published by the Free Software Foundation; either
8 * version 2 of the License, or (at your option) any later version.
10 * This library is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 * Lesser General Public License for more details.
15 * You should have received a copy of the GNU Lesser General
16 * Public License along with this library; if not, write to the
17 * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
18 * Boston, MA 02111-1307, USA.
20 * Author: Emmanuele Bassi <ebassi@linux.intel.com>
26 * @Short_Description: Bind two object properties
28 * #GBinding is the representation of a binding between a property on a
29 * #GObject instance (or source) and another property on another #GObject
30 * instance (or target). Whenever the source property changes, the same
31 * value is applied to the target property; for instance, the following
35 * g_object_bind_property (object1, "property-a",
36 * object2, "property-b",
40 * will cause <emphasis>object2:property-b</emphasis> to be updated every
41 * time g_object_set() or the specific accessor changes the value of
42 * <emphasis>object1:property-a</emphasis>.
44 * It is possible to create a bidirectional binding between two properties
45 * of two #GObject instances, so that if either property changes, the
46 * other is updated as well, for instance:
49 * g_object_bind_property (object1, "property-a",
50 * object2, "property-b",
51 * G_BINDING_BIDIRECTIONAL);
54 * will keep the two properties in sync.
56 * It is also possible to set a custom transformation function (in both
57 * directions, in case of a bidirectional binding) to apply a custom
58 * transformation from the source value to the target value before
59 * applying it; for instance, the following binding:
62 * g_object_bind_property_full (adjustment1, "value",
63 * adjustment2, "value",
64 * G_BINDING_BIDIRECTIONAL,
65 * celsius_to_fahrenheit,
66 * fahrenheit_to_celsius,
70 * will keep the <emphasis>value</emphasis> property of the two adjustments
71 * in sync; the <function>celsius_to_fahrenheit</function> function will be
72 * called whenever the <emphasis>adjustment1:value</emphasis> property changes
73 * and will transform the current value of the property before applying it
74 * to the <emphasis>adjustment2:value</emphasis> property; vice versa, the
75 * <function>fahrenheit_to_celsius</function> function will be called whenever
76 * the <emphasis>adjustment2:value</emphasis> property changes, and will
77 * transform the current value of the property before applying it to the
78 * <emphasis>adjustment1:value</emphasis>.
80 * Note that #GBinding does not resolve cycles by itself; a cycle like
83 * object1:propertyA -> object2:propertyB
84 * object2:propertyB -> object3:propertyC
85 * object3:propertyC -> object1:propertyA
88 * might lead to an infinite loop. The loop, in this particular case,
89 * can be avoided if the objects emit the #GObject::notify signal only
90 * if the value has effectively been changed. A binding is implemented
91 * using the #GObject::notify signal, so it is susceptible to all the
92 * various ways of blocking a signal emission, like g_signal_stop_emission()
93 * or g_signal_handler_block().
95 * A binding will be severed, and the resources it allocates freed, whenever
96 * either one of the #GObject instances it refers to are finalized, or when
97 * the #GBinding instance loses its last reference.
99 * #GBinding is available since GObject 2.26
106 #include "gbinding.h"
110 #include "gparamspecs.h"
111 #include "gvaluetypes.h"
113 #include "glibintl.h"
115 #include "gobjectalias.h"
118 g_binding_flags_get_type (void)
120 static volatile gsize g_define_type_id__volatile = 0;
122 if (g_once_init_enter (&g_define_type_id__volatile))
124 static const GFlagsValue values[] = {
125 { G_BINDING_DEFAULT, "G_BINDING_DEFAULT", "default" },
126 { G_BINDING_BIDIRECTIONAL, "G_BINDING_BIDIRECTIONAL", "bidirectional" },
129 GType g_define_type_id =
130 g_flags_register_static (g_intern_static_string ("GBindingFlags"), values);
131 g_once_init_leave (&g_define_type_id__volatile, g_define_type_id);
134 return g_define_type_id__volatile;
137 #define G_BINDING_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST ((klass), G_TYPE_BINDING, GBindingClass))
138 #define G_IS_BINDING_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), G_TYPE_BINDING))
139 #define G_BINDING_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), G_TYPE_BINDING, GBindingClass))
141 typedef struct _GBindingClass GBindingClass;
145 GObject parent_instance;
147 /* no reference is held on the objects, to avoid cycles */
151 /* the property names are interned, so they should not be freed */
152 gchar *source_property;
153 gchar *target_property;
155 GParamSpec *source_pspec;
156 GParamSpec *target_pspec;
158 GBindingTransformFunc transform_s2t;
159 GBindingTransformFunc transform_t2s;
166 gpointer transform_data;
167 GDestroyNotify notify;
169 /* a guard, to avoid loops */
173 struct _GBindingClass
175 GObjectClass parent_class;
184 PROP_SOURCE_PROPERTY,
185 PROP_TARGET_PROPERTY,
189 static GQuark quark_gbinding = 0;
191 G_DEFINE_TYPE (GBinding, g_binding, G_TYPE_OBJECT);
194 add_binding_qdata (GObject *gobject,
199 bindings = g_object_get_qdata (gobject, quark_gbinding);
200 if (bindings == NULL)
202 bindings = g_list_prepend (NULL, binding);
203 g_object_set_qdata (gobject, quark_gbinding, bindings);
206 bindings = g_list_prepend (bindings, binding);
210 remove_binding_qdata (GObject *gobject,
215 bindings = g_object_get_qdata (gobject, quark_gbinding);
216 bindings = g_list_remove (bindings, binding);
220 weak_unbind (gpointer user_data,
221 GObject *where_the_object_was)
223 GBinding *binding = user_data;
225 if (binding->source == where_the_object_was)
226 binding->source = NULL;
229 if (binding->source_notify != 0)
230 g_signal_handler_disconnect (binding->source, binding->source_notify);
232 g_object_weak_unref (binding->source, weak_unbind, user_data);
233 remove_binding_qdata (binding->source, binding);
234 binding->source = NULL;
237 if (binding->target == where_the_object_was)
238 binding->target = NULL;
241 if (binding->target_notify != 0)
242 g_signal_handler_disconnect (binding->target, binding->target_notify);
244 g_object_weak_unref (binding->target, weak_unbind, user_data);
245 remove_binding_qdata (binding->target, binding);
246 binding->target = NULL;
249 g_object_unref (binding);
252 static inline gboolean
253 default_transform (const GValue *value_a,
256 /* if it's not the same type, try to convert it using the GValue
257 * transformation API; otherwise just copy it
259 if (!g_type_is_a (G_VALUE_TYPE (value_a), G_VALUE_TYPE (value_b)))
261 /* are these two types compatible (can be directly copied)? */
262 if (g_value_type_compatible (G_VALUE_TYPE (value_a),
263 G_VALUE_TYPE (value_b)))
265 g_value_copy (value_a, value_b);
269 if (g_value_type_transformable (G_VALUE_TYPE (value_a),
270 G_VALUE_TYPE (value_b)))
272 if (g_value_transform (value_a, value_b))
275 g_warning ("%s: Unable to convert a value of type %s to a "
278 g_type_name (G_VALUE_TYPE (value_a)),
279 g_type_name (G_VALUE_TYPE (value_b)));
285 g_value_copy (value_a, value_b);
292 default_transform_to (GBinding *binding G_GNUC_UNUSED,
293 const GValue *value_a,
295 gpointer user_data G_GNUC_UNUSED)
297 return default_transform (value_a, value_b);
301 default_transform_from (GBinding *binding G_GNUC_UNUSED,
302 const GValue *value_a,
304 gpointer user_data G_GNUC_UNUSED)
306 return default_transform (value_a, value_b);
310 on_source_notify (GObject *gobject,
315 GValue source_value = { 0, };
316 GValue target_value = { 0, };
319 if (binding->is_frozen)
322 if (pspec->flags & G_PARAM_STATIC_NAME)
323 p_name = g_intern_static_string (pspec->name);
325 p_name = g_intern_string (pspec->name);
327 if (p_name != binding->source_property)
330 g_value_init (&source_value, G_PARAM_SPEC_VALUE_TYPE (binding->source_pspec));
331 g_value_init (&target_value, G_PARAM_SPEC_VALUE_TYPE (binding->target_pspec));
333 g_object_get_property (binding->source, binding->source_pspec->name, &source_value);
335 res = binding->transform_s2t (binding,
338 binding->transform_data);
341 binding->is_frozen = TRUE;
343 g_param_value_validate (binding->target_pspec, &target_value);
344 g_object_set_property (binding->target, binding->target_pspec->name, &target_value);
346 binding->is_frozen = FALSE;
349 g_value_unset (&source_value);
350 g_value_unset (&target_value);
354 on_target_notify (GObject *gobject,
359 GValue source_value = { 0, };
360 GValue target_value = { 0, };
363 if (binding->is_frozen)
366 if (pspec->flags & G_PARAM_STATIC_NAME)
367 p_name = g_intern_static_string (pspec->name);
369 p_name = g_intern_string (pspec->name);
371 if (p_name != binding->target_property)
374 g_value_init (&source_value, G_PARAM_SPEC_VALUE_TYPE (binding->target_pspec));
375 g_value_init (&target_value, G_PARAM_SPEC_VALUE_TYPE (binding->source_pspec));
377 g_object_get_property (binding->target, binding->target_pspec->name, &source_value);
379 res = binding->transform_t2s (binding,
382 binding->transform_data);
385 binding->is_frozen = TRUE;
387 g_param_value_validate (binding->source_pspec, &target_value);
388 g_object_set_property (binding->source, binding->source_pspec->name, &target_value);
390 binding->is_frozen = FALSE;
393 g_value_unset (&source_value);
394 g_value_unset (&target_value);
398 g_binding_finalize (GObject *gobject)
400 GBinding *binding = G_BINDING (gobject);
402 if (binding->notify != NULL)
404 binding->notify (binding->transform_data);
406 binding->transform_data = NULL;
407 binding->notify = NULL;
410 if (binding->source != NULL)
412 if (binding->source_notify != 0)
413 g_signal_handler_disconnect (binding->source, binding->source_notify);
415 g_object_weak_unref (binding->source, weak_unbind, binding);
416 remove_binding_qdata (binding->source, binding);
419 if (binding->target != NULL)
421 if (binding->target_notify != 0)
422 g_signal_handler_disconnect (binding->target, binding->target_notify);
424 g_object_weak_unref (binding->target, weak_unbind, binding);
425 remove_binding_qdata (binding->target, binding);
428 G_OBJECT_CLASS (g_binding_parent_class)->finalize (gobject);
432 g_binding_set_property (GObject *gobject,
437 GBinding *binding = G_BINDING (gobject);
442 binding->source = g_value_get_object (value);
445 case PROP_SOURCE_PROPERTY:
446 binding->source_property = g_intern_string (g_value_get_string (value));
450 binding->target = g_value_get_object (value);
453 case PROP_TARGET_PROPERTY:
454 binding->target_property = g_intern_string (g_value_get_string (value));
458 binding->flags = g_value_get_flags (value);
462 G_OBJECT_WARN_INVALID_PROPERTY_ID (gobject, prop_id, pspec);
468 g_binding_get_property (GObject *gobject,
473 GBinding *binding = G_BINDING (gobject);
478 g_value_set_object (value, binding->source);
481 case PROP_SOURCE_PROPERTY:
482 g_value_set_string (value, binding->source_property);
486 g_value_set_object (value, binding->target);
489 case PROP_TARGET_PROPERTY:
490 g_value_set_string (value, binding->target_property);
494 g_value_set_flags (value, binding->flags);
498 G_OBJECT_WARN_INVALID_PROPERTY_ID (gobject, prop_id, pspec);
504 g_binding_constructed (GObject *gobject)
506 GBinding *binding = G_BINDING (gobject);
508 /* assert that we were constructed correctly */
509 g_assert (binding->source != NULL);
510 g_assert (binding->target != NULL);
511 g_assert (binding->source_property != NULL);
512 g_assert (binding->target_property != NULL);
514 /* we assume a check was performed prior to construction - since
515 * g_object_bind_property_full() does it; we cannot fail construction
516 * anyway, so it would be hard for use to properly warn here
518 binding->source_pspec = g_object_class_find_property (G_OBJECT_GET_CLASS (binding->source), binding->source_property);
519 binding->target_pspec = g_object_class_find_property (G_OBJECT_GET_CLASS (binding->target), binding->target_property);
520 g_assert (binding->source_pspec != NULL);
521 g_assert (binding->target_pspec != NULL);
523 /* set the default transformation functions here */
524 binding->transform_s2t = default_transform_to;
525 binding->transform_t2s = default_transform_from;
527 binding->transform_data = NULL;
528 binding->notify = NULL;
530 binding->source_notify = g_signal_connect (binding->source, "notify",
531 G_CALLBACK (on_source_notify),
534 g_object_weak_ref (binding->source, weak_unbind, binding);
535 add_binding_qdata (binding->source, binding);
537 if (binding->flags & G_BINDING_BIDIRECTIONAL)
538 binding->target_notify = g_signal_connect (binding->target, "notify",
539 G_CALLBACK (on_target_notify),
542 g_object_weak_ref (binding->target, weak_unbind, binding);
543 add_binding_qdata (binding->target, binding);
548 g_binding_class_init (GBindingClass *klass)
550 GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
552 quark_gbinding = g_quark_from_static_string ("g-binding");
554 gobject_class->constructed = g_binding_constructed;
555 gobject_class->set_property = g_binding_set_property;
556 gobject_class->get_property = g_binding_get_property;
557 gobject_class->finalize = g_binding_finalize;
562 * The #GObject that should be used as the source of the binding
566 g_object_class_install_property (gobject_class, PROP_SOURCE,
567 g_param_spec_object ("source",
569 P_("The source of the binding"),
571 G_PARAM_CONSTRUCT_ONLY |
573 G_PARAM_STATIC_STRINGS));
577 * The #GObject that should be used as the target of the binding
581 g_object_class_install_property (gobject_class, PROP_TARGET,
582 g_param_spec_object ("target",
584 P_("The target of the binding"),
586 G_PARAM_CONSTRUCT_ONLY |
588 G_PARAM_STATIC_STRINGS));
590 * GBinding:source-property:
592 * The name of the property of #GBinding:source that should be used
593 * as the source of the binding
597 g_object_class_install_property (gobject_class, PROP_SOURCE_PROPERTY,
598 g_param_spec_string ("source-property",
599 P_("Source Property"),
600 P_("The property on the source to bind"),
602 G_PARAM_CONSTRUCT_ONLY |
604 G_PARAM_STATIC_STRINGS));
606 * GBinding:target-property:
608 * The name of the property of #GBinding:target that should be used
609 * as the target of the binding
613 g_object_class_install_property (gobject_class, PROP_TARGET_PROPERTY,
614 g_param_spec_string ("target-property",
615 P_("Target Property"),
616 P_("The property on the target to bind"),
618 G_PARAM_CONSTRUCT_ONLY |
620 G_PARAM_STATIC_STRINGS));
624 * Flags to be used to control the #GBinding
628 g_object_class_install_property (gobject_class, PROP_FLAGS,
629 g_param_spec_flags ("flags",
631 P_("The binding flags"),
632 G_TYPE_BINDING_FLAGS,
634 G_PARAM_CONSTRUCT_ONLY |
636 G_PARAM_STATIC_STRINGS));
640 g_binding_init (GBinding *binding)
645 * g_binding_get_flags:
646 * @binding: a #GBinding
648 * Retrieves the flags passed when constructing the #GBinding
650 * Return value: the #GBindingFlags used by the #GBinding
655 g_binding_get_flags (GBinding *binding)
657 g_return_val_if_fail (G_IS_BINDING (binding), G_BINDING_DEFAULT);
659 return binding->flags;
663 * g_binding_get_source:
664 * @binding: a #GBinding
666 * Retrieves the #GObject instance used as the source of the binding
668 * Return value: (transfer none): the source #GObject
673 g_binding_get_source (GBinding *binding)
675 g_return_val_if_fail (G_IS_BINDING (binding), NULL);
677 return binding->source;
681 * g_binding_get_target:
682 * @binding: a #GBinding
684 * Retrieves the #GObject instance used as the target of the binding
686 * Return value: (transfer none): the target #GObject
691 g_binding_get_target (GBinding *binding)
693 g_return_val_if_fail (G_IS_BINDING (binding), NULL);
695 return binding->target;
699 * g_binding_get_source_property:
700 * @binding: a #GBinding
702 * Retrieves the name of the property of #GBinding:source used as the source
705 * Return value: the name of the source property
709 G_CONST_RETURN gchar *
710 g_binding_get_source_property (GBinding *binding)
712 g_return_val_if_fail (G_IS_BINDING (binding), NULL);
714 return binding->source_property;
718 * g_binding_get_target_property:
719 * @binding: a #GBinding
721 * Retrieves the name of the property of #GBinding:target used as the target
724 * Return value: the name of the target property
728 G_CONST_RETURN gchar *
729 g_binding_get_target_property (GBinding *binding)
731 g_return_val_if_fail (G_IS_BINDING (binding), NULL);
733 return binding->target_property;
737 * g_object_bind_property_full:
738 * @source: the source #GObject
739 * @source_property: the property on @source to bind
740 * @target: the target #GObject
741 * @target_property: the property on @target to bind
742 * @flags: flags to pass to #GBinding
743 * @transform_to: (scope notified) (allow-none): the transformation function
744 * from the @source to the @target, or %NULL to use the default
745 * @transform_from: (scope notified) (allow-none): the transformation function
746 * from the @target to the @source, or %NULL to use the default
747 * @user_data: custom data to be passed to the transformation functions,
749 * @notify: function to be called when disposing the binding, to free the
750 * resources used by the transformation functions
752 * Complete version of g_object_bind_property().
754 * Creates a binding between @source_property on @source and @target_property
755 * on @target, allowing you to set the transformation functions to be used by
758 * If @flags contains %G_BINDING_BIDIRECTIONAL then the binding will be mutual:
759 * if @target_property on @target changes then the @source_property on @source
760 * will be updated as well. The @transform_from function is only used in case
761 * of bidirectional bindings, otherwise it will be ignored
763 * The binding will automatically be removed when either the @source or the
764 * @target instances are finalized. To remove the binding without affecting the
765 * @source and the @target you can just call g_object_unref() on the returned
766 * #GBinding instance.
768 * A #GObject can have multiple bindings.
770 * Return value: (transfer none): the #GBinding instance representing the
771 * binding between the two #GObject instances. The binding is released
772 * whenever the #GBinding reference count reaches zero.
777 g_object_bind_property_full (gpointer source,
778 const gchar *source_property,
780 const gchar *target_property,
782 GBindingTransformFunc transform_to,
783 GBindingTransformFunc transform_from,
785 GDestroyNotify notify)
790 g_return_val_if_fail (G_IS_OBJECT (source), NULL);
791 g_return_val_if_fail (source_property != NULL, NULL);
792 g_return_val_if_fail (G_IS_OBJECT (target), NULL);
793 g_return_val_if_fail (target_property != NULL, NULL);
795 if (source == target && g_strcmp0 (source_property, target_property) == 0)
797 g_warning ("Unable to bind the same property on the same instance");
801 if (transform_to == NULL)
802 transform_to = default_transform_to;
804 if (transform_from == NULL)
805 transform_from = default_transform_from;
807 pspec = g_object_class_find_property (G_OBJECT_GET_CLASS (source), source_property);
810 g_warning ("%s: The source object of type %s has no property called '%s'",
812 G_OBJECT_TYPE_NAME (source),
817 if (!(pspec->flags & G_PARAM_READABLE))
819 g_warning ("%s: The source object of type %s has no readable property called '%s'",
821 G_OBJECT_TYPE_NAME (source),
826 if ((flags & G_BINDING_BIDIRECTIONAL) &&
827 ((pspec->flags & G_PARAM_CONSTRUCT_ONLY) || !(pspec->flags & G_PARAM_WRITABLE)))
829 g_warning ("%s: The source object of type %s has no writable property called '%s'",
831 G_OBJECT_TYPE_NAME (source),
836 pspec = g_object_class_find_property (G_OBJECT_GET_CLASS (target), target_property);
839 g_warning ("%s: The target object of type %s has no property called '%s'",
841 G_OBJECT_TYPE_NAME (target),
846 if ((pspec->flags & G_PARAM_CONSTRUCT_ONLY) || !(pspec->flags & G_PARAM_WRITABLE))
848 g_warning ("%s: The target object of type %s has no writable property called '%s'",
850 G_OBJECT_TYPE_NAME (target),
855 if ((flags & G_BINDING_BIDIRECTIONAL) &&
856 !(pspec->flags & G_PARAM_READABLE))
858 g_warning ("%s: The starget object of type %s has no writable property called '%s'",
860 G_OBJECT_TYPE_NAME (target),
865 binding = g_object_new (G_TYPE_BINDING,
867 "source-property", source_property,
869 "target-property", target_property,
873 /* making these properties would be awkward, though not impossible */
874 binding->transform_s2t = transform_to;
875 binding->transform_t2s = transform_from;
876 binding->transform_data = user_data;
877 binding->notify = notify;
883 * g_object_bind_property:
884 * @source: the source #GObject
885 * @source_property: the property on @source to bind
886 * @target: the target #GObject
887 * @target_property: the property on @target to bind
888 * @flags: flags to pass to #GBinding
890 * Creates a binding between @source_property on @source and @target_property
891 * on @target. Whenever the @source_property is changed the @target_property is
892 * updated using the same value. For instance:
895 * g_object_bind_property (action, "active", widget, "sensitive", 0);
898 * Will result in the "sensitive" property of the widget #GObject instance to be
899 * updated with the same value of the "active" property of the action #GObject
902 * If @flags contains %G_BINDING_BIDIRECTIONAL then the binding will be mutual:
903 * if @target_property on @target changes then the @source_property on @source
904 * will be updated as well.
906 * The binding will automatically be removed when either the @source or the
907 * @target instances are finalized. To remove the binding without affecting the
908 * @source and the @target you can just call g_object_unref() on the returned
909 * #GBinding instance.
911 * A #GObject can have multiple bindings.
913 * Return value: (transfer none): the #GBinding instance representing the
914 * binding between the two #GObject instances. The binding is released
915 * whenever the #GBinding reference count reaches zero.
920 g_object_bind_property (gpointer source,
921 const gchar *source_property,
923 const gchar *target_property,
926 /* type checking is done in g_object_bind_property_full() */
928 return g_object_bind_property_full (source, source_property,
929 target, target_property,
936 #define __G_BINDING_C__
937 #include "gobjectaliasdef.c"