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
;
377 /* dispose of the transformation data */
378 if (binding
->notify
!= NULL
)
380 binding
->notify (binding
->transform_data
);
382 binding
->transform_data
= NULL
;
383 binding
->notify
= NULL
;
386 if (binding
->source
!= NULL
)
388 if (binding
->source_notify
!= 0)
389 g_signal_handler_disconnect (binding
->source
, binding
->source_notify
);
391 g_object_weak_unref (binding
->source
, weak_unbind
, binding
);
393 binding
->source_notify
= 0;
394 binding
->source
= NULL
;
397 if (binding
->target
!= NULL
)
399 if (binding
->target_notify
!= 0)
400 g_signal_handler_disconnect (binding
->target
, binding
->target_notify
);
402 if (!source_is_target
)
403 g_object_weak_unref (binding
->target
, weak_unbind
, binding
);
405 binding
->target_notify
= 0;
406 binding
->target
= NULL
;
410 g_object_unref (binding
);
414 g_binding_finalize (GObject
*gobject
)
416 GBinding
*binding
= G_BINDING (gobject
);
418 g_binding_unbind_internal (binding
, FALSE
);
420 G_OBJECT_CLASS (g_binding_parent_class
)->finalize (gobject
);
424 g_binding_set_property (GObject
*gobject
,
429 GBinding
*binding
= G_BINDING (gobject
);
434 binding
->source
= g_value_get_object (value
);
437 case PROP_SOURCE_PROPERTY
:
438 binding
->source_property
= g_intern_string (g_value_get_string (value
));
442 binding
->target
= g_value_get_object (value
);
445 case PROP_TARGET_PROPERTY
:
446 binding
->target_property
= g_intern_string (g_value_get_string (value
));
450 binding
->flags
= g_value_get_flags (value
);
454 G_OBJECT_WARN_INVALID_PROPERTY_ID (gobject
, prop_id
, pspec
);
460 g_binding_get_property (GObject
*gobject
,
465 GBinding
*binding
= G_BINDING (gobject
);
470 g_value_set_object (value
, binding
->source
);
473 case PROP_SOURCE_PROPERTY
:
474 g_value_set_string (value
, binding
->source_property
);
478 g_value_set_object (value
, binding
->target
);
481 case PROP_TARGET_PROPERTY
:
482 g_value_set_string (value
, binding
->target_property
);
486 g_value_set_flags (value
, binding
->flags
);
490 G_OBJECT_WARN_INVALID_PROPERTY_ID (gobject
, prop_id
, pspec
);
496 g_binding_constructed (GObject
*gobject
)
498 GBinding
*binding
= G_BINDING (gobject
);
499 GBindingTransformFunc transform_func
= default_transform
;
500 GQuark source_property_detail
;
501 GClosure
*source_notify_closure
;
503 /* assert that we were constructed correctly */
504 g_assert (binding
->source
!= NULL
);
505 g_assert (binding
->target
!= NULL
);
506 g_assert (binding
->source_property
!= NULL
);
507 g_assert (binding
->target_property
!= NULL
);
509 /* we assume a check was performed prior to construction - since
510 * g_object_bind_property_full() does it; we cannot fail construction
511 * anyway, so it would be hard for use to properly warn here
513 binding
->source_pspec
= g_object_class_find_property (G_OBJECT_GET_CLASS (binding
->source
), binding
->source_property
);
514 binding
->target_pspec
= g_object_class_find_property (G_OBJECT_GET_CLASS (binding
->target
), binding
->target_property
);
515 g_assert (binding
->source_pspec
!= NULL
);
516 g_assert (binding
->target_pspec
!= NULL
);
518 /* switch to the invert boolean transform if needed */
519 if (binding
->flags
& G_BINDING_INVERT_BOOLEAN
)
520 transform_func
= default_invert_boolean_transform
;
522 /* set the default transformation functions here */
523 binding
->transform_s2t
= transform_func
;
524 binding
->transform_t2s
= transform_func
;
526 binding
->transform_data
= NULL
;
527 binding
->notify
= NULL
;
529 source_property_detail
= g_quark_from_string (binding
->source_property
);
530 source_notify_closure
= g_cclosure_new (G_CALLBACK (on_source_notify
),
532 binding
->source_notify
= g_signal_connect_closure_by_id (binding
->source
,
533 gobject_notify_signal_id
,
534 source_property_detail
,
535 source_notify_closure
,
538 g_object_weak_ref (binding
->source
, weak_unbind
, binding
);
540 if (binding
->flags
& G_BINDING_BIDIRECTIONAL
)
542 GQuark target_property_detail
;
543 GClosure
*target_notify_closure
;
545 target_property_detail
= g_quark_from_string (binding
->target_property
);
546 target_notify_closure
= g_cclosure_new (G_CALLBACK (on_target_notify
),
548 binding
->target_notify
= g_signal_connect_closure_by_id (binding
->target
,
549 gobject_notify_signal_id
,
550 target_property_detail
,
551 target_notify_closure
,
555 if (binding
->target
!= binding
->source
)
556 g_object_weak_ref (binding
->target
, weak_unbind
, binding
);
560 g_binding_class_init (GBindingClass
*klass
)
562 GObjectClass
*gobject_class
= G_OBJECT_CLASS (klass
);
564 gobject_notify_signal_id
= g_signal_lookup ("notify", G_TYPE_OBJECT
);
565 g_assert (gobject_notify_signal_id
!= 0);
567 gobject_class
->constructed
= g_binding_constructed
;
568 gobject_class
->set_property
= g_binding_set_property
;
569 gobject_class
->get_property
= g_binding_get_property
;
570 gobject_class
->finalize
= g_binding_finalize
;
575 * The #GObject that should be used as the source of the binding
579 g_object_class_install_property (gobject_class
, PROP_SOURCE
,
580 g_param_spec_object ("source",
582 P_("The source of the binding"),
584 G_PARAM_CONSTRUCT_ONLY
|
586 G_PARAM_STATIC_STRINGS
));
590 * The #GObject that should be used as the target of the binding
594 g_object_class_install_property (gobject_class
, PROP_TARGET
,
595 g_param_spec_object ("target",
597 P_("The target of the binding"),
599 G_PARAM_CONSTRUCT_ONLY
|
601 G_PARAM_STATIC_STRINGS
));
603 * GBinding:source-property:
605 * The name of the property of #GBinding:source that should be used
606 * as the source of the binding
610 g_object_class_install_property (gobject_class
, PROP_SOURCE_PROPERTY
,
611 g_param_spec_string ("source-property",
612 P_("Source Property"),
613 P_("The property on the source to bind"),
615 G_PARAM_CONSTRUCT_ONLY
|
617 G_PARAM_STATIC_STRINGS
));
619 * GBinding:target-property:
621 * The name of the property of #GBinding:target that should be used
622 * as the target of the binding
626 g_object_class_install_property (gobject_class
, PROP_TARGET_PROPERTY
,
627 g_param_spec_string ("target-property",
628 P_("Target Property"),
629 P_("The property on the target to bind"),
631 G_PARAM_CONSTRUCT_ONLY
|
633 G_PARAM_STATIC_STRINGS
));
637 * Flags to be used to control the #GBinding
641 g_object_class_install_property (gobject_class
, PROP_FLAGS
,
642 g_param_spec_flags ("flags",
644 P_("The binding flags"),
645 G_TYPE_BINDING_FLAGS
,
647 G_PARAM_CONSTRUCT_ONLY
|
649 G_PARAM_STATIC_STRINGS
));
653 g_binding_init (GBinding
*binding
)
658 * g_binding_get_flags:
659 * @binding: a #GBinding
661 * Retrieves the flags passed when constructing the #GBinding.
663 * Returns: the #GBindingFlags used by the #GBinding
668 g_binding_get_flags (GBinding
*binding
)
670 g_return_val_if_fail (G_IS_BINDING (binding
), G_BINDING_DEFAULT
);
672 return binding
->flags
;
676 * g_binding_get_source:
677 * @binding: a #GBinding
679 * Retrieves the #GObject instance used as the source of the binding.
681 * Returns: (transfer none): the source #GObject
686 g_binding_get_source (GBinding
*binding
)
688 g_return_val_if_fail (G_IS_BINDING (binding
), NULL
);
690 return binding
->source
;
694 * g_binding_get_target:
695 * @binding: a #GBinding
697 * Retrieves the #GObject instance used as the target of the binding.
699 * Returns: (transfer none): the target #GObject
704 g_binding_get_target (GBinding
*binding
)
706 g_return_val_if_fail (G_IS_BINDING (binding
), NULL
);
708 return binding
->target
;
712 * g_binding_get_source_property:
713 * @binding: a #GBinding
715 * Retrieves the name of the property of #GBinding:source used as the source
718 * Returns: the name of the source property
723 g_binding_get_source_property (GBinding
*binding
)
725 g_return_val_if_fail (G_IS_BINDING (binding
), NULL
);
727 return binding
->source_property
;
731 * g_binding_get_target_property:
732 * @binding: a #GBinding
734 * Retrieves the name of the property of #GBinding:target used as the target
737 * Returns: the name of the target property
742 g_binding_get_target_property (GBinding
*binding
)
744 g_return_val_if_fail (G_IS_BINDING (binding
), NULL
);
746 return binding
->target_property
;
751 * @binding: a #GBinding
753 * Explicitly releases the binding between the source and the target
754 * property expressed by @binding.
756 * This function will release the reference that is being held on
757 * the @binding instance; if you want to hold on to the #GBinding instance
758 * after calling g_binding_unbind(), you will need to hold a reference
764 g_binding_unbind (GBinding
*binding
)
766 g_return_if_fail (G_IS_BINDING (binding
));
768 g_binding_unbind_internal (binding
, TRUE
);
772 * g_object_bind_property_full:
773 * @source: (type GObject.Object): the source #GObject
774 * @source_property: the property on @source to bind
775 * @target: (type GObject.Object): the target #GObject
776 * @target_property: the property on @target to bind
777 * @flags: flags to pass to #GBinding
778 * @transform_to: (scope notified) (nullable): the transformation function
779 * from the @source to the @target, or %NULL to use the default
780 * @transform_from: (scope notified) (nullable): the transformation function
781 * from the @target to the @source, or %NULL to use the default
782 * @user_data: custom data to be passed to the transformation functions,
784 * @notify: (nullable): a function to call when disposing the binding, to free
785 * resources used by the transformation functions, or %NULL if not required
787 * Complete version of g_object_bind_property().
789 * Creates a binding between @source_property on @source and @target_property
790 * on @target, allowing you to set the transformation functions to be used by
793 * If @flags contains %G_BINDING_BIDIRECTIONAL then the binding will be mutual:
794 * if @target_property on @target changes then the @source_property on @source
795 * will be updated as well. The @transform_from function is only used in case
796 * of bidirectional bindings, otherwise it will be ignored
798 * The binding will automatically be removed when either the @source or the
799 * @target instances are finalized. To remove the binding without affecting the
800 * @source and the @target you can just call g_object_unref() on the returned
801 * #GBinding instance.
803 * A #GObject can have multiple bindings.
805 * The same @user_data parameter will be used for both @transform_to
806 * and @transform_from transformation functions; the @notify function will
807 * be called once, when the binding is removed. If you need different data
808 * for each transformation function, please use
809 * g_object_bind_property_with_closures() instead.
811 * Returns: (transfer none): the #GBinding instance representing the
812 * binding between the two #GObject instances. The binding is released
813 * whenever the #GBinding reference count reaches zero.
818 g_object_bind_property_full (gpointer source
,
819 const gchar
*source_property
,
821 const gchar
*target_property
,
823 GBindingTransformFunc transform_to
,
824 GBindingTransformFunc transform_from
,
826 GDestroyNotify notify
)
831 g_return_val_if_fail (G_IS_OBJECT (source
), NULL
);
832 g_return_val_if_fail (source_property
!= NULL
, NULL
);
833 g_return_val_if_fail (G_IS_OBJECT (target
), NULL
);
834 g_return_val_if_fail (target_property
!= NULL
, NULL
);
836 if (source
== target
&& g_strcmp0 (source_property
, target_property
) == 0)
838 g_warning ("Unable to bind the same property on the same instance");
842 /* remove the G_BINDING_INVERT_BOOLEAN flag in case we have
843 * custom transformation functions
845 if ((flags
& G_BINDING_INVERT_BOOLEAN
) &&
846 (transform_to
!= NULL
|| transform_from
!= NULL
))
848 flags
&= ~G_BINDING_INVERT_BOOLEAN
;
851 pspec
= g_object_class_find_property (G_OBJECT_GET_CLASS (source
), source_property
);
854 g_warning ("%s: The source object of type %s has no property called '%s'",
856 G_OBJECT_TYPE_NAME (source
),
861 if (!(pspec
->flags
& G_PARAM_READABLE
))
863 g_warning ("%s: The source object of type %s has no readable property called '%s'",
865 G_OBJECT_TYPE_NAME (source
),
870 if ((flags
& G_BINDING_BIDIRECTIONAL
) &&
871 ((pspec
->flags
& G_PARAM_CONSTRUCT_ONLY
) || !(pspec
->flags
& G_PARAM_WRITABLE
)))
873 g_warning ("%s: The source object of type %s has no writable property called '%s'",
875 G_OBJECT_TYPE_NAME (source
),
880 if ((flags
& G_BINDING_INVERT_BOOLEAN
) &&
881 !(G_PARAM_SPEC_VALUE_TYPE (pspec
) == G_TYPE_BOOLEAN
))
883 g_warning ("%s: The G_BINDING_INVERT_BOOLEAN flag can only be used "
884 "when binding boolean properties; the source property '%s' "
888 g_type_name (G_PARAM_SPEC_VALUE_TYPE (pspec
)));
892 pspec
= g_object_class_find_property (G_OBJECT_GET_CLASS (target
), target_property
);
895 g_warning ("%s: The target object of type %s has no property called '%s'",
897 G_OBJECT_TYPE_NAME (target
),
902 if ((pspec
->flags
& G_PARAM_CONSTRUCT_ONLY
) || !(pspec
->flags
& G_PARAM_WRITABLE
))
904 g_warning ("%s: The target object of type %s has no writable property called '%s'",
906 G_OBJECT_TYPE_NAME (target
),
911 if ((flags
& G_BINDING_BIDIRECTIONAL
) &&
912 !(pspec
->flags
& G_PARAM_READABLE
))
914 g_warning ("%s: The target object of type %s has no readable property called '%s'",
916 G_OBJECT_TYPE_NAME (target
),
921 if ((flags
& G_BINDING_INVERT_BOOLEAN
) &&
922 !(G_PARAM_SPEC_VALUE_TYPE (pspec
) == G_TYPE_BOOLEAN
))
924 g_warning ("%s: The G_BINDING_INVERT_BOOLEAN flag can only be used "
925 "when binding boolean properties; the target property '%s' "
929 g_type_name (G_PARAM_SPEC_VALUE_TYPE (pspec
)));
933 binding
= g_object_new (G_TYPE_BINDING
,
935 "source-property", source_property
,
937 "target-property", target_property
,
941 if (transform_to
!= NULL
)
942 binding
->transform_s2t
= transform_to
;
944 if (transform_from
!= NULL
)
945 binding
->transform_t2s
= transform_from
;
947 binding
->transform_data
= user_data
;
948 binding
->notify
= notify
;
950 /* synchronize the target with the source by faking an emission of
951 * the ::notify signal for the source property; this will also take
952 * care of the bidirectional binding case because the eventual change
953 * will emit a notification on the target
955 if (flags
& G_BINDING_SYNC_CREATE
)
956 on_source_notify (binding
->source
, binding
->source_pspec
, binding
);
962 * g_object_bind_property:
963 * @source: (type GObject.Object): the source #GObject
964 * @source_property: the property on @source to bind
965 * @target: (type GObject.Object): the target #GObject
966 * @target_property: the property on @target to bind
967 * @flags: flags to pass to #GBinding
969 * Creates a binding between @source_property on @source and @target_property
970 * on @target. Whenever the @source_property is changed the @target_property is
971 * updated using the same value. For instance:
974 * g_object_bind_property (action, "active", widget, "sensitive", 0);
977 * Will result in the "sensitive" property of the widget #GObject instance to be
978 * updated with the same value of the "active" property of the action #GObject
981 * If @flags contains %G_BINDING_BIDIRECTIONAL then the binding will be mutual:
982 * if @target_property on @target changes then the @source_property on @source
983 * will be updated as well.
985 * The binding will automatically be removed when either the @source or the
986 * @target instances are finalized. To remove the binding without affecting the
987 * @source and the @target you can just call g_object_unref() on the returned
988 * #GBinding instance.
990 * A #GObject can have multiple bindings.
992 * Returns: (transfer none): the #GBinding instance representing the
993 * binding between the two #GObject instances. The binding is released
994 * whenever the #GBinding reference count reaches zero.
999 g_object_bind_property (gpointer source
,
1000 const gchar
*source_property
,
1002 const gchar
*target_property
,
1003 GBindingFlags flags
)
1005 /* type checking is done in g_object_bind_property_full() */
1007 return g_object_bind_property_full (source
, source_property
,
1008 target
, target_property
,
1015 typedef struct _TransformData
1017 GClosure
*transform_to_closure
;
1018 GClosure
*transform_from_closure
;
1022 bind_with_closures_transform_to (GBinding
*binding
,
1023 const GValue
*source
,
1027 TransformData
*t_data
= data
;
1028 GValue params
[3] = { G_VALUE_INIT
, G_VALUE_INIT
, G_VALUE_INIT
};
1029 GValue retval
= G_VALUE_INIT
;
1032 g_value_init (¶ms
[0], G_TYPE_BINDING
);
1033 g_value_set_object (¶ms
[0], binding
);
1035 g_value_init (¶ms
[1], G_TYPE_VALUE
);
1036 g_value_set_boxed (¶ms
[1], source
);
1038 g_value_init (¶ms
[2], G_TYPE_VALUE
);
1039 g_value_set_boxed (¶ms
[2], target
);
1041 g_value_init (&retval
, G_TYPE_BOOLEAN
);
1042 g_value_set_boolean (&retval
, FALSE
);
1044 g_closure_invoke (t_data
->transform_to_closure
, &retval
, 3, params
, NULL
);
1046 res
= g_value_get_boolean (&retval
);
1049 const GValue
*out_value
= g_value_get_boxed (¶ms
[2]);
1051 g_assert (out_value
!= NULL
);
1053 g_value_copy (out_value
, target
);
1056 g_value_unset (¶ms
[0]);
1057 g_value_unset (¶ms
[1]);
1058 g_value_unset (¶ms
[2]);
1059 g_value_unset (&retval
);
1065 bind_with_closures_transform_from (GBinding
*binding
,
1066 const GValue
*source
,
1070 TransformData
*t_data
= data
;
1071 GValue params
[3] = { G_VALUE_INIT
, G_VALUE_INIT
, G_VALUE_INIT
};
1072 GValue retval
= G_VALUE_INIT
;
1075 g_value_init (¶ms
[0], G_TYPE_BINDING
);
1076 g_value_set_object (¶ms
[0], binding
);
1078 g_value_init (¶ms
[1], G_TYPE_VALUE
);
1079 g_value_set_boxed (¶ms
[1], source
);
1081 g_value_init (¶ms
[2], G_TYPE_VALUE
);
1082 g_value_set_boxed (¶ms
[2], target
);
1084 g_value_init (&retval
, G_TYPE_BOOLEAN
);
1085 g_value_set_boolean (&retval
, FALSE
);
1087 g_closure_invoke (t_data
->transform_from_closure
, &retval
, 3, params
, NULL
);
1089 res
= g_value_get_boolean (&retval
);
1092 const GValue
*out_value
= g_value_get_boxed (¶ms
[2]);
1094 g_assert (out_value
!= NULL
);
1096 g_value_copy (out_value
, target
);
1099 g_value_unset (¶ms
[0]);
1100 g_value_unset (¶ms
[1]);
1101 g_value_unset (¶ms
[2]);
1102 g_value_unset (&retval
);
1108 bind_with_closures_free_func (gpointer data
)
1110 TransformData
*t_data
= data
;
1112 if (t_data
->transform_to_closure
!= NULL
)
1113 g_closure_unref (t_data
->transform_to_closure
);
1115 if (t_data
->transform_from_closure
!= NULL
)
1116 g_closure_unref (t_data
->transform_from_closure
);
1118 g_slice_free (TransformData
, t_data
);
1122 * g_object_bind_property_with_closures: (rename-to g_object_bind_property_full)
1123 * @source: (type GObject.Object): the source #GObject
1124 * @source_property: the property on @source to bind
1125 * @target: (type GObject.Object): the target #GObject
1126 * @target_property: the property on @target to bind
1127 * @flags: flags to pass to #GBinding
1128 * @transform_to: a #GClosure wrapping the transformation function
1129 * from the @source to the @target, or %NULL to use the default
1130 * @transform_from: a #GClosure wrapping the transformation function
1131 * from the @target to the @source, or %NULL to use the default
1133 * Creates a binding between @source_property on @source and @target_property
1134 * on @target, allowing you to set the transformation functions to be used by
1137 * This function is the language bindings friendly version of
1138 * g_object_bind_property_full(), using #GClosures instead of
1139 * function pointers.
1141 * Returns: (transfer none): the #GBinding instance representing the
1142 * binding between the two #GObject instances. The binding is released
1143 * whenever the #GBinding reference count reaches zero.
1148 g_object_bind_property_with_closures (gpointer source
,
1149 const gchar
*source_property
,
1151 const gchar
*target_property
,
1152 GBindingFlags flags
,
1153 GClosure
*transform_to
,
1154 GClosure
*transform_from
)
1156 TransformData
*data
;
1158 data
= g_slice_new0 (TransformData
);
1160 if (transform_to
!= NULL
)
1162 if (G_CLOSURE_NEEDS_MARSHAL (transform_to
))
1163 g_closure_set_marshal (transform_to
, g_cclosure_marshal_BOOLEAN__BOXED_BOXED
);
1165 data
->transform_to_closure
= g_closure_ref (transform_to
);
1166 g_closure_sink (data
->transform_to_closure
);
1169 if (transform_from
!= NULL
)
1171 if (G_CLOSURE_NEEDS_MARSHAL (transform_from
))
1172 g_closure_set_marshal (transform_from
, g_cclosure_marshal_BOOLEAN__BOXED_BOXED
);
1174 data
->transform_from_closure
= g_closure_ref (transform_from
);
1175 g_closure_sink (data
->transform_from_closure
);
1178 return g_object_bind_property_full (source
, source_property
,
1179 target
, target_property
,
1181 transform_to
!= NULL
? bind_with_closures_transform_to
: NULL
,
1182 transform_from
!= NULL
? bind_with_closures_transform_from
: NULL
,
1184 bind_with_closures_free_func
);