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 * <note><para>Bindings for languages with garbage collection can use
100 * g_binding_unbind() to explicitly release a binding between the source
101 * and target properties, instead of relying on the last reference on the
102 * binding, source, and target instances to drop.</para></note>
104 * #GBinding is available since GObject 2.26
111 #include "gbinding.h"
113 #include "gmarshal.h"
116 #include "gparamspecs.h"
117 #include "gvaluetypes.h"
119 #include "glibintl.h"
123 g_binding_flags_get_type (void)
125 static volatile gsize g_define_type_id__volatile
= 0;
127 if (g_once_init_enter (&g_define_type_id__volatile
))
129 static const GFlagsValue values
[] = {
130 { G_BINDING_DEFAULT
, "G_BINDING_DEFAULT", "default" },
131 { G_BINDING_BIDIRECTIONAL
, "G_BINDING_BIDIRECTIONAL", "bidirectional" },
132 { G_BINDING_SYNC_CREATE
, "G_BINDING_SYNC_CREATE", "sync-create" },
133 { G_BINDING_INVERT_BOOLEAN
, "G_BINDING_INVERT_BOOLEAN", "invert-boolean" },
136 GType g_define_type_id
=
137 g_flags_register_static (g_intern_static_string ("GBindingFlags"), values
);
138 g_once_init_leave (&g_define_type_id__volatile
, g_define_type_id
);
141 return g_define_type_id__volatile
;
144 #define G_BINDING_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST ((klass), G_TYPE_BINDING, GBindingClass))
145 #define G_IS_BINDING_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), G_TYPE_BINDING))
146 #define G_BINDING_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), G_TYPE_BINDING, GBindingClass))
148 typedef struct _GBindingClass GBindingClass
;
152 GObject parent_instance
;
154 /* no reference is held on the objects, to avoid cycles */
158 /* the property names are interned, so they should not be freed */
159 const gchar
*source_property
;
160 const gchar
*target_property
;
162 GParamSpec
*source_pspec
;
163 GParamSpec
*target_pspec
;
165 GBindingTransformFunc transform_s2t
;
166 GBindingTransformFunc transform_t2s
;
173 gpointer transform_data
;
174 GDestroyNotify notify
;
176 /* a guard, to avoid loops */
180 struct _GBindingClass
182 GObjectClass parent_class
;
191 PROP_SOURCE_PROPERTY
,
192 PROP_TARGET_PROPERTY
,
196 static GQuark quark_gbinding
= 0;
198 G_DEFINE_TYPE (GBinding
, g_binding
, G_TYPE_OBJECT
);
201 add_binding_qdata (GObject
*gobject
,
204 GHashTable
*bindings
;
206 bindings
= g_object_get_qdata (gobject
, quark_gbinding
);
207 if (bindings
== NULL
)
209 bindings
= g_hash_table_new (NULL
, NULL
);
211 g_object_set_qdata_full (gobject
, quark_gbinding
,
213 (GDestroyNotify
) g_hash_table_unref
);
216 g_hash_table_add (bindings
, binding
);
220 remove_binding_qdata (GObject
*gobject
,
223 GHashTable
*bindings
;
225 bindings
= g_object_get_qdata (gobject
, quark_gbinding
);
227 g_hash_table_remove (bindings
, binding
);
230 /* the basic assumption is that if either the source or the target
231 * goes away then the binding does not exist any more and it should
235 weak_unbind (gpointer user_data
,
236 GObject
*where_the_object_was
)
238 GBinding
*binding
= user_data
;
240 /* if what went away was the source, unset it so that GBinding::finalize
241 * does not try to access it; otherwise, disconnect everything and remove
242 * the GBinding instance from the object's qdata
244 if (binding
->source
== where_the_object_was
)
245 binding
->source
= NULL
;
248 if (binding
->source_notify
!= 0)
249 g_signal_handler_disconnect (binding
->source
, binding
->source_notify
);
251 g_object_weak_unref (binding
->source
, weak_unbind
, user_data
);
252 remove_binding_qdata (binding
->source
, binding
);
254 binding
->source_notify
= 0;
255 binding
->source
= NULL
;
258 /* as above, but with the target */
259 if (binding
->target
== where_the_object_was
)
260 binding
->target
= NULL
;
263 if (binding
->target_notify
!= 0)
264 g_signal_handler_disconnect (binding
->target
, binding
->target_notify
);
266 g_object_weak_unref (binding
->target
, weak_unbind
, user_data
);
267 remove_binding_qdata (binding
->target
, binding
);
269 binding
->target_notify
= 0;
270 binding
->target
= NULL
;
273 /* this will take care of the binding itself */
274 g_object_unref (binding
);
277 static inline gboolean
278 default_transform (const GValue
*value_a
,
281 /* if it's not the same type, try to convert it using the GValue
282 * transformation API; otherwise just copy it
284 if (!g_type_is_a (G_VALUE_TYPE (value_a
), G_VALUE_TYPE (value_b
)))
286 /* are these two types compatible (can be directly copied)? */
287 if (g_value_type_compatible (G_VALUE_TYPE (value_a
),
288 G_VALUE_TYPE (value_b
)))
290 g_value_copy (value_a
, value_b
);
294 if (g_value_type_transformable (G_VALUE_TYPE (value_a
),
295 G_VALUE_TYPE (value_b
)))
297 if (g_value_transform (value_a
, value_b
))
300 g_warning ("%s: Unable to convert a value of type %s to a "
303 g_type_name (G_VALUE_TYPE (value_a
)),
304 g_type_name (G_VALUE_TYPE (value_b
)));
310 g_value_copy (value_a
, value_b
);
316 static inline gboolean
317 default_invert_boolean_transform (const GValue
*value_a
,
322 g_assert (G_VALUE_HOLDS_BOOLEAN (value_a
));
323 g_assert (G_VALUE_HOLDS_BOOLEAN (value_b
));
325 value
= g_value_get_boolean (value_a
);
328 g_value_set_boolean (value_b
, value
);
334 default_transform_to (GBinding
*binding
,
335 const GValue
*value_a
,
337 gpointer user_data G_GNUC_UNUSED
)
339 if (binding
->flags
& G_BINDING_INVERT_BOOLEAN
)
340 return default_invert_boolean_transform (value_a
, value_b
);
342 return default_transform (value_a
, value_b
);
346 default_transform_from (GBinding
*binding
,
347 const GValue
*value_a
,
349 gpointer user_data G_GNUC_UNUSED
)
351 if (binding
->flags
& G_BINDING_INVERT_BOOLEAN
)
352 return default_invert_boolean_transform (value_a
, value_b
);
354 return default_transform (value_a
, value_b
);
358 on_source_notify (GObject
*gobject
,
363 GValue source_value
= G_VALUE_INIT
;
364 GValue target_value
= G_VALUE_INIT
;
367 if (binding
->is_frozen
)
370 p_name
= g_intern_string (pspec
->name
);
372 if (p_name
!= binding
->source_property
)
375 g_value_init (&source_value
, G_PARAM_SPEC_VALUE_TYPE (binding
->source_pspec
));
376 g_value_init (&target_value
, G_PARAM_SPEC_VALUE_TYPE (binding
->target_pspec
));
378 g_object_get_property (binding
->source
, binding
->source_pspec
->name
, &source_value
);
380 res
= binding
->transform_s2t (binding
,
383 binding
->transform_data
);
386 binding
->is_frozen
= TRUE
;
388 g_param_value_validate (binding
->target_pspec
, &target_value
);
389 g_object_set_property (binding
->target
, binding
->target_pspec
->name
, &target_value
);
391 binding
->is_frozen
= FALSE
;
394 g_value_unset (&source_value
);
395 g_value_unset (&target_value
);
399 on_target_notify (GObject
*gobject
,
404 GValue source_value
= G_VALUE_INIT
;
405 GValue target_value
= G_VALUE_INIT
;
408 if (binding
->is_frozen
)
411 p_name
= g_intern_string (pspec
->name
);
413 if (p_name
!= binding
->target_property
)
416 g_value_init (&source_value
, G_PARAM_SPEC_VALUE_TYPE (binding
->target_pspec
));
417 g_value_init (&target_value
, G_PARAM_SPEC_VALUE_TYPE (binding
->source_pspec
));
419 g_object_get_property (binding
->target
, binding
->target_pspec
->name
, &source_value
);
421 res
= binding
->transform_t2s (binding
,
424 binding
->transform_data
);
427 binding
->is_frozen
= TRUE
;
429 g_param_value_validate (binding
->source_pspec
, &target_value
);
430 g_object_set_property (binding
->source
, binding
->source_pspec
->name
, &target_value
);
432 binding
->is_frozen
= FALSE
;
435 g_value_unset (&source_value
);
436 g_value_unset (&target_value
);
440 g_binding_unbind_internal (GBinding
*binding
,
441 gboolean unref_binding
)
443 /* dispose of the transformation data */
444 if (binding
->notify
!= NULL
)
446 binding
->notify (binding
->transform_data
);
448 binding
->transform_data
= NULL
;
449 binding
->notify
= NULL
;
452 if (binding
->source
!= NULL
)
454 if (binding
->source_notify
!= 0)
455 g_signal_handler_disconnect (binding
->source
, binding
->source_notify
);
457 g_object_weak_unref (binding
->source
, weak_unbind
, binding
);
458 remove_binding_qdata (binding
->source
, binding
);
460 binding
->source_notify
= 0;
461 binding
->source
= NULL
;
464 if (binding
->target
!= NULL
)
466 if (binding
->target_notify
!= 0)
467 g_signal_handler_disconnect (binding
->target
, binding
->target_notify
);
469 g_object_weak_unref (binding
->target
, weak_unbind
, binding
);
470 remove_binding_qdata (binding
->target
, binding
);
472 binding
->target_notify
= 0;
473 binding
->target
= NULL
;
477 g_object_unref (binding
);
481 g_binding_finalize (GObject
*gobject
)
483 GBinding
*binding
= G_BINDING (gobject
);
485 g_binding_unbind_internal (binding
, FALSE
);
487 G_OBJECT_CLASS (g_binding_parent_class
)->finalize (gobject
);
491 g_binding_set_property (GObject
*gobject
,
496 GBinding
*binding
= G_BINDING (gobject
);
501 binding
->source
= g_value_get_object (value
);
504 case PROP_SOURCE_PROPERTY
:
505 binding
->source_property
= g_intern_string (g_value_get_string (value
));
509 binding
->target
= g_value_get_object (value
);
512 case PROP_TARGET_PROPERTY
:
513 binding
->target_property
= g_intern_string (g_value_get_string (value
));
517 binding
->flags
= g_value_get_flags (value
);
521 G_OBJECT_WARN_INVALID_PROPERTY_ID (gobject
, prop_id
, pspec
);
527 g_binding_get_property (GObject
*gobject
,
532 GBinding
*binding
= G_BINDING (gobject
);
537 g_value_set_object (value
, binding
->source
);
540 case PROP_SOURCE_PROPERTY
:
541 g_value_set_string (value
, binding
->source_property
);
545 g_value_set_object (value
, binding
->target
);
548 case PROP_TARGET_PROPERTY
:
549 g_value_set_string (value
, binding
->target_property
);
553 g_value_set_flags (value
, binding
->flags
);
557 G_OBJECT_WARN_INVALID_PROPERTY_ID (gobject
, prop_id
, pspec
);
563 g_binding_constructed (GObject
*gobject
)
565 GBinding
*binding
= G_BINDING (gobject
);
567 /* assert that we were constructed correctly */
568 g_assert (binding
->source
!= NULL
);
569 g_assert (binding
->target
!= NULL
);
570 g_assert (binding
->source_property
!= NULL
);
571 g_assert (binding
->target_property
!= NULL
);
573 /* we assume a check was performed prior to construction - since
574 * g_object_bind_property_full() does it; we cannot fail construction
575 * anyway, so it would be hard for use to properly warn here
577 binding
->source_pspec
= g_object_class_find_property (G_OBJECT_GET_CLASS (binding
->source
), binding
->source_property
);
578 binding
->target_pspec
= g_object_class_find_property (G_OBJECT_GET_CLASS (binding
->target
), binding
->target_property
);
579 g_assert (binding
->source_pspec
!= NULL
);
580 g_assert (binding
->target_pspec
!= NULL
);
582 /* set the default transformation functions here */
583 binding
->transform_s2t
= default_transform_to
;
584 binding
->transform_t2s
= default_transform_from
;
586 binding
->transform_data
= NULL
;
587 binding
->notify
= NULL
;
589 binding
->source_notify
= g_signal_connect (binding
->source
, "notify",
590 G_CALLBACK (on_source_notify
),
593 g_object_weak_ref (binding
->source
, weak_unbind
, binding
);
594 add_binding_qdata (binding
->source
, binding
);
596 if (binding
->flags
& G_BINDING_BIDIRECTIONAL
)
597 binding
->target_notify
= g_signal_connect (binding
->target
, "notify",
598 G_CALLBACK (on_target_notify
),
601 if (binding
->target
!= binding
->source
)
603 g_object_weak_ref (binding
->target
, weak_unbind
, binding
);
604 add_binding_qdata (binding
->target
, binding
);
609 g_binding_class_init (GBindingClass
*klass
)
611 GObjectClass
*gobject_class
= G_OBJECT_CLASS (klass
);
613 quark_gbinding
= g_quark_from_static_string ("g-binding");
615 gobject_class
->constructed
= g_binding_constructed
;
616 gobject_class
->set_property
= g_binding_set_property
;
617 gobject_class
->get_property
= g_binding_get_property
;
618 gobject_class
->finalize
= g_binding_finalize
;
623 * The #GObject that should be used as the source of the binding
627 g_object_class_install_property (gobject_class
, PROP_SOURCE
,
628 g_param_spec_object ("source",
630 P_("The source of the binding"),
632 G_PARAM_CONSTRUCT_ONLY
|
634 G_PARAM_STATIC_STRINGS
));
638 * The #GObject that should be used as the target of the binding
642 g_object_class_install_property (gobject_class
, PROP_TARGET
,
643 g_param_spec_object ("target",
645 P_("The target of the binding"),
647 G_PARAM_CONSTRUCT_ONLY
|
649 G_PARAM_STATIC_STRINGS
));
651 * GBinding:source-property:
653 * The name of the property of #GBinding:source that should be used
654 * as the source of the binding
658 g_object_class_install_property (gobject_class
, PROP_SOURCE_PROPERTY
,
659 g_param_spec_string ("source-property",
660 P_("Source Property"),
661 P_("The property on the source to bind"),
663 G_PARAM_CONSTRUCT_ONLY
|
665 G_PARAM_STATIC_STRINGS
));
667 * GBinding:target-property:
669 * The name of the property of #GBinding:target that should be used
670 * as the target of the binding
674 g_object_class_install_property (gobject_class
, PROP_TARGET_PROPERTY
,
675 g_param_spec_string ("target-property",
676 P_("Target Property"),
677 P_("The property on the target to bind"),
679 G_PARAM_CONSTRUCT_ONLY
|
681 G_PARAM_STATIC_STRINGS
));
685 * Flags to be used to control the #GBinding
689 g_object_class_install_property (gobject_class
, PROP_FLAGS
,
690 g_param_spec_flags ("flags",
692 P_("The binding flags"),
693 G_TYPE_BINDING_FLAGS
,
695 G_PARAM_CONSTRUCT_ONLY
|
697 G_PARAM_STATIC_STRINGS
));
701 g_binding_init (GBinding
*binding
)
706 * g_binding_get_flags:
707 * @binding: a #GBinding
709 * Retrieves the flags passed when constructing the #GBinding
711 * Return value: the #GBindingFlags used by the #GBinding
716 g_binding_get_flags (GBinding
*binding
)
718 g_return_val_if_fail (G_IS_BINDING (binding
), G_BINDING_DEFAULT
);
720 return binding
->flags
;
724 * g_binding_get_source:
725 * @binding: a #GBinding
727 * Retrieves the #GObject instance used as the source of the binding
729 * Return value: (transfer none): the source #GObject
734 g_binding_get_source (GBinding
*binding
)
736 g_return_val_if_fail (G_IS_BINDING (binding
), NULL
);
738 return binding
->source
;
742 * g_binding_get_target:
743 * @binding: a #GBinding
745 * Retrieves the #GObject instance used as the target of the binding
747 * Return value: (transfer none): the target #GObject
752 g_binding_get_target (GBinding
*binding
)
754 g_return_val_if_fail (G_IS_BINDING (binding
), NULL
);
756 return binding
->target
;
760 * g_binding_get_source_property:
761 * @binding: a #GBinding
763 * Retrieves the name of the property of #GBinding:source used as the source
766 * Return value: the name of the source property
771 g_binding_get_source_property (GBinding
*binding
)
773 g_return_val_if_fail (G_IS_BINDING (binding
), NULL
);
775 return binding
->source_property
;
779 * g_binding_get_target_property:
780 * @binding: a #GBinding
782 * Retrieves the name of the property of #GBinding:target used as the target
785 * Return value: the name of the target property
790 g_binding_get_target_property (GBinding
*binding
)
792 g_return_val_if_fail (G_IS_BINDING (binding
), NULL
);
794 return binding
->target_property
;
799 * @binding: a #GBinding
801 * Explicitly releases the binding between the source and the target
802 * property expressed by @binding.
804 * <note>This function will release the reference that is being held on
805 * the @binding instance; if you want to hold on to the #GBinding instance
806 * after calling g_binding_unbind(), you will need to hold a reference
812 g_binding_unbind (GBinding
*binding
)
814 g_return_if_fail (G_IS_BINDING (binding
));
816 g_binding_unbind_internal (binding
, TRUE
);
820 * g_object_bind_property_full:
821 * @source: (type GObject.Object): the source #GObject
822 * @source_property: the property on @source to bind
823 * @target: (type GObject.Object): the target #GObject
824 * @target_property: the property on @target to bind
825 * @flags: flags to pass to #GBinding
826 * @transform_to: (scope notified) (allow-none): the transformation function
827 * from the @source to the @target, or %NULL to use the default
828 * @transform_from: (scope notified) (allow-none): the transformation function
829 * from the @target to the @source, or %NULL to use the default
830 * @user_data: custom data to be passed to the transformation functions,
832 * @notify: function to be called when disposing the binding, to free the
833 * resources used by the transformation functions
835 * Complete version of g_object_bind_property().
837 * Creates a binding between @source_property on @source and @target_property
838 * on @target, allowing you to set the transformation functions to be used by
841 * If @flags contains %G_BINDING_BIDIRECTIONAL then the binding will be mutual:
842 * if @target_property on @target changes then the @source_property on @source
843 * will be updated as well. The @transform_from function is only used in case
844 * of bidirectional bindings, otherwise it will be ignored
846 * The binding will automatically be removed when either the @source or the
847 * @target instances are finalized. To remove the binding without affecting the
848 * @source and the @target you can just call g_object_unref() on the returned
849 * #GBinding instance.
851 * A #GObject can have multiple bindings.
853 * <note>The same @user_data parameter will be used for both @transform_to
854 * and @transform_from transformation functions; the @notify function will
855 * be called once, when the binding is removed. If you need different data
856 * for each transformation function, please use
857 * g_object_bind_property_with_closures() instead.</note>
859 * Return value: (transfer none): the #GBinding instance representing the
860 * binding between the two #GObject instances. The binding is released
861 * whenever the #GBinding reference count reaches zero.
866 g_object_bind_property_full (gpointer source
,
867 const gchar
*source_property
,
869 const gchar
*target_property
,
871 GBindingTransformFunc transform_to
,
872 GBindingTransformFunc transform_from
,
874 GDestroyNotify notify
)
879 g_return_val_if_fail (G_IS_OBJECT (source
), NULL
);
880 g_return_val_if_fail (source_property
!= NULL
, NULL
);
881 g_return_val_if_fail (G_IS_OBJECT (target
), NULL
);
882 g_return_val_if_fail (target_property
!= NULL
, NULL
);
884 if (source
== target
&& g_strcmp0 (source_property
, target_property
) == 0)
886 g_warning ("Unable to bind the same property on the same instance");
890 /* remove the G_BINDING_INVERT_BOOLEAN flag in case we have
891 * custom transformation functions
893 if ((flags
& G_BINDING_INVERT_BOOLEAN
) &&
894 (transform_to
!= NULL
|| transform_from
!= NULL
))
896 flags
&= ~G_BINDING_INVERT_BOOLEAN
;
899 pspec
= g_object_class_find_property (G_OBJECT_GET_CLASS (source
), source_property
);
902 g_warning ("%s: The source object of type %s has no property called '%s'",
904 G_OBJECT_TYPE_NAME (source
),
909 if (!(pspec
->flags
& G_PARAM_READABLE
))
911 g_warning ("%s: The source object of type %s has no readable property called '%s'",
913 G_OBJECT_TYPE_NAME (source
),
918 if ((flags
& G_BINDING_BIDIRECTIONAL
) &&
919 ((pspec
->flags
& G_PARAM_CONSTRUCT_ONLY
) || !(pspec
->flags
& G_PARAM_WRITABLE
)))
921 g_warning ("%s: The source object of type %s has no writable property called '%s'",
923 G_OBJECT_TYPE_NAME (source
),
928 if ((flags
& G_BINDING_INVERT_BOOLEAN
) &&
929 !(G_PARAM_SPEC_VALUE_TYPE (pspec
) == G_TYPE_BOOLEAN
))
931 g_warning ("%s: The G_BINDING_INVERT_BOOLEAN flag can only be used "
932 "when binding boolean properties; the source property '%s' "
936 g_type_name (G_PARAM_SPEC_VALUE_TYPE (pspec
)));
940 pspec
= g_object_class_find_property (G_OBJECT_GET_CLASS (target
), target_property
);
943 g_warning ("%s: The target object of type %s has no property called '%s'",
945 G_OBJECT_TYPE_NAME (target
),
950 if ((pspec
->flags
& G_PARAM_CONSTRUCT_ONLY
) || !(pspec
->flags
& G_PARAM_WRITABLE
))
952 g_warning ("%s: The target object of type %s has no writable property called '%s'",
954 G_OBJECT_TYPE_NAME (target
),
959 if ((flags
& G_BINDING_BIDIRECTIONAL
) &&
960 !(pspec
->flags
& G_PARAM_READABLE
))
962 g_warning ("%s: The target object of type %s has no readable property called '%s'",
964 G_OBJECT_TYPE_NAME (target
),
969 if ((flags
& G_BINDING_INVERT_BOOLEAN
) &&
970 !(G_PARAM_SPEC_VALUE_TYPE (pspec
) == G_TYPE_BOOLEAN
))
972 g_warning ("%s: The G_BINDING_INVERT_BOOLEAN flag can only be used "
973 "when binding boolean properties; the target property '%s' "
977 g_type_name (G_PARAM_SPEC_VALUE_TYPE (pspec
)));
981 binding
= g_object_new (G_TYPE_BINDING
,
983 "source-property", source_property
,
985 "target-property", target_property
,
989 if (transform_to
!= NULL
)
990 binding
->transform_s2t
= transform_to
;
992 if (transform_from
!= NULL
)
993 binding
->transform_t2s
= transform_from
;
995 binding
->transform_data
= user_data
;
996 binding
->notify
= notify
;
998 /* synchronize the target with the source by faking an emission of
999 * the ::notify signal for the source property; this will also take
1000 * care of the bidirectional binding case because the eventual change
1001 * will emit a notification on the target
1003 if (flags
& G_BINDING_SYNC_CREATE
)
1004 on_source_notify (binding
->source
, binding
->source_pspec
, binding
);
1010 * g_object_bind_property:
1011 * @source: (type GObject.Object): the source #GObject
1012 * @source_property: the property on @source to bind
1013 * @target: (type GObject.Object): the target #GObject
1014 * @target_property: the property on @target to bind
1015 * @flags: flags to pass to #GBinding
1017 * Creates a binding between @source_property on @source and @target_property
1018 * on @target. Whenever the @source_property is changed the @target_property is
1019 * updated using the same value. For instance:
1022 * g_object_bind_property (action, "active", widget, "sensitive", 0);
1025 * Will result in the "sensitive" property of the widget #GObject instance to be
1026 * updated with the same value of the "active" property of the action #GObject
1029 * If @flags contains %G_BINDING_BIDIRECTIONAL then the binding will be mutual:
1030 * if @target_property on @target changes then the @source_property on @source
1031 * will be updated as well.
1033 * The binding will automatically be removed when either the @source or the
1034 * @target instances are finalized. To remove the binding without affecting the
1035 * @source and the @target you can just call g_object_unref() on the returned
1036 * #GBinding instance.
1038 * A #GObject can have multiple bindings.
1040 * Return value: (transfer none): the #GBinding instance representing the
1041 * binding between the two #GObject instances. The binding is released
1042 * whenever the #GBinding reference count reaches zero.
1047 g_object_bind_property (gpointer source
,
1048 const gchar
*source_property
,
1050 const gchar
*target_property
,
1051 GBindingFlags flags
)
1053 /* type checking is done in g_object_bind_property_full() */
1055 return g_object_bind_property_full (source
, source_property
,
1056 target
, target_property
,
1063 typedef struct _TransformData
1065 GClosure
*transform_to_closure
;
1066 GClosure
*transform_from_closure
;
1070 bind_with_closures_transform_to (GBinding
*binding
,
1071 const GValue
*source
,
1075 TransformData
*t_data
= data
;
1076 GValue params
[3] = { G_VALUE_INIT
, G_VALUE_INIT
, G_VALUE_INIT
};
1077 GValue retval
= G_VALUE_INIT
;
1080 g_value_init (¶ms
[0], G_TYPE_BINDING
);
1081 g_value_set_object (¶ms
[0], binding
);
1083 g_value_init (¶ms
[1], G_TYPE_VALUE
);
1084 g_value_set_boxed (¶ms
[1], source
);
1086 g_value_init (¶ms
[2], G_TYPE_VALUE
);
1087 g_value_set_boxed (¶ms
[2], target
);
1089 g_value_init (&retval
, G_TYPE_BOOLEAN
);
1090 g_value_set_boolean (&retval
, FALSE
);
1092 g_closure_invoke (t_data
->transform_to_closure
, &retval
, 3, params
, NULL
);
1094 res
= g_value_get_boolean (&retval
);
1097 const GValue
*out_value
= g_value_get_boxed (¶ms
[2]);
1099 g_assert (out_value
!= NULL
);
1101 g_value_copy (out_value
, target
);
1104 g_value_unset (¶ms
[0]);
1105 g_value_unset (¶ms
[1]);
1106 g_value_unset (¶ms
[2]);
1107 g_value_unset (&retval
);
1113 bind_with_closures_transform_from (GBinding
*binding
,
1114 const GValue
*source
,
1118 TransformData
*t_data
= data
;
1119 GValue params
[3] = { G_VALUE_INIT
, G_VALUE_INIT
, G_VALUE_INIT
};
1120 GValue retval
= G_VALUE_INIT
;
1123 g_value_init (¶ms
[0], G_TYPE_BINDING
);
1124 g_value_set_object (¶ms
[0], binding
);
1126 g_value_init (¶ms
[1], G_TYPE_VALUE
);
1127 g_value_set_boxed (¶ms
[1], source
);
1129 g_value_init (¶ms
[2], G_TYPE_VALUE
);
1130 g_value_set_boxed (¶ms
[2], target
);
1132 g_value_init (&retval
, G_TYPE_BOOLEAN
);
1133 g_value_set_boolean (&retval
, FALSE
);
1135 g_closure_invoke (t_data
->transform_from_closure
, &retval
, 3, params
, NULL
);
1137 res
= g_value_get_boolean (&retval
);
1140 const GValue
*out_value
= g_value_get_boxed (¶ms
[2]);
1142 g_assert (out_value
!= NULL
);
1144 g_value_copy (out_value
, target
);
1147 g_value_unset (¶ms
[0]);
1148 g_value_unset (¶ms
[1]);
1149 g_value_unset (¶ms
[2]);
1150 g_value_unset (&retval
);
1156 bind_with_closures_free_func (gpointer data
)
1158 TransformData
*t_data
= data
;
1160 if (t_data
->transform_to_closure
!= NULL
)
1161 g_closure_unref (t_data
->transform_to_closure
);
1163 if (t_data
->transform_from_closure
!= NULL
)
1164 g_closure_unref (t_data
->transform_from_closure
);
1166 g_slice_free (TransformData
, t_data
);
1170 * g_object_bind_property_with_closures:
1171 * @source: (type GObject.Object): the source #GObject
1172 * @source_property: the property on @source to bind
1173 * @target: (type GObject.Object): the target #GObject
1174 * @target_property: the property on @target to bind
1175 * @flags: flags to pass to #GBinding
1176 * @transform_to: a #GClosure wrapping the transformation function
1177 * from the @source to the @target, or %NULL to use the default
1178 * @transform_from: a #GClosure wrapping the transformation function
1179 * from the @target to the @source, or %NULL to use the default
1181 * Creates a binding between @source_property on @source and @target_property
1182 * on @target, allowing you to set the transformation functions to be used by
1185 * This function is the language bindings friendly version of
1186 * g_object_bind_property_full(), using #GClosure<!-- -->s instead of
1187 * function pointers.
1189 * Rename to: g_object_bind_property_full
1191 * Return value: (transfer none): the #GBinding instance representing the
1192 * binding between the two #GObject instances. The binding is released
1193 * whenever the #GBinding reference count reaches zero.
1198 g_object_bind_property_with_closures (gpointer source
,
1199 const gchar
*source_property
,
1201 const gchar
*target_property
,
1202 GBindingFlags flags
,
1203 GClosure
*transform_to
,
1204 GClosure
*transform_from
)
1206 TransformData
*data
;
1208 data
= g_slice_new0 (TransformData
);
1210 if (transform_to
!= NULL
)
1212 if (G_CLOSURE_NEEDS_MARSHAL (transform_to
))
1213 g_closure_set_marshal (transform_to
, g_cclosure_marshal_BOOLEAN__BOXED_BOXED
);
1215 data
->transform_to_closure
= g_closure_ref (transform_to
);
1216 g_closure_sink (data
->transform_to_closure
);
1219 if (transform_from
!= NULL
)
1221 if (G_CLOSURE_NEEDS_MARSHAL (transform_from
))
1222 g_closure_set_marshal (transform_from
, g_cclosure_marshal_BOOLEAN__BOXED_BOXED
);
1224 data
->transform_from_closure
= g_closure_ref (transform_from
);
1225 g_closure_sink (data
->transform_from_closure
);
1228 return g_object_bind_property_full (source
, source_property
,
1229 target
, target_property
,
1231 transform_to
!= NULL
? bind_with_closures_transform_to
: NULL
,
1232 transform_from
!= NULL
? bind_with_closures_transform_from
: NULL
,
1234 bind_with_closures_free_func
);