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.1 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, see <http://www.gnu.org/licenses/>.
18 * Author: Emmanuele Bassi <ebassi@linux.intel.com>
24 * @Short_Description: Bind two object properties
26 * #GBinding is the representation of a binding between a property on a
27 * #GObject instance (or source) and another property on another #GObject
28 * instance (or target). Whenever the source property changes, the same
29 * value is applied to the target property; for instance, the following
32 * |[<!-- language="C" -->
33 * g_object_bind_property (object1, "property-a",
34 * object2, "property-b",
38 * will cause the property named "property-b" of @object2 to be updated
39 * every time g_object_set() or the specific accessor changes the value of
40 * the property "property-a" of @object1.
42 * It is possible to create a bidirectional binding between two properties
43 * of two #GObject instances, so that if either property changes, the
44 * other is updated as well, for instance:
46 * |[<!-- language="C" -->
47 * g_object_bind_property (object1, "property-a",
48 * object2, "property-b",
49 * G_BINDING_BIDIRECTIONAL);
52 * will keep the two properties in sync.
54 * It is also possible to set a custom transformation function (in both
55 * directions, in case of a bidirectional binding) to apply a custom
56 * transformation from the source value to the target value before
57 * applying it; for instance, the following binding:
59 * |[<!-- language="C" -->
60 * g_object_bind_property_full (adjustment1, "value",
61 * adjustment2, "value",
62 * G_BINDING_BIDIRECTIONAL,
63 * celsius_to_fahrenheit,
64 * fahrenheit_to_celsius,
68 * will keep the "value" property of the two adjustments in sync; the
69 * @celsius_to_fahrenheit function will be called whenever the "value"
70 * property of @adjustment1 changes and will transform the current value
71 * of the property before applying it to the "value" property of @adjustment2.
73 * Vice versa, the @fahrenheit_to_celsius function will be called whenever
74 * the "value" property of @adjustment2 changes, and will transform the
75 * current value of the property before applying it to the "value" property
78 * Note that #GBinding does not resolve cycles by itself; a cycle like
81 * object1:propertyA -> object2:propertyB
82 * object2:propertyB -> object3:propertyC
83 * object3:propertyC -> object1:propertyA
86 * might lead to an infinite loop. The loop, in this particular case,
87 * can be avoided if the objects emit the #GObject::notify signal only
88 * if the value has effectively been changed. A binding is implemented
89 * using the #GObject::notify signal, so it is susceptible to all the
90 * various ways of blocking a signal emission, like g_signal_stop_emission()
91 * or g_signal_handler_block().
93 * A binding will be severed, and the resources it allocates freed, whenever
94 * either one of the #GObject instances it refers to are finalized, or when
95 * the #GBinding instance loses its last reference.
97 * Bindings for languages with garbage collection can use
98 * g_binding_unbind() to explicitly release a binding between the source
99 * and target properties, instead of relying on the last reference on the
100 * binding, source, and target instances to drop.
102 * #GBinding is available since GObject 2.26
109 #include "gbinding.h"
111 #include "gmarshal.h"
114 #include "gparamspecs.h"
115 #include "gvaluetypes.h"
117 #include "glibintl.h"
121 g_binding_flags_get_type (void)
123 static volatile gsize g_define_type_id__volatile
= 0;
125 if (g_once_init_enter (&g_define_type_id__volatile
))
127 static const GFlagsValue values
[] = {
128 { G_BINDING_DEFAULT
, "G_BINDING_DEFAULT", "default" },
129 { G_BINDING_BIDIRECTIONAL
, "G_BINDING_BIDIRECTIONAL", "bidirectional" },
130 { G_BINDING_SYNC_CREATE
, "G_BINDING_SYNC_CREATE", "sync-create" },
131 { G_BINDING_INVERT_BOOLEAN
, "G_BINDING_INVERT_BOOLEAN", "invert-boolean" },
134 GType g_define_type_id
=
135 g_flags_register_static (g_intern_static_string ("GBindingFlags"), values
);
136 g_once_init_leave (&g_define_type_id__volatile
, g_define_type_id
);
139 return g_define_type_id__volatile
;
142 #define G_BINDING_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST ((klass), G_TYPE_BINDING, GBindingClass))
143 #define G_IS_BINDING_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), G_TYPE_BINDING))
144 #define G_BINDING_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), G_TYPE_BINDING, GBindingClass))
146 typedef struct _GBindingClass GBindingClass
;
150 GObject parent_instance
;
152 /* no reference is held on the objects, to avoid cycles */
156 /* the property names are interned, so they should not be freed */
157 const gchar
*source_property
;
158 const gchar
*target_property
;
160 GParamSpec
*source_pspec
;
161 GParamSpec
*target_pspec
;
163 GBindingTransformFunc transform_s2t
;
164 GBindingTransformFunc transform_t2s
;
171 gpointer transform_data
;
172 GDestroyNotify notify
;
174 /* a guard, to avoid loops */
178 struct _GBindingClass
180 GObjectClass parent_class
;
189 PROP_SOURCE_PROPERTY
,
190 PROP_TARGET_PROPERTY
,
194 static guint gobject_notify_signal_id
;
196 G_DEFINE_TYPE (GBinding
, g_binding
, G_TYPE_OBJECT
)
198 /* the basic assumption is that if either the source or the target
199 * goes away then the binding does not exist any more and it should
203 weak_unbind (gpointer user_data
,
204 GObject
*where_the_object_was
)
206 GBinding
*binding
= user_data
;
208 /* if what went away was the source, unset it so that GBinding::finalize
209 * does not try to access it; otherwise, disconnect everything and remove
210 * the GBinding instance from the object's qdata
212 if (binding
->source
== where_the_object_was
)
213 binding
->source
= NULL
;
216 if (binding
->source_notify
!= 0)
217 g_signal_handler_disconnect (binding
->source
, binding
->source_notify
);
219 g_object_weak_unref (binding
->source
, weak_unbind
, user_data
);
221 binding
->source_notify
= 0;
222 binding
->source
= NULL
;
225 /* as above, but with the target */
226 if (binding
->target
== where_the_object_was
)
227 binding
->target
= NULL
;
230 if (binding
->target_notify
!= 0)
231 g_signal_handler_disconnect (binding
->target
, binding
->target_notify
);
233 g_object_weak_unref (binding
->target
, weak_unbind
, user_data
);
235 binding
->target_notify
= 0;
236 binding
->target
= NULL
;
239 /* this will take care of the binding itself */
240 g_object_unref (binding
);
244 default_transform (GBinding
*binding
,
245 const GValue
*value_a
,
247 gpointer user_data G_GNUC_UNUSED
)
249 /* if it's not the same type, try to convert it using the GValue
250 * transformation API; otherwise just copy it
252 if (!g_type_is_a (G_VALUE_TYPE (value_a
), G_VALUE_TYPE (value_b
)))
254 /* are these two types compatible (can be directly copied)? */
255 if (g_value_type_compatible (G_VALUE_TYPE (value_a
),
256 G_VALUE_TYPE (value_b
)))
258 g_value_copy (value_a
, value_b
);
262 if (g_value_type_transformable (G_VALUE_TYPE (value_a
),
263 G_VALUE_TYPE (value_b
)))
265 if (g_value_transform (value_a
, value_b
))
269 g_warning ("%s: Unable to convert a value of type %s to a "
272 g_type_name (G_VALUE_TYPE (value_a
)),
273 g_type_name (G_VALUE_TYPE (value_b
)));
278 g_value_copy (value_a
, value_b
);
283 default_invert_boolean_transform (GBinding
*binding
,
284 const GValue
*value_a
,
286 gpointer user_data G_GNUC_UNUSED
)
290 g_assert (G_VALUE_HOLDS_BOOLEAN (value_a
));
291 g_assert (G_VALUE_HOLDS_BOOLEAN (value_b
));
293 value
= g_value_get_boolean (value_a
);
296 g_value_set_boolean (value_b
, value
);
302 on_source_notify (GObject
*gobject
,
306 GValue from_value
= G_VALUE_INIT
;
307 GValue to_value
= G_VALUE_INIT
;
310 if (binding
->is_frozen
)
313 g_value_init (&from_value
, G_PARAM_SPEC_VALUE_TYPE (binding
->source_pspec
));
314 g_value_init (&to_value
, G_PARAM_SPEC_VALUE_TYPE (binding
->target_pspec
));
316 g_object_get_property (binding
->source
, binding
->source_pspec
->name
, &from_value
);
318 res
= binding
->transform_s2t (binding
,
321 binding
->transform_data
);
324 binding
->is_frozen
= TRUE
;
326 g_param_value_validate (binding
->target_pspec
, &to_value
);
327 g_object_set_property (binding
->target
, binding
->target_pspec
->name
, &to_value
);
329 binding
->is_frozen
= FALSE
;
332 g_value_unset (&from_value
);
333 g_value_unset (&to_value
);
337 on_target_notify (GObject
*gobject
,
341 GValue from_value
= G_VALUE_INIT
;
342 GValue to_value
= G_VALUE_INIT
;
345 if (binding
->is_frozen
)
348 g_value_init (&from_value
, G_PARAM_SPEC_VALUE_TYPE (binding
->target_pspec
));
349 g_value_init (&to_value
, G_PARAM_SPEC_VALUE_TYPE (binding
->source_pspec
));
351 g_object_get_property (binding
->target
, binding
->target_pspec
->name
, &from_value
);
353 res
= binding
->transform_t2s (binding
,
356 binding
->transform_data
);
359 binding
->is_frozen
= TRUE
;
361 g_param_value_validate (binding
->source_pspec
, &to_value
);
362 g_object_set_property (binding
->source
, binding
->source_pspec
->name
, &to_value
);
364 binding
->is_frozen
= FALSE
;
367 g_value_unset (&from_value
);
368 g_value_unset (&to_value
);
372 g_binding_unbind_internal (GBinding
*binding
,
373 gboolean unref_binding
)
375 gboolean source_is_target
= binding
->source
== binding
->target
;
376 gboolean binding_was_removed
= FALSE
;
378 /* dispose of the transformation data */
379 if (binding
->notify
!= NULL
)
381 binding
->notify (binding
->transform_data
);
383 binding
->transform_data
= NULL
;
384 binding
->notify
= NULL
;
387 if (binding
->source
!= NULL
)
389 if (binding
->source_notify
!= 0)
390 g_signal_handler_disconnect (binding
->source
, binding
->source_notify
);
392 g_object_weak_unref (binding
->source
, weak_unbind
, binding
);
394 binding
->source_notify
= 0;
395 binding
->source
= NULL
;
396 binding_was_removed
= TRUE
;
399 if (binding
->target
!= NULL
)
401 if (binding
->target_notify
!= 0)
402 g_signal_handler_disconnect (binding
->target
, binding
->target_notify
);
404 if (!source_is_target
)
405 g_object_weak_unref (binding
->target
, weak_unbind
, binding
);
407 binding
->target_notify
= 0;
408 binding
->target
= NULL
;
409 binding_was_removed
= TRUE
;
412 if (binding_was_removed
&& unref_binding
)
413 g_object_unref (binding
);
417 g_binding_finalize (GObject
*gobject
)
419 GBinding
*binding
= G_BINDING (gobject
);
421 g_binding_unbind_internal (binding
, FALSE
);
423 G_OBJECT_CLASS (g_binding_parent_class
)->finalize (gobject
);
427 g_binding_set_property (GObject
*gobject
,
432 GBinding
*binding
= G_BINDING (gobject
);
437 binding
->source
= g_value_get_object (value
);
440 case PROP_SOURCE_PROPERTY
:
441 binding
->source_property
= g_intern_string (g_value_get_string (value
));
445 binding
->target
= g_value_get_object (value
);
448 case PROP_TARGET_PROPERTY
:
449 binding
->target_property
= g_intern_string (g_value_get_string (value
));
453 binding
->flags
= g_value_get_flags (value
);
457 G_OBJECT_WARN_INVALID_PROPERTY_ID (gobject
, prop_id
, pspec
);
463 g_binding_get_property (GObject
*gobject
,
468 GBinding
*binding
= G_BINDING (gobject
);
473 g_value_set_object (value
, binding
->source
);
476 case PROP_SOURCE_PROPERTY
:
477 g_value_set_string (value
, binding
->source_property
);
481 g_value_set_object (value
, binding
->target
);
484 case PROP_TARGET_PROPERTY
:
485 g_value_set_string (value
, binding
->target_property
);
489 g_value_set_flags (value
, binding
->flags
);
493 G_OBJECT_WARN_INVALID_PROPERTY_ID (gobject
, prop_id
, pspec
);
499 g_binding_constructed (GObject
*gobject
)
501 GBinding
*binding
= G_BINDING (gobject
);
502 GBindingTransformFunc transform_func
= default_transform
;
503 GQuark source_property_detail
;
504 GClosure
*source_notify_closure
;
506 /* assert that we were constructed correctly */
507 g_assert (binding
->source
!= NULL
);
508 g_assert (binding
->target
!= NULL
);
509 g_assert (binding
->source_property
!= NULL
);
510 g_assert (binding
->target_property
!= NULL
);
512 /* we assume a check was performed prior to construction - since
513 * g_object_bind_property_full() does it; we cannot fail construction
514 * anyway, so it would be hard for use to properly warn here
516 binding
->source_pspec
= g_object_class_find_property (G_OBJECT_GET_CLASS (binding
->source
), binding
->source_property
);
517 binding
->target_pspec
= g_object_class_find_property (G_OBJECT_GET_CLASS (binding
->target
), binding
->target_property
);
518 g_assert (binding
->source_pspec
!= NULL
);
519 g_assert (binding
->target_pspec
!= NULL
);
521 /* switch to the invert boolean transform if needed */
522 if (binding
->flags
& G_BINDING_INVERT_BOOLEAN
)
523 transform_func
= default_invert_boolean_transform
;
525 /* set the default transformation functions here */
526 binding
->transform_s2t
= transform_func
;
527 binding
->transform_t2s
= transform_func
;
529 binding
->transform_data
= NULL
;
530 binding
->notify
= NULL
;
532 source_property_detail
= g_quark_from_string (binding
->source_property
);
533 source_notify_closure
= g_cclosure_new (G_CALLBACK (on_source_notify
),
535 binding
->source_notify
= g_signal_connect_closure_by_id (binding
->source
,
536 gobject_notify_signal_id
,
537 source_property_detail
,
538 source_notify_closure
,
541 g_object_weak_ref (binding
->source
, weak_unbind
, binding
);
543 if (binding
->flags
& G_BINDING_BIDIRECTIONAL
)
545 GQuark target_property_detail
;
546 GClosure
*target_notify_closure
;
548 target_property_detail
= g_quark_from_string (binding
->target_property
);
549 target_notify_closure
= g_cclosure_new (G_CALLBACK (on_target_notify
),
551 binding
->target_notify
= g_signal_connect_closure_by_id (binding
->target
,
552 gobject_notify_signal_id
,
553 target_property_detail
,
554 target_notify_closure
,
558 if (binding
->target
!= binding
->source
)
559 g_object_weak_ref (binding
->target
, weak_unbind
, binding
);
563 g_binding_class_init (GBindingClass
*klass
)
565 GObjectClass
*gobject_class
= G_OBJECT_CLASS (klass
);
567 gobject_notify_signal_id
= g_signal_lookup ("notify", G_TYPE_OBJECT
);
568 g_assert (gobject_notify_signal_id
!= 0);
570 gobject_class
->constructed
= g_binding_constructed
;
571 gobject_class
->set_property
= g_binding_set_property
;
572 gobject_class
->get_property
= g_binding_get_property
;
573 gobject_class
->finalize
= g_binding_finalize
;
578 * The #GObject that should be used as the source of the binding
582 g_object_class_install_property (gobject_class
, PROP_SOURCE
,
583 g_param_spec_object ("source",
585 P_("The source of the binding"),
587 G_PARAM_CONSTRUCT_ONLY
|
589 G_PARAM_STATIC_STRINGS
));
593 * The #GObject that should be used as the target of the binding
597 g_object_class_install_property (gobject_class
, PROP_TARGET
,
598 g_param_spec_object ("target",
600 P_("The target of the binding"),
602 G_PARAM_CONSTRUCT_ONLY
|
604 G_PARAM_STATIC_STRINGS
));
606 * GBinding:source-property:
608 * The name of the property of #GBinding:source that should be used
609 * as the source of the binding
613 g_object_class_install_property (gobject_class
, PROP_SOURCE_PROPERTY
,
614 g_param_spec_string ("source-property",
615 P_("Source Property"),
616 P_("The property on the source to bind"),
618 G_PARAM_CONSTRUCT_ONLY
|
620 G_PARAM_STATIC_STRINGS
));
622 * GBinding:target-property:
624 * The name of the property of #GBinding:target that should be used
625 * as the target of the binding
629 g_object_class_install_property (gobject_class
, PROP_TARGET_PROPERTY
,
630 g_param_spec_string ("target-property",
631 P_("Target Property"),
632 P_("The property on the target to bind"),
634 G_PARAM_CONSTRUCT_ONLY
|
636 G_PARAM_STATIC_STRINGS
));
640 * Flags to be used to control the #GBinding
644 g_object_class_install_property (gobject_class
, PROP_FLAGS
,
645 g_param_spec_flags ("flags",
647 P_("The binding flags"),
648 G_TYPE_BINDING_FLAGS
,
650 G_PARAM_CONSTRUCT_ONLY
|
652 G_PARAM_STATIC_STRINGS
));
656 g_binding_init (GBinding
*binding
)
661 * g_binding_get_flags:
662 * @binding: a #GBinding
664 * Retrieves the flags passed when constructing the #GBinding.
666 * Returns: the #GBindingFlags used by the #GBinding
671 g_binding_get_flags (GBinding
*binding
)
673 g_return_val_if_fail (G_IS_BINDING (binding
), G_BINDING_DEFAULT
);
675 return binding
->flags
;
679 * g_binding_get_source:
680 * @binding: a #GBinding
682 * Retrieves the #GObject instance used as the source of the binding.
684 * Returns: (transfer none): the source #GObject
689 g_binding_get_source (GBinding
*binding
)
691 g_return_val_if_fail (G_IS_BINDING (binding
), NULL
);
693 return binding
->source
;
697 * g_binding_get_target:
698 * @binding: a #GBinding
700 * Retrieves the #GObject instance used as the target of the binding.
702 * Returns: (transfer none): the target #GObject
707 g_binding_get_target (GBinding
*binding
)
709 g_return_val_if_fail (G_IS_BINDING (binding
), NULL
);
711 return binding
->target
;
715 * g_binding_get_source_property:
716 * @binding: a #GBinding
718 * Retrieves the name of the property of #GBinding:source used as the source
721 * Returns: the name of the source property
726 g_binding_get_source_property (GBinding
*binding
)
728 g_return_val_if_fail (G_IS_BINDING (binding
), NULL
);
730 return binding
->source_property
;
734 * g_binding_get_target_property:
735 * @binding: a #GBinding
737 * Retrieves the name of the property of #GBinding:target used as the target
740 * Returns: the name of the target property
745 g_binding_get_target_property (GBinding
*binding
)
747 g_return_val_if_fail (G_IS_BINDING (binding
), NULL
);
749 return binding
->target_property
;
754 * @binding: a #GBinding
756 * Explicitly releases the binding between the source and the target
757 * property expressed by @binding.
759 * This function will release the reference that is being held on
760 * the @binding instance; if you want to hold on to the #GBinding instance
761 * after calling g_binding_unbind(), you will need to hold a reference
767 g_binding_unbind (GBinding
*binding
)
769 g_return_if_fail (G_IS_BINDING (binding
));
771 g_binding_unbind_internal (binding
, TRUE
);
775 * g_object_bind_property_full:
776 * @source: (type GObject.Object): the source #GObject
777 * @source_property: the property on @source to bind
778 * @target: (type GObject.Object): the target #GObject
779 * @target_property: the property on @target to bind
780 * @flags: flags to pass to #GBinding
781 * @transform_to: (scope notified) (nullable): the transformation function
782 * from the @source to the @target, or %NULL to use the default
783 * @transform_from: (scope notified) (nullable): the transformation function
784 * from the @target to the @source, or %NULL to use the default
785 * @user_data: custom data to be passed to the transformation functions,
787 * @notify: (nullable): a function to call when disposing the binding, to free
788 * resources used by the transformation functions, or %NULL if not required
790 * Complete version of g_object_bind_property().
792 * Creates a binding between @source_property on @source and @target_property
793 * on @target, allowing you to set the transformation functions to be used by
796 * If @flags contains %G_BINDING_BIDIRECTIONAL then the binding will be mutual:
797 * if @target_property on @target changes then the @source_property on @source
798 * will be updated as well. The @transform_from function is only used in case
799 * of bidirectional bindings, otherwise it will be ignored
801 * The binding will automatically be removed when either the @source or the
802 * @target instances are finalized. To remove the binding without affecting the
803 * @source and the @target you can just call g_object_unref() on the returned
804 * #GBinding instance.
806 * A #GObject can have multiple bindings.
808 * The same @user_data parameter will be used for both @transform_to
809 * and @transform_from transformation functions; the @notify function will
810 * be called once, when the binding is removed. If you need different data
811 * for each transformation function, please use
812 * g_object_bind_property_with_closures() instead.
814 * Returns: (transfer none): the #GBinding instance representing the
815 * binding between the two #GObject instances. The binding is released
816 * whenever the #GBinding reference count reaches zero.
821 g_object_bind_property_full (gpointer source
,
822 const gchar
*source_property
,
824 const gchar
*target_property
,
826 GBindingTransformFunc transform_to
,
827 GBindingTransformFunc transform_from
,
829 GDestroyNotify notify
)
834 g_return_val_if_fail (G_IS_OBJECT (source
), NULL
);
835 g_return_val_if_fail (source_property
!= NULL
, NULL
);
836 g_return_val_if_fail (G_IS_OBJECT (target
), NULL
);
837 g_return_val_if_fail (target_property
!= NULL
, NULL
);
839 if (source
== target
&& g_strcmp0 (source_property
, target_property
) == 0)
841 g_warning ("Unable to bind the same property on the same instance");
845 /* remove the G_BINDING_INVERT_BOOLEAN flag in case we have
846 * custom transformation functions
848 if ((flags
& G_BINDING_INVERT_BOOLEAN
) &&
849 (transform_to
!= NULL
|| transform_from
!= NULL
))
851 flags
&= ~G_BINDING_INVERT_BOOLEAN
;
854 pspec
= g_object_class_find_property (G_OBJECT_GET_CLASS (source
), source_property
);
857 g_warning ("%s: The source object of type %s has no property called '%s'",
859 G_OBJECT_TYPE_NAME (source
),
864 if (!(pspec
->flags
& G_PARAM_READABLE
))
866 g_warning ("%s: The source object of type %s has no readable property called '%s'",
868 G_OBJECT_TYPE_NAME (source
),
873 if ((flags
& G_BINDING_BIDIRECTIONAL
) &&
874 ((pspec
->flags
& G_PARAM_CONSTRUCT_ONLY
) || !(pspec
->flags
& G_PARAM_WRITABLE
)))
876 g_warning ("%s: The source object of type %s has no writable property called '%s'",
878 G_OBJECT_TYPE_NAME (source
),
883 if ((flags
& G_BINDING_INVERT_BOOLEAN
) &&
884 !(G_PARAM_SPEC_VALUE_TYPE (pspec
) == G_TYPE_BOOLEAN
))
886 g_warning ("%s: The G_BINDING_INVERT_BOOLEAN flag can only be used "
887 "when binding boolean properties; the source property '%s' "
891 g_type_name (G_PARAM_SPEC_VALUE_TYPE (pspec
)));
895 pspec
= g_object_class_find_property (G_OBJECT_GET_CLASS (target
), target_property
);
898 g_warning ("%s: The target object of type %s has no property called '%s'",
900 G_OBJECT_TYPE_NAME (target
),
905 if ((pspec
->flags
& G_PARAM_CONSTRUCT_ONLY
) || !(pspec
->flags
& G_PARAM_WRITABLE
))
907 g_warning ("%s: The target object of type %s has no writable property called '%s'",
909 G_OBJECT_TYPE_NAME (target
),
914 if ((flags
& G_BINDING_BIDIRECTIONAL
) &&
915 !(pspec
->flags
& G_PARAM_READABLE
))
917 g_warning ("%s: The target object of type %s has no readable property called '%s'",
919 G_OBJECT_TYPE_NAME (target
),
924 if ((flags
& G_BINDING_INVERT_BOOLEAN
) &&
925 !(G_PARAM_SPEC_VALUE_TYPE (pspec
) == G_TYPE_BOOLEAN
))
927 g_warning ("%s: The G_BINDING_INVERT_BOOLEAN flag can only be used "
928 "when binding boolean properties; the target property '%s' "
932 g_type_name (G_PARAM_SPEC_VALUE_TYPE (pspec
)));
936 binding
= g_object_new (G_TYPE_BINDING
,
938 "source-property", source_property
,
940 "target-property", target_property
,
944 if (transform_to
!= NULL
)
945 binding
->transform_s2t
= transform_to
;
947 if (transform_from
!= NULL
)
948 binding
->transform_t2s
= transform_from
;
950 binding
->transform_data
= user_data
;
951 binding
->notify
= notify
;
953 /* synchronize the target with the source by faking an emission of
954 * the ::notify signal for the source property; this will also take
955 * care of the bidirectional binding case because the eventual change
956 * will emit a notification on the target
958 if (flags
& G_BINDING_SYNC_CREATE
)
959 on_source_notify (binding
->source
, binding
->source_pspec
, binding
);
965 * g_object_bind_property:
966 * @source: (type GObject.Object): the source #GObject
967 * @source_property: the property on @source to bind
968 * @target: (type GObject.Object): the target #GObject
969 * @target_property: the property on @target to bind
970 * @flags: flags to pass to #GBinding
972 * Creates a binding between @source_property on @source and @target_property
973 * on @target. Whenever the @source_property is changed the @target_property is
974 * updated using the same value. For instance:
977 * g_object_bind_property (action, "active", widget, "sensitive", 0);
980 * Will result in the "sensitive" property of the widget #GObject instance to be
981 * updated with the same value of the "active" property of the action #GObject
984 * If @flags contains %G_BINDING_BIDIRECTIONAL then the binding will be mutual:
985 * if @target_property on @target changes then the @source_property on @source
986 * will be updated as well.
988 * The binding will automatically be removed when either the @source or the
989 * @target instances are finalized. To remove the binding without affecting the
990 * @source and the @target you can just call g_object_unref() on the returned
991 * #GBinding instance.
993 * A #GObject can have multiple bindings.
995 * Returns: (transfer none): the #GBinding instance representing the
996 * binding between the two #GObject instances. The binding is released
997 * whenever the #GBinding reference count reaches zero.
1002 g_object_bind_property (gpointer source
,
1003 const gchar
*source_property
,
1005 const gchar
*target_property
,
1006 GBindingFlags flags
)
1008 /* type checking is done in g_object_bind_property_full() */
1010 return g_object_bind_property_full (source
, source_property
,
1011 target
, target_property
,
1018 typedef struct _TransformData
1020 GClosure
*transform_to_closure
;
1021 GClosure
*transform_from_closure
;
1025 bind_with_closures_transform_to (GBinding
*binding
,
1026 const GValue
*source
,
1030 TransformData
*t_data
= data
;
1031 GValue params
[3] = { G_VALUE_INIT
, G_VALUE_INIT
, G_VALUE_INIT
};
1032 GValue retval
= G_VALUE_INIT
;
1035 g_value_init (¶ms
[0], G_TYPE_BINDING
);
1036 g_value_set_object (¶ms
[0], binding
);
1038 g_value_init (¶ms
[1], G_TYPE_VALUE
);
1039 g_value_set_boxed (¶ms
[1], source
);
1041 g_value_init (¶ms
[2], G_TYPE_VALUE
);
1042 g_value_set_boxed (¶ms
[2], target
);
1044 g_value_init (&retval
, G_TYPE_BOOLEAN
);
1045 g_value_set_boolean (&retval
, FALSE
);
1047 g_closure_invoke (t_data
->transform_to_closure
, &retval
, 3, params
, NULL
);
1049 res
= g_value_get_boolean (&retval
);
1052 const GValue
*out_value
= g_value_get_boxed (¶ms
[2]);
1054 g_assert (out_value
!= NULL
);
1056 g_value_copy (out_value
, target
);
1059 g_value_unset (¶ms
[0]);
1060 g_value_unset (¶ms
[1]);
1061 g_value_unset (¶ms
[2]);
1062 g_value_unset (&retval
);
1068 bind_with_closures_transform_from (GBinding
*binding
,
1069 const GValue
*source
,
1073 TransformData
*t_data
= data
;
1074 GValue params
[3] = { G_VALUE_INIT
, G_VALUE_INIT
, G_VALUE_INIT
};
1075 GValue retval
= G_VALUE_INIT
;
1078 g_value_init (¶ms
[0], G_TYPE_BINDING
);
1079 g_value_set_object (¶ms
[0], binding
);
1081 g_value_init (¶ms
[1], G_TYPE_VALUE
);
1082 g_value_set_boxed (¶ms
[1], source
);
1084 g_value_init (¶ms
[2], G_TYPE_VALUE
);
1085 g_value_set_boxed (¶ms
[2], target
);
1087 g_value_init (&retval
, G_TYPE_BOOLEAN
);
1088 g_value_set_boolean (&retval
, FALSE
);
1090 g_closure_invoke (t_data
->transform_from_closure
, &retval
, 3, params
, NULL
);
1092 res
= g_value_get_boolean (&retval
);
1095 const GValue
*out_value
= g_value_get_boxed (¶ms
[2]);
1097 g_assert (out_value
!= NULL
);
1099 g_value_copy (out_value
, target
);
1102 g_value_unset (¶ms
[0]);
1103 g_value_unset (¶ms
[1]);
1104 g_value_unset (¶ms
[2]);
1105 g_value_unset (&retval
);
1111 bind_with_closures_free_func (gpointer data
)
1113 TransformData
*t_data
= data
;
1115 if (t_data
->transform_to_closure
!= NULL
)
1116 g_closure_unref (t_data
->transform_to_closure
);
1118 if (t_data
->transform_from_closure
!= NULL
)
1119 g_closure_unref (t_data
->transform_from_closure
);
1121 g_slice_free (TransformData
, t_data
);
1125 * g_object_bind_property_with_closures: (rename-to g_object_bind_property_full)
1126 * @source: (type GObject.Object): the source #GObject
1127 * @source_property: the property on @source to bind
1128 * @target: (type GObject.Object): the target #GObject
1129 * @target_property: the property on @target to bind
1130 * @flags: flags to pass to #GBinding
1131 * @transform_to: a #GClosure wrapping the transformation function
1132 * from the @source to the @target, or %NULL to use the default
1133 * @transform_from: a #GClosure wrapping the transformation function
1134 * from the @target to the @source, or %NULL to use the default
1136 * Creates a binding between @source_property on @source and @target_property
1137 * on @target, allowing you to set the transformation functions to be used by
1140 * This function is the language bindings friendly version of
1141 * g_object_bind_property_full(), using #GClosures instead of
1142 * function pointers.
1144 * Returns: (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
);