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"
108 #include "gmarshal.h"
111 #include "gparamspecs.h"
112 #include "gvaluetypes.h"
114 #include "glibintl.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" },
127 { G_BINDING_SYNC_CREATE, "G_BINDING_SYNC_CREATE", "sync-create" },
128 { G_BINDING_INVERT_BOOLEAN, "G_BINDING_INVERT_BOOLEAN", "invert-boolean" },
131 GType g_define_type_id =
132 g_flags_register_static (g_intern_static_string ("GBindingFlags"), values);
133 g_once_init_leave (&g_define_type_id__volatile, g_define_type_id);
136 return g_define_type_id__volatile;
139 #define G_BINDING_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST ((klass), G_TYPE_BINDING, GBindingClass))
140 #define G_IS_BINDING_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), G_TYPE_BINDING))
141 #define G_BINDING_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), G_TYPE_BINDING, GBindingClass))
143 typedef struct _GBindingClass GBindingClass;
147 GObject parent_instance;
149 /* no reference is held on the objects, to avoid cycles */
153 /* the property names are interned, so they should not be freed */
154 gchar *source_property;
155 gchar *target_property;
157 GParamSpec *source_pspec;
158 GParamSpec *target_pspec;
160 GBindingTransformFunc transform_s2t;
161 GBindingTransformFunc transform_t2s;
168 gpointer transform_data;
169 GDestroyNotify notify;
171 /* a guard, to avoid loops */
175 struct _GBindingClass
177 GObjectClass parent_class;
186 PROP_SOURCE_PROPERTY,
187 PROP_TARGET_PROPERTY,
191 static GQuark quark_gbinding = 0;
193 G_DEFINE_TYPE (GBinding, g_binding, G_TYPE_OBJECT);
196 add_binding_qdata (GObject *gobject,
199 GHashTable *bindings;
201 bindings = g_object_get_qdata (gobject, quark_gbinding);
202 if (bindings == NULL)
204 bindings = g_hash_table_new (NULL, NULL);
206 g_object_set_qdata_full (gobject, quark_gbinding,
208 (GDestroyNotify) g_hash_table_destroy);
211 g_hash_table_insert (bindings, binding, GUINT_TO_POINTER (1));
215 remove_binding_qdata (GObject *gobject,
218 GHashTable *bindings;
220 bindings = g_object_get_qdata (gobject, quark_gbinding);
221 g_hash_table_remove (bindings, binding);
224 /* the basic assumption is that if either the source or the target
225 * goes away then the binding does not exist any more and it should
229 weak_unbind (gpointer user_data,
230 GObject *where_the_object_was)
232 GBinding *binding = user_data;
234 /* if what went away was the source, unset it so that GBinding::finalize
235 * does not try to access it; otherwise, disconnect everything and remove
236 * the GBinding instance from the object's qdata
238 if (binding->source == where_the_object_was)
239 binding->source = NULL;
242 if (binding->source_notify != 0)
243 g_signal_handler_disconnect (binding->source, binding->source_notify);
245 g_object_weak_unref (binding->source, weak_unbind, user_data);
246 remove_binding_qdata (binding->source, binding);
247 binding->source = NULL;
250 /* as above, but with the target */
251 if (binding->target == where_the_object_was)
252 binding->target = NULL;
255 if (binding->target_notify != 0)
256 g_signal_handler_disconnect (binding->target, binding->target_notify);
258 g_object_weak_unref (binding->target, weak_unbind, user_data);
259 remove_binding_qdata (binding->target, binding);
260 binding->target = NULL;
263 /* this will take care of the binding itself */
264 g_object_unref (binding);
267 static inline gboolean
268 default_transform (const GValue *value_a,
271 /* if it's not the same type, try to convert it using the GValue
272 * transformation API; otherwise just copy it
274 if (!g_type_is_a (G_VALUE_TYPE (value_a), G_VALUE_TYPE (value_b)))
276 /* are these two types compatible (can be directly copied)? */
277 if (g_value_type_compatible (G_VALUE_TYPE (value_a),
278 G_VALUE_TYPE (value_b)))
280 g_value_copy (value_a, value_b);
284 if (g_value_type_transformable (G_VALUE_TYPE (value_a),
285 G_VALUE_TYPE (value_b)))
287 if (g_value_transform (value_a, value_b))
290 g_warning ("%s: Unable to convert a value of type %s to a "
293 g_type_name (G_VALUE_TYPE (value_a)),
294 g_type_name (G_VALUE_TYPE (value_b)));
300 g_value_copy (value_a, value_b);
306 static inline gboolean
307 default_invert_boolean_transform (const GValue *value_a,
312 g_assert (G_VALUE_HOLDS_BOOLEAN (value_a));
313 g_assert (G_VALUE_HOLDS_BOOLEAN (value_b));
315 value = g_value_get_boolean (value_a);
318 g_value_set_boolean (value_b, value);
324 default_transform_to (GBinding *binding,
325 const GValue *value_a,
327 gpointer user_data G_GNUC_UNUSED)
329 if (binding->flags & G_BINDING_INVERT_BOOLEAN)
330 return default_invert_boolean_transform (value_a, value_b);
332 return default_transform (value_a, value_b);
336 default_transform_from (GBinding *binding,
337 const GValue *value_a,
339 gpointer user_data G_GNUC_UNUSED)
341 if (binding->flags & G_BINDING_INVERT_BOOLEAN)
342 return default_invert_boolean_transform (value_a, value_b);
344 return default_transform (value_a, value_b);
348 on_source_notify (GObject *gobject,
353 GValue source_value = { 0, };
354 GValue target_value = { 0, };
357 if (binding->is_frozen)
360 p_name = g_intern_string (pspec->name);
362 if (p_name != binding->source_property)
365 g_value_init (&source_value, G_PARAM_SPEC_VALUE_TYPE (binding->source_pspec));
366 g_value_init (&target_value, G_PARAM_SPEC_VALUE_TYPE (binding->target_pspec));
368 g_object_get_property (binding->source, binding->source_pspec->name, &source_value);
370 res = binding->transform_s2t (binding,
373 binding->transform_data);
376 binding->is_frozen = TRUE;
378 g_param_value_validate (binding->target_pspec, &target_value);
379 g_object_set_property (binding->target, binding->target_pspec->name, &target_value);
381 binding->is_frozen = FALSE;
384 g_value_unset (&source_value);
385 g_value_unset (&target_value);
389 on_target_notify (GObject *gobject,
394 GValue source_value = { 0, };
395 GValue target_value = { 0, };
398 if (binding->is_frozen)
401 p_name = g_intern_string (pspec->name);
403 if (p_name != binding->target_property)
406 g_value_init (&source_value, G_PARAM_SPEC_VALUE_TYPE (binding->target_pspec));
407 g_value_init (&target_value, G_PARAM_SPEC_VALUE_TYPE (binding->source_pspec));
409 g_object_get_property (binding->target, binding->target_pspec->name, &source_value);
411 res = binding->transform_t2s (binding,
414 binding->transform_data);
417 binding->is_frozen = TRUE;
419 g_param_value_validate (binding->source_pspec, &target_value);
420 g_object_set_property (binding->source, binding->source_pspec->name, &target_value);
422 binding->is_frozen = FALSE;
425 g_value_unset (&source_value);
426 g_value_unset (&target_value);
430 g_binding_finalize (GObject *gobject)
432 GBinding *binding = G_BINDING (gobject);
434 /* dispose of the transformation data */
435 if (binding->notify != NULL)
437 binding->notify (binding->transform_data);
439 binding->transform_data = NULL;
440 binding->notify = NULL;
443 /* we need this in case the source and target instance are still
444 * valid, and it was the GBinding that was unreferenced
446 if (binding->source != NULL)
448 if (binding->source_notify != 0)
449 g_signal_handler_disconnect (binding->source, binding->source_notify);
451 g_object_weak_unref (binding->source, weak_unbind, binding);
452 remove_binding_qdata (binding->source, binding);
455 if (binding->target != NULL)
457 if (binding->target_notify != 0)
458 g_signal_handler_disconnect (binding->target, binding->target_notify);
460 g_object_weak_unref (binding->target, weak_unbind, binding);
461 remove_binding_qdata (binding->target, binding);
464 G_OBJECT_CLASS (g_binding_parent_class)->finalize (gobject);
468 g_binding_set_property (GObject *gobject,
473 GBinding *binding = G_BINDING (gobject);
478 binding->source = g_value_get_object (value);
481 case PROP_SOURCE_PROPERTY:
482 binding->source_property = g_intern_string (g_value_get_string (value));
486 binding->target = g_value_get_object (value);
489 case PROP_TARGET_PROPERTY:
490 binding->target_property = g_intern_string (g_value_get_string (value));
494 binding->flags = g_value_get_flags (value);
498 G_OBJECT_WARN_INVALID_PROPERTY_ID (gobject, prop_id, pspec);
504 g_binding_get_property (GObject *gobject,
509 GBinding *binding = G_BINDING (gobject);
514 g_value_set_object (value, binding->source);
517 case PROP_SOURCE_PROPERTY:
518 g_value_set_string (value, binding->source_property);
522 g_value_set_object (value, binding->target);
525 case PROP_TARGET_PROPERTY:
526 g_value_set_string (value, binding->target_property);
530 g_value_set_flags (value, binding->flags);
534 G_OBJECT_WARN_INVALID_PROPERTY_ID (gobject, prop_id, pspec);
540 g_binding_constructed (GObject *gobject)
542 GBinding *binding = G_BINDING (gobject);
544 /* assert that we were constructed correctly */
545 g_assert (binding->source != NULL);
546 g_assert (binding->target != NULL);
547 g_assert (binding->source_property != NULL);
548 g_assert (binding->target_property != NULL);
550 /* we assume a check was performed prior to construction - since
551 * g_object_bind_property_full() does it; we cannot fail construction
552 * anyway, so it would be hard for use to properly warn here
554 binding->source_pspec = g_object_class_find_property (G_OBJECT_GET_CLASS (binding->source), binding->source_property);
555 binding->target_pspec = g_object_class_find_property (G_OBJECT_GET_CLASS (binding->target), binding->target_property);
556 g_assert (binding->source_pspec != NULL);
557 g_assert (binding->target_pspec != NULL);
559 /* set the default transformation functions here */
560 binding->transform_s2t = default_transform_to;
561 binding->transform_t2s = default_transform_from;
563 binding->transform_data = NULL;
564 binding->notify = NULL;
566 binding->source_notify = g_signal_connect (binding->source, "notify",
567 G_CALLBACK (on_source_notify),
570 g_object_weak_ref (binding->source, weak_unbind, binding);
571 add_binding_qdata (binding->source, binding);
573 if (binding->flags & G_BINDING_BIDIRECTIONAL)
574 binding->target_notify = g_signal_connect (binding->target, "notify",
575 G_CALLBACK (on_target_notify),
578 g_object_weak_ref (binding->target, weak_unbind, binding);
579 add_binding_qdata (binding->target, binding);
584 g_binding_class_init (GBindingClass *klass)
586 GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
588 quark_gbinding = g_quark_from_static_string ("g-binding");
590 gobject_class->constructed = g_binding_constructed;
591 gobject_class->set_property = g_binding_set_property;
592 gobject_class->get_property = g_binding_get_property;
593 gobject_class->finalize = g_binding_finalize;
598 * The #GObject that should be used as the source of the binding
602 g_object_class_install_property (gobject_class, PROP_SOURCE,
603 g_param_spec_object ("source",
605 P_("The source of the binding"),
607 G_PARAM_CONSTRUCT_ONLY |
609 G_PARAM_STATIC_STRINGS));
613 * The #GObject that should be used as the target of the binding
617 g_object_class_install_property (gobject_class, PROP_TARGET,
618 g_param_spec_object ("target",
620 P_("The target of the binding"),
622 G_PARAM_CONSTRUCT_ONLY |
624 G_PARAM_STATIC_STRINGS));
626 * GBinding:source-property:
628 * The name of the property of #GBinding:source that should be used
629 * as the source of the binding
633 g_object_class_install_property (gobject_class, PROP_SOURCE_PROPERTY,
634 g_param_spec_string ("source-property",
635 P_("Source Property"),
636 P_("The property on the source to bind"),
638 G_PARAM_CONSTRUCT_ONLY |
640 G_PARAM_STATIC_STRINGS));
642 * GBinding:target-property:
644 * The name of the property of #GBinding:target that should be used
645 * as the target of the binding
649 g_object_class_install_property (gobject_class, PROP_TARGET_PROPERTY,
650 g_param_spec_string ("target-property",
651 P_("Target Property"),
652 P_("The property on the target to bind"),
654 G_PARAM_CONSTRUCT_ONLY |
656 G_PARAM_STATIC_STRINGS));
660 * Flags to be used to control the #GBinding
664 g_object_class_install_property (gobject_class, PROP_FLAGS,
665 g_param_spec_flags ("flags",
667 P_("The binding flags"),
668 G_TYPE_BINDING_FLAGS,
670 G_PARAM_CONSTRUCT_ONLY |
672 G_PARAM_STATIC_STRINGS));
676 g_binding_init (GBinding *binding)
681 * g_binding_get_flags:
682 * @binding: a #GBinding
684 * Retrieves the flags passed when constructing the #GBinding
686 * Return value: the #GBindingFlags used by the #GBinding
691 g_binding_get_flags (GBinding *binding)
693 g_return_val_if_fail (G_IS_BINDING (binding), G_BINDING_DEFAULT);
695 return binding->flags;
699 * g_binding_get_source:
700 * @binding: a #GBinding
702 * Retrieves the #GObject instance used as the source of the binding
704 * Return value: (transfer none): the source #GObject
709 g_binding_get_source (GBinding *binding)
711 g_return_val_if_fail (G_IS_BINDING (binding), NULL);
713 return binding->source;
717 * g_binding_get_target:
718 * @binding: a #GBinding
720 * Retrieves the #GObject instance used as the target of the binding
722 * Return value: (transfer none): the target #GObject
727 g_binding_get_target (GBinding *binding)
729 g_return_val_if_fail (G_IS_BINDING (binding), NULL);
731 return binding->target;
735 * g_binding_get_source_property:
736 * @binding: a #GBinding
738 * Retrieves the name of the property of #GBinding:source used as the source
741 * Return value: the name of the source property
745 G_CONST_RETURN gchar *
746 g_binding_get_source_property (GBinding *binding)
748 g_return_val_if_fail (G_IS_BINDING (binding), NULL);
750 return binding->source_property;
754 * g_binding_get_target_property:
755 * @binding: a #GBinding
757 * Retrieves the name of the property of #GBinding:target used as the target
760 * Return value: the name of the target property
764 G_CONST_RETURN gchar *
765 g_binding_get_target_property (GBinding *binding)
767 g_return_val_if_fail (G_IS_BINDING (binding), NULL);
769 return binding->target_property;
773 * g_object_bind_property_full:
774 * @source: the source #GObject
775 * @source_property: the property on @source to bind
776 * @target: the target #GObject
777 * @target_property: the property on @target to bind
778 * @flags: flags to pass to #GBinding
779 * @transform_to: (scope notified) (allow-none): the transformation function
780 * from the @source to the @target, or %NULL to use the default
781 * @transform_from: (scope notified) (allow-none): the transformation function
782 * from the @target to the @source, or %NULL to use the default
783 * @user_data: custom data to be passed to the transformation functions,
785 * @notify: function to be called when disposing the binding, to free the
786 * resources used by the transformation functions
788 * Complete version of g_object_bind_property().
790 * Creates a binding between @source_property on @source and @target_property
791 * on @target, allowing you to set the transformation functions to be used by
794 * If @flags contains %G_BINDING_BIDIRECTIONAL then the binding will be mutual:
795 * if @target_property on @target changes then the @source_property on @source
796 * will be updated as well. The @transform_from function is only used in case
797 * of bidirectional bindings, otherwise it will be ignored
799 * The binding will automatically be removed when either the @source or the
800 * @target instances are finalized. To remove the binding without affecting the
801 * @source and the @target you can just call g_object_unref() on the returned
802 * #GBinding instance.
804 * A #GObject can have multiple bindings.
806 * <note>The same @user_data parameter will be used for both @transform_to
807 * and @transform_from transformation functions; the @notify function will
808 * be called once, when the binding is removed. If you need different data
809 * for each transformation function, please use
810 * g_object_bind_property_with_closures() instead.</note>
812 * Return value: (transfer none): the #GBinding instance representing the
813 * binding between the two #GObject instances. The binding is released
814 * whenever the #GBinding reference count reaches zero.
819 g_object_bind_property_full (gpointer source,
820 const gchar *source_property,
822 const gchar *target_property,
824 GBindingTransformFunc transform_to,
825 GBindingTransformFunc transform_from,
827 GDestroyNotify notify)
832 g_return_val_if_fail (G_IS_OBJECT (source), NULL);
833 g_return_val_if_fail (source_property != NULL, NULL);
834 g_return_val_if_fail (G_IS_OBJECT (target), NULL);
835 g_return_val_if_fail (target_property != NULL, NULL);
837 if (source == target && g_strcmp0 (source_property, target_property) == 0)
839 g_warning ("Unable to bind the same property on the same instance");
843 /* remove the G_BINDING_INVERT_BOOLEAN flag in case we have
844 * custom transformation functions
846 if ((flags & G_BINDING_INVERT_BOOLEAN) &&
847 (transform_to != NULL || transform_from != NULL))
849 flags &= ~G_BINDING_INVERT_BOOLEAN;
852 pspec = g_object_class_find_property (G_OBJECT_GET_CLASS (source), source_property);
855 g_warning ("%s: The source object of type %s has no property called '%s'",
857 G_OBJECT_TYPE_NAME (source),
862 if (!(pspec->flags & G_PARAM_READABLE))
864 g_warning ("%s: The source object of type %s has no readable property called '%s'",
866 G_OBJECT_TYPE_NAME (source),
871 if ((flags & G_BINDING_BIDIRECTIONAL) &&
872 ((pspec->flags & G_PARAM_CONSTRUCT_ONLY) || !(pspec->flags & G_PARAM_WRITABLE)))
874 g_warning ("%s: The source object of type %s has no writable property called '%s'",
876 G_OBJECT_TYPE_NAME (source),
881 if ((flags & G_BINDING_INVERT_BOOLEAN) &&
882 !(G_PARAM_SPEC_VALUE_TYPE (pspec) == G_TYPE_BOOLEAN))
884 g_warning ("%s: The G_BINDING_INVERT_BOOLEAN flag can only be used "
885 "when binding boolean properties; the source property '%s' "
889 g_type_name (G_PARAM_SPEC_VALUE_TYPE (pspec)));
893 pspec = g_object_class_find_property (G_OBJECT_GET_CLASS (target), target_property);
896 g_warning ("%s: The target object of type %s has no property called '%s'",
898 G_OBJECT_TYPE_NAME (target),
903 if ((pspec->flags & G_PARAM_CONSTRUCT_ONLY) || !(pspec->flags & G_PARAM_WRITABLE))
905 g_warning ("%s: The target object of type %s has no writable property called '%s'",
907 G_OBJECT_TYPE_NAME (target),
912 if ((flags & G_BINDING_BIDIRECTIONAL) &&
913 !(pspec->flags & G_PARAM_READABLE))
915 g_warning ("%s: The starget object of type %s has no writable property called '%s'",
917 G_OBJECT_TYPE_NAME (target),
922 if ((flags & G_BINDING_INVERT_BOOLEAN) &&
923 !(G_PARAM_SPEC_VALUE_TYPE (pspec) == G_TYPE_BOOLEAN))
925 g_warning ("%s: The G_BINDING_INVERT_BOOLEAN flag can only be used "
926 "when binding boolean properties; the target property '%s' "
930 g_type_name (G_PARAM_SPEC_VALUE_TYPE (pspec)));
934 binding = g_object_new (G_TYPE_BINDING,
936 "source-property", source_property,
938 "target-property", target_property,
942 if (transform_to != NULL)
943 binding->transform_s2t = transform_to;
945 if (transform_from != NULL)
946 binding->transform_t2s = transform_from;
948 binding->transform_data = user_data;
949 binding->notify = notify;
951 /* synchronize the target with the source by faking an emission of
952 * the ::notify signal for the source property; this will also take
953 * care of the bidirectional binding case because the eventual change
954 * will emit a notification on the target
956 if (flags & G_BINDING_SYNC_CREATE)
957 on_source_notify (binding->source, binding->source_pspec, binding);
963 * g_object_bind_property:
964 * @source: the source #GObject
965 * @source_property: the property on @source to bind
966 * @target: the target #GObject
967 * @target_property: the property on @target to bind
968 * @flags: flags to pass to #GBinding
970 * Creates a binding between @source_property on @source and @target_property
971 * on @target. Whenever the @source_property is changed the @target_property is
972 * updated using the same value. For instance:
975 * g_object_bind_property (action, "active", widget, "sensitive", 0);
978 * Will result in the "sensitive" property of the widget #GObject instance to be
979 * updated with the same value of the "active" property of the action #GObject
982 * If @flags contains %G_BINDING_BIDIRECTIONAL then the binding will be mutual:
983 * if @target_property on @target changes then the @source_property on @source
984 * will be updated as well.
986 * The binding will automatically be removed when either the @source or the
987 * @target instances are finalized. To remove the binding without affecting the
988 * @source and the @target you can just call g_object_unref() on the returned
989 * #GBinding instance.
991 * A #GObject can have multiple bindings.
993 * Return value: (transfer none): the #GBinding instance representing the
994 * binding between the two #GObject instances. The binding is released
995 * whenever the #GBinding reference count reaches zero.
1000 g_object_bind_property (gpointer source,
1001 const gchar *source_property,
1003 const gchar *target_property,
1004 GBindingFlags flags)
1006 /* type checking is done in g_object_bind_property_full() */
1008 return g_object_bind_property_full (source, source_property,
1009 target, target_property,
1016 typedef struct _TransformData
1018 GClosure *transform_to_closure;
1019 GClosure *transform_from_closure;
1023 bind_with_closures_transform_to (GBinding *binding,
1024 const GValue *source,
1028 TransformData *t_data = data;
1029 GValue params[3] = { { 0, }, { 0, }, { 0, } };
1030 GValue retval = { 0, };
1033 g_value_init (¶ms[0], G_TYPE_BINDING);
1034 g_value_set_object (¶ms[0], binding);
1036 g_value_init (¶ms[1], G_TYPE_VALUE);
1037 g_value_set_boxed (¶ms[1], source);
1039 g_value_init (¶ms[2], G_TYPE_VALUE);
1040 g_value_set_boxed (¶ms[2], target);
1042 g_value_init (&retval, G_TYPE_BOOLEAN);
1043 g_value_set_boolean (&retval, FALSE);
1045 g_closure_invoke (t_data->transform_to_closure, &retval, 3, params, NULL);
1047 res = g_value_get_boolean (&retval);
1050 const GValue *out_value = g_value_get_boxed (¶ms[2]);
1052 g_assert (out_value != NULL);
1054 g_value_copy (out_value, target);
1057 g_value_unset (¶ms[0]);
1058 g_value_unset (¶ms[1]);
1059 g_value_unset (¶ms[2]);
1060 g_value_unset (&retval);
1066 bind_with_closures_transform_from (GBinding *binding,
1067 const GValue *source,
1071 TransformData *t_data = data;
1072 GValue params[3] = { { 0, }, { 0, }, { 0, } };
1073 GValue retval = { 0, };
1076 g_value_init (¶ms[0], G_TYPE_BINDING);
1077 g_value_set_object (¶ms[0], binding);
1079 g_value_init (¶ms[1], G_TYPE_VALUE);
1080 g_value_set_boxed (¶ms[1], source);
1082 g_value_init (¶ms[2], G_TYPE_VALUE);
1083 g_value_set_boxed (¶ms[2], target);
1085 g_value_init (&retval, G_TYPE_BOOLEAN);
1086 g_value_set_boolean (&retval, FALSE);
1088 g_closure_invoke (t_data->transform_from_closure, &retval, 3, params, NULL);
1090 res = g_value_get_boolean (&retval);
1093 const GValue *out_value = g_value_get_boxed (¶ms[2]);
1095 g_assert (out_value != NULL);
1097 g_value_copy (out_value, target);
1100 g_value_unset (¶ms[0]);
1101 g_value_unset (¶ms[1]);
1102 g_value_unset (¶ms[2]);
1103 g_value_unset (&retval);
1109 bind_with_closures_free_func (gpointer data)
1111 TransformData *t_data = data;
1113 if (t_data->transform_to_closure != NULL)
1114 g_closure_unref (t_data->transform_to_closure);
1116 if (t_data->transform_from_closure != NULL)
1117 g_closure_unref (t_data->transform_from_closure);
1119 g_slice_free (TransformData, t_data);
1123 * g_object_bind_property_with_closures:
1124 * @source: the source #GObject
1125 * @source_property: the property on @source to bind
1126 * @target: the target #GObject
1127 * @target_property: the property on @target to bind
1128 * @flags: flags to pass to #GBinding
1129 * @transform_to: a #GClosure wrapping the transformation function
1130 * from the @source to the @target, or %NULL to use the default
1131 * @transform_from: a #GClosure wrapping the transformation function
1132 * from the @target to the @source, or %NULL to use the default
1134 * Creates a binding between @source_property on @source and @target_property
1135 * on @target, allowing you to set the transformation functions to be used by
1138 * This function is the language bindings friendly version of
1139 * g_object_bind_property_full(), using #GClosure<!-- -->s instead of
1140 * function pointers.
1142 * Rename to: g_object_bind_property_full
1144 * Return value: (transfer none): the #GBinding instance representing the
1145 * binding between the two #GObject instances. The binding is released
1146 * whenever the #GBinding reference count reaches zero.
1151 g_object_bind_property_with_closures (gpointer source,
1152 const gchar *source_property,
1154 const gchar *target_property,
1155 GBindingFlags flags,
1156 GClosure *transform_to,
1157 GClosure *transform_from)
1159 TransformData *data;
1161 data = g_slice_new0 (TransformData);
1163 if (transform_to != NULL)
1165 if (G_CLOSURE_NEEDS_MARSHAL (transform_to))
1166 g_closure_set_marshal (transform_to, g_cclosure_marshal_BOOLEAN__BOXED_BOXED);
1168 data->transform_to_closure = g_closure_ref (transform_to);
1169 g_closure_sink (data->transform_to_closure);
1172 if (transform_from != NULL)
1174 if (G_CLOSURE_NEEDS_MARSHAL (transform_from))
1175 g_closure_set_marshal (transform_from, g_cclosure_marshal_BOOLEAN__BOXED_BOXED);
1177 data->transform_from_closure = g_closure_ref (transform_from);
1178 g_closure_sink (data->transform_from_closure);
1181 return g_object_bind_property_full (source, source_property,
1182 target, target_property,
1184 transform_to != NULL ? bind_with_closures_transform_to : NULL,
1185 transform_from != NULL ? bind_with_closures_transform_from : NULL,
1187 bind_with_closures_free_func);