gobject/gbinding.c

   1 /* gbinding.c: Binding for object properties
   2  *
   3  * Copyright (C) 2010  Intel Corp.
   4  *
   5  * SPDX-License-Identifier: LGPL-2.1-or-later
   6  *
   7  * This library is free software; you can redistribute it and/or
   8  * modify it under the terms of the GNU Lesser General Public
   9  * License as published by the Free Software Foundation; either
  10  * version 2.1 of the License, or (at your option) any later version.
  11  *
  12  * This library is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15  * Lesser General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU Lesser General
  18  * Public License along with this library; if not, see <http://www.gnu.org/licenses/>.
  19  *
  20  * Author: Emmanuele Bassi <ebassi@linux.intel.com>
  21  */
  22
  23 /**
  24  * SECTION:gbinding
  25  * @Title: GBinding
  26  * @Short_Description: Bind two object properties
  27  *
  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).
  31  *
  32  * Whenever the source property changes, the same value is applied to the
  33  * target property; for instance, the following binding:
  34  *
  35  * |[<!-- language="C" -->
  36  *   g_object_bind_property (object1, "property-a",
  37  *                           object2, "property-b",
  38  *                           G_BINDING_DEFAULT);
  39  * ]|
  40  *
  41  * will cause the property named "property-b" of @object2 to be updated
  42  * every time g_object_set() or the specific accessor changes the value of
  43  * the property "property-a" of @object1.
  44  *
  45  * It is possible to create a bidirectional binding between two properties
  46  * of two #GObject instances, so that if either property changes, the
  47  * other is updated as well, for instance:
  48  *
  49  * |[<!-- language="C" -->
  50  *   g_object_bind_property (object1, "property-a",
  51  *                           object2, "property-b",
  52  *                           G_BINDING_BIDIRECTIONAL);
  53  * ]|
  54  *
  55  * will keep the two properties in sync.
  56  *
  57  * It is also possible to set a custom transformation function (in both
  58  * directions, in case of a bidirectional binding) to apply a custom
  59  * transformation from the source value to the target value before
  60  * applying it; for instance, the following binding:
  61  *
  62  * |[<!-- language="C" -->
  63  *   g_object_bind_property_full (adjustment1, "value",
  64  *                                adjustment2, "value",
  65  *                                G_BINDING_BIDIRECTIONAL,
  66  *                                celsius_to_fahrenheit,
  67  *                                fahrenheit_to_celsius,
  68  *                                NULL, NULL);
  69  * ]|
  70  *
  71  * will keep the "value" property of the two adjustments in sync; the
  72  * @celsius_to_fahrenheit function will be called whenever the "value"
  73  * property of @adjustment1 changes and will transform the current value
  74  * of the property before applying it to the "value" property of @adjustment2.
  75  *
  76  * Vice versa, the @fahrenheit_to_celsius function will be called whenever
  77  * the "value" property of @adjustment2 changes, and will transform the
  78  * current value of the property before applying it to the "value" property
  79  * of @adjustment1.
  80  *
  81  * Note that #GBinding does not resolve cycles by itself; a cycle like
  82  *
  83  * |[
  84  *   object1:propertyA -> object2:propertyB
  85  *   object2:propertyB -> object3:propertyC
  86  *   object3:propertyC -> object1:propertyA
  87  * ]|
  88  *
  89  * might lead to an infinite loop. The loop, in this particular case,
  90  * can be avoided if the objects emit the #GObject::notify signal only
  91  * if the value has effectively been changed. A binding is implemented
  92  * using the #GObject::notify signal, so it is susceptible to all the
  93  * various ways of blocking a signal emission, like g_signal_stop_emission()
  94  * or g_signal_handler_block().
  95  *
  96  * A binding will be severed, and the resources it allocates freed, whenever
  97  * either one of the #GObject instances it refers to are finalized, or when
  98  * the #GBinding instance loses its last reference.
  99  *
 100  * Bindings for languages with garbage collection can use
 101  * g_binding_unbind() to explicitly release a binding between the source
 102  * and target properties, instead of relying on the last reference on the
 103  * binding, source, and target instances to drop.
 104  *
 105  * #GBinding is available since GObject 2.26
 106  */
 107
 108 #include "config.h"
 109
 110 #include <string.h>
 111
 112 #include "gbinding.h"
 113 #include "genums.h"
 114 #include "gmarshal.h"
 115 #include "gobject.h"
 116 #include "gsignal.h"
 117 #include "gparamspecs.h"
 118 #include "gvaluetypes.h"
 119
 120 #include "glibintl.h"
 121
 122
 123 GType
 124 g_binding_flags_get_type (void)
 125 {
 126   static gsize static_g_define_type_id = 0;
 127
 128   if (g_once_init_enter (&static_g_define_type_id))
 129     {
 130       static const GFlagsValue values[] = {
 131         { G_BINDING_DEFAULT, "G_BINDING_DEFAULT", "default" },
 132         { G_BINDING_BIDIRECTIONAL, "G_BINDING_BIDIRECTIONAL", "bidirectional" },
 133         { G_BINDING_SYNC_CREATE, "G_BINDING_SYNC_CREATE", "sync-create" },
 134         { G_BINDING_INVERT_BOOLEAN, "G_BINDING_INVERT_BOOLEAN", "invert-boolean" },
 135         { 0, NULL, NULL }
 136       };
 137       GType g_define_type_id =
 138         g_flags_register_static (g_intern_static_string ("GBindingFlags"), values);
 139       g_once_init_leave (&static_g_define_type_id, g_define_type_id);
 140     }
 141
 142   return static_g_define_type_id;
 143 }
 144
 145 /* Reference counted helper struct that is passed to all callbacks to ensure
 146  * that they never work with already freed objects without having to store
 147  * strong references for them.
 148  *
 149  * Using strong references anywhere is not possible because of the API
 150  * requirements of GBinding, specifically that the initial reference of the
 151  * GBinding is owned by the source/target and the caller and can be released
 152  * either by the source/target being finalized or calling g_binding_unbind().
 153  *
 154  * As such, the only strong reference has to be owned by both weak notifies of
 155  * the source and target and the first to be called has to release it.
 156  */
 157 typedef struct {
 158   GWeakRef binding;
 159   GWeakRef source;
 160   GWeakRef target;
 161   gboolean binding_removed;
 162 } BindingContext;
 163
 164 static BindingContext *
 165 binding_context_ref (BindingContext *context)
 166 {
 167   return g_atomic_rc_box_acquire (context);
 168 }
 169
 170 static void
 171 binding_context_clear (BindingContext *context)
 172 {
 173   g_weak_ref_clear (&context->binding);
 174   g_weak_ref_clear (&context->source);
 175   g_weak_ref_clear (&context->target);
 176 }
 177
 178 static void
 179 binding_context_unref (BindingContext *context)
 180 {
 181   g_atomic_rc_box_release_full (context, (GDestroyNotify) binding_context_clear);
 182 }
 183
 184 /* Reference counting for the transform functions to ensure that they're always
 185  * valid while making use of them in the property notify callbacks.
 186  *
 187  * The transform functions are released when unbinding but unbinding can happen
 188  * while the transform functions are currently in use inside the notify callbacks.
 189  */
 190 typedef struct {
 191   GBindingTransformFunc transform_s2t;
 192   GBindingTransformFunc transform_t2s;
 193
 194   gpointer transform_data;
 195   GDestroyNotify destroy_notify;
 196 } TransformFunc;
 197
 198 static TransformFunc *
 199 transform_func_new (GBindingTransformFunc transform_s2t,
 200                     GBindingTransformFunc transform_t2s,
 201                     gpointer              transform_data,
 202                     GDestroyNotify        destroy_notify)
 203 {
 204   TransformFunc *func = g_atomic_rc_box_new0 (TransformFunc);
 205
 206   func->transform_s2t = transform_s2t;
 207   func->transform_t2s = transform_t2s;
 208   func->transform_data = transform_data;
 209   func->destroy_notify = destroy_notify;
 210
 211   return func;
 212 }
 213
 214 static TransformFunc *
 215 transform_func_ref (TransformFunc *func)
 216 {
 217   return g_atomic_rc_box_acquire (func);
 218 }
 219
 220 static void
 221 transform_func_clear (TransformFunc *func)
 222 {
 223   if (func->destroy_notify)
 224     func->destroy_notify (func->transform_data);
 225 }
 226
 227 static void
 228 transform_func_unref (TransformFunc *func)
 229 {
 230   g_atomic_rc_box_release_full (func, (GDestroyNotify) transform_func_clear);
 231 }
 232
 233 #define G_BINDING_CLASS(klass)          (G_TYPE_CHECK_CLASS_CAST ((klass), G_TYPE_BINDING, GBindingClass))
 234 #define G_IS_BINDING_CLASS(klass)       (G_TYPE_CHECK_CLASS_TYPE ((klass), G_TYPE_BINDING))
 235 #define G_BINDING_GET_CLASS(obj)        (G_TYPE_INSTANCE_GET_CLASS ((obj), G_TYPE_BINDING, GBindingClass))
 236
 237 typedef struct _GBindingClass           GBindingClass;
 238
 239 struct _GBinding
 240 {
 241   GObject parent_instance;
 242
 243   /* no reference is held on the objects, to avoid cycles */
 244   BindingContext *context;
 245
 246   /* protects transform_func, source, target property notify and
 247    * target_weak_notify_installed for unbinding */
 248   GMutex unbind_lock;
 249
 250   /* transform functions, only NULL after unbinding */
 251   TransformFunc *transform_func; /* LOCK: unbind_lock */
 252
 253   /* the property names are interned, so they should not be freed */
 254   const gchar *source_property;
 255   const gchar *target_property;
 256
 257   GParamSpec *source_pspec;
 258   GParamSpec *target_pspec;
 259
 260   GBindingFlags flags;
 261
 262   guint source_notify; /* LOCK: unbind_lock */
 263   guint target_notify; /* LOCK: unbind_lock */
 264   gboolean target_weak_notify_installed; /* LOCK: unbind_lock */
 265
 266   /* a guard, to avoid loops */
 267   guint is_frozen : 1;
 268 };
 269
 270 struct _GBindingClass
 271 {
 272   GObjectClass parent_class;
 273 };
 274
 275 enum
 276 {
 277   PROP_0,
 278
 279   PROP_SOURCE,
 280   PROP_TARGET,
 281   PROP_SOURCE_PROPERTY,
 282   PROP_TARGET_PROPERTY,
 283   PROP_FLAGS
 284 };
 285
 286 static guint gobject_notify_signal_id;
 287
 288 G_DEFINE_TYPE (GBinding, g_binding, G_TYPE_OBJECT)
 289
 290 static void weak_unbind (gpointer user_data, GObject *where_the_object_was);
 291
 292 /* Must be called with the unbind lock held, context/binding != NULL and strong
 293  * references to source/target or NULL.
 294  * Return TRUE if the binding was actually removed and FALSE if it was already
 295  * removed before. */
 296 static gboolean
 297 unbind_internal_locked (BindingContext *context, GBinding *binding, GObject *source, GObject *target)
 298 {
 299   gboolean binding_was_removed = FALSE;
 300
 301   g_assert (context != NULL);
 302   g_assert (binding != NULL);
 303
 304   /* If the target went away we still have a strong reference to the source
 305    * here and can clear it from the binding. Otherwise if the source went away
 306    * we can clear the target from the binding. Finalizing an object clears its
 307    * signal handlers and all weak references pointing to it before calling
 308    * weak notify callbacks.
 309    *
 310    * If both still exist we clean up everything set up by the binding.
 311    */
 312   if (source)
 313     {
 314       /* We always add/remove the source property notify and the weak notify
 315        * of the source at the same time, and should only ever do that once. */
 316       if (binding->source_notify != 0)
 317         {
 318           g_signal_handler_disconnect (source, binding->source_notify);
 319
 320           g_object_weak_unref (source, weak_unbind, context);
 321           binding_context_unref (context);
 322
 323           binding->source_notify = 0;
 324         }
 325       g_weak_ref_set (&context->source, NULL);
 326     }
 327
 328   /* As above, but with the target. If source==target then no weak notify was
 329    * installed for the target, which is why that is stored as a separate
 330    * boolean inside the binding. */
 331   if (target)
 332     {
 333       /* There might be a target property notify without a weak notify on the
 334        * target or the other way around, so these have to be handled
 335        * independently here unlike for the source. */
 336       if (binding->target_notify != 0)
 337         {
 338           g_signal_handler_disconnect (target, binding->target_notify);
 339
 340           binding->target_notify = 0;
 341         }
 342       g_weak_ref_set (&context->target, NULL);
 343
 344       /* Remove the weak notify from the target, at most once */
 345       if (binding->target_weak_notify_installed)
 346         {
 347           g_object_weak_unref (target, weak_unbind, context);
 348           binding_context_unref (context);
 349           binding->target_weak_notify_installed = FALSE;
 350         }
 351     }
 352
 353   /* Make sure to remove the binding only once and return to the caller that
 354    * this was the call that actually removed it. */
 355   if (!context->binding_removed)
 356     {
 357       context->binding_removed = TRUE;
 358       binding_was_removed = TRUE;
 359     }
 360
 361   return binding_was_removed;
 362 }
 363
 364 /* the basic assumption is that if either the source or the target
 365  * goes away then the binding does not exist any more and it should
 366  * be reaped as well. Each weak notify owns a strong reference to the
 367  * binding that should be dropped here. */
 368 static void
 369 weak_unbind (gpointer  user_data,
 370              GObject  *where_the_object_was)
 371 {
 372   BindingContext *context = user_data;
 373   GBinding *binding;
 374   GObject *source, *target;
 375   gboolean binding_was_removed = FALSE;
 376   TransformFunc *transform_func;
 377
 378   binding = g_weak_ref_get (&context->binding);
 379   if (!binding)
 380     {
 381       /* The binding was already destroyed before so there's nothing to do */
 382       binding_context_unref (context);
 383       return;
 384     }
 385
 386   g_mutex_lock (&binding->unbind_lock);
 387
 388   transform_func = g_steal_pointer (&binding->transform_func);
 389
 390   source = g_weak_ref_get (&context->source);
 391   target = g_weak_ref_get (&context->target);
 392
 393   /* If this is called then either the source or target or both must be in the
 394    * process of being disposed. If this happens as part of g_object_unref()
 395    * then the weak references are actually cleared, otherwise if disposing
 396    * happens as part of g_object_run_dispose() then they would still point to
 397    * the disposed object.
 398    *
 399    * If the object this is being called for is either the source or the target
 400    * and we actually got a strong reference to it nonetheless (see above),
 401    * then signal handlers and weak notifies for it are already disconnected
 402    * and they must not be disconnected a second time. Instead simply clear the
 403    * weak reference and be done with it.
 404    *
 405    * See https://gitlab.gnome.org/GNOME/glib/-/issues/2266 */
 406
 407   if (source == where_the_object_was)
 408     {
 409       g_weak_ref_set (&context->source, NULL);
 410       g_clear_object (&source);
 411     }
 412
 413   if (target == where_the_object_was)
 414     {
 415       g_weak_ref_set (&context->target, NULL);
 416       g_clear_object (&target);
 417     }
 418
 419   binding_was_removed = unbind_internal_locked (context, binding, source, target);
 420
 421   g_mutex_unlock (&binding->unbind_lock);
 422
 423   /* Unref source, target and transform_func after the mutex is unlocked as it
 424    * might release the last reference, which then accesses the mutex again */
 425   g_clear_object (&target);
 426   g_clear_object (&source);
 427
 428   g_clear_pointer (&transform_func, transform_func_unref);
 429
 430   /* This releases the strong reference we got from the weak ref above */
 431   g_object_unref (binding);
 432
 433   /* This will take care of the binding itself. */
 434   if (binding_was_removed)
 435     g_object_unref (binding);
 436
 437   /* Each weak notify owns a reference to the binding context. */
 438   binding_context_unref (context);
 439 }
 440
 441 static gboolean
 442 default_transform (GBinding     *binding,
 443                    const GValue *value_a,
 444                    GValue       *value_b,
 445                    gpointer      user_data G_GNUC_UNUSED)
 446 {
 447   /* if it's not the same type, try to convert it using the GValue
 448    * transformation API; otherwise just copy it
 449    */
 450   if (!g_type_is_a (G_VALUE_TYPE (value_a), G_VALUE_TYPE (value_b)))
 451     {
 452       /* are these two types compatible (can be directly copied)? */
 453       if (g_value_type_compatible (G_VALUE_TYPE (value_a),
 454                                    G_VALUE_TYPE (value_b)))
 455         {
 456           g_value_copy (value_a, value_b);
 457           return TRUE;
 458         }
 459
 460       if (g_value_type_transformable (G_VALUE_TYPE (value_a),
 461                                       G_VALUE_TYPE (value_b)))
 462         {
 463           if (g_value_transform (value_a, value_b))
 464             return TRUE;
 465         }
 466
 467       g_critical ("%s: Unable to convert a value of type %s to a "
 468                   "value of type %s",
 469                   G_STRLOC,
 470                   g_type_name (G_VALUE_TYPE (value_a)),
 471                   g_type_name (G_VALUE_TYPE (value_b)));
 472
 473       return FALSE;
 474     }
 475
 476   g_value_copy (value_a, value_b);
 477   return TRUE;
 478 }
 479
 480 static gboolean
 481 default_invert_boolean_transform (GBinding     *binding,
 482                                   const GValue *value_a,
 483                                   GValue       *value_b,
 484                                   gpointer      user_data G_GNUC_UNUSED)
 485 {
 486   gboolean value;
 487
 488   g_assert (G_VALUE_HOLDS_BOOLEAN (value_a));
 489   g_assert (G_VALUE_HOLDS_BOOLEAN (value_b));
 490
 491   value = g_value_get_boolean (value_a);
 492   value = !value;
 493
 494   g_value_set_boolean (value_b, value);
 495
 496   return TRUE;
 497 }
 498
 499 static void
 500 on_source_notify (GObject          *source,
 501                   GParamSpec       *pspec,
 502                   BindingContext   *context)
 503 {
 504   GBinding *binding;
 505   GObject *target;
 506   TransformFunc *transform_func;
 507   GValue from_value = G_VALUE_INIT;
 508   GValue to_value = G_VALUE_INIT;
 509   gboolean res;
 510
 511   binding = g_weak_ref_get (&context->binding);
 512   if (!binding)
 513     return;
 514
 515   if (binding->is_frozen)
 516     {
 517       g_object_unref (binding);
 518       return;
 519     }
 520
 521   target = g_weak_ref_get (&context->target);
 522   if (!target)
 523     {
 524       g_object_unref (binding);
 525       return;
 526     }
 527
 528   /* Get the transform function safely */
 529   g_mutex_lock (&binding->unbind_lock);
 530   if (!binding->transform_func)
 531     {
 532       /* it was released already during unbinding, nothing to do here */
 533       g_mutex_unlock (&binding->unbind_lock);
 534       return;
 535     }
 536   transform_func = transform_func_ref (binding->transform_func);
 537   g_mutex_unlock (&binding->unbind_lock);
 538
 539   g_value_init (&from_value, G_PARAM_SPEC_VALUE_TYPE (binding->source_pspec));
 540   g_value_init (&to_value, G_PARAM_SPEC_VALUE_TYPE (binding->target_pspec));
 541
 542   g_object_get_property (source, binding->source_pspec->name, &from_value);
 543
 544   res = transform_func->transform_s2t (binding,
 545                                        &from_value,
 546                                        &to_value,
 547                                        transform_func->transform_data);
 548
 549   transform_func_unref (transform_func);
 550
 551   if (res)
 552     {
 553       binding->is_frozen = TRUE;
 554
 555       (void) g_param_value_validate (binding->target_pspec, &to_value);
 556       g_object_set_property (target, binding->target_pspec->name, &to_value);
 557
 558       binding->is_frozen = FALSE;
 559     }
 560
 561   g_value_unset (&from_value);
 562   g_value_unset (&to_value);
 563
 564   g_object_unref (target);
 565   g_object_unref (binding);
 566 }
 567
 568 static void
 569 on_target_notify (GObject          *target,
 570                   GParamSpec       *pspec,
 571                   BindingContext   *context)
 572 {
 573   GBinding *binding;
 574   GObject *source;
 575   TransformFunc *transform_func;
 576   GValue from_value = G_VALUE_INIT;
 577   GValue to_value = G_VALUE_INIT;
 578   gboolean res;
 579
 580   binding = g_weak_ref_get (&context->binding);
 581   if (!binding)
 582     return;
 583
 584   if (binding->is_frozen)
 585     {
 586       g_object_unref (binding);
 587       return;
 588     }
 589
 590   source = g_weak_ref_get (&context->source);
 591   if (!source)
 592     {
 593       g_object_unref (binding);
 594       return;
 595     }
 596
 597   /* Get the transform function safely */
 598   g_mutex_lock (&binding->unbind_lock);
 599   if (!binding->transform_func)
 600     {
 601       /* it was released already during unbinding, nothing to do here */
 602       g_mutex_unlock (&binding->unbind_lock);
 603       return;
 604     }
 605   transform_func = transform_func_ref (binding->transform_func);
 606   g_mutex_unlock (&binding->unbind_lock);
 607
 608   g_value_init (&from_value, G_PARAM_SPEC_VALUE_TYPE (binding->target_pspec));
 609   g_value_init (&to_value, G_PARAM_SPEC_VALUE_TYPE (binding->source_pspec));
 610
 611   g_object_get_property (target, binding->target_pspec->name, &from_value);
 612
 613   res = transform_func->transform_t2s (binding,
 614                                        &from_value,
 615                                        &to_value,
 616                                        transform_func->transform_data);
 617   transform_func_unref (transform_func);
 618
 619   if (res)
 620     {
 621       binding->is_frozen = TRUE;
 622
 623       (void) g_param_value_validate (binding->source_pspec, &to_value);
 624       g_object_set_property (source, binding->source_pspec->name, &to_value);
 625
 626       binding->is_frozen = FALSE;
 627     }
 628
 629   g_value_unset (&from_value);
 630   g_value_unset (&to_value);
 631
 632   g_object_unref (source);
 633   g_object_unref (binding);
 634 }
 635
 636 static inline void
 637 g_binding_unbind_internal (GBinding *binding,
 638                            gboolean  unref_binding)
 639 {
 640   BindingContext *context = binding->context;
 641   GObject *source, *target;
 642   gboolean binding_was_removed = FALSE;
 643   TransformFunc *transform_func;
 644
 645   g_mutex_lock (&binding->unbind_lock);
 646
 647   transform_func = g_steal_pointer (&binding->transform_func);
 648
 649   source = g_weak_ref_get (&context->source);
 650   target = g_weak_ref_get (&context->target);
 651
 652   binding_was_removed = unbind_internal_locked (context, binding, source, target);
 653
 654   g_mutex_unlock (&binding->unbind_lock);
 655
 656   /* Unref source, target and transform_func after the mutex is unlocked as it
 657    * might release the last reference, which then accesses the mutex again */
 658   g_clear_object (&target);
 659   g_clear_object (&source);
 660
 661   g_clear_pointer (&transform_func, transform_func_unref);
 662
 663   if (binding_was_removed && unref_binding)
 664     g_object_unref (binding);
 665 }
 666
 667 static void
 668 g_binding_finalize (GObject *gobject)
 669 {
 670   GBinding *binding = G_BINDING (gobject);
 671
 672   g_binding_unbind_internal (binding, FALSE);
 673
 674   binding_context_unref (binding->context);
 675
 676   g_mutex_clear (&binding->unbind_lock);
 677
 678   G_OBJECT_CLASS (g_binding_parent_class)->finalize (gobject);
 679 }
 680
 681 /* @key must have already been validated with is_valid()
 682  * Modifies @key in place. */
 683 static void
 684 canonicalize_key (gchar *key)
 685 {
 686   gchar *p;
 687
 688   for (p = key; *p != 0; p++)
 689     {
 690       gchar c = *p;
 691
 692       if (c == '_')
 693         *p = '-';
 694     }
 695 }
 696
 697 /* @key must have already been validated with is_valid() */
 698 static gboolean
 699 is_canonical (const gchar *key)
 700 {
 701   return (strchr (key, '_') == NULL);
 702 }
 703
 704 static void
 705 g_binding_set_property (GObject      *gobject,
 706                         guint         prop_id,
 707                         const GValue *value,
 708                         GParamSpec   *pspec)
 709 {
 710   GBinding *binding = G_BINDING (gobject);
 711
 712   switch (prop_id)
 713     {
 714     case PROP_SOURCE:
 715       g_weak_ref_set (&binding->context->source, g_value_get_object (value));
 716       break;
 717
 718     case PROP_TARGET:
 719       g_weak_ref_set (&binding->context->target, g_value_get_object (value));
 720       break;
 721
 722     case PROP_SOURCE_PROPERTY:
 723     case PROP_TARGET_PROPERTY:
 724       {
 725         gchar *name_copy = NULL;
 726         const gchar *name = g_value_get_string (value);
 727         const gchar **dest;
 728
 729         /* Ensure the name we intern is canonical. */
 730         if (!is_canonical (name))
 731           {
 732             name_copy = g_value_dup_string (value);
 733             canonicalize_key (name_copy);
 734             name = name_copy;
 735           }
 736
 737         if (prop_id == PROP_SOURCE_PROPERTY)
 738           dest = &binding->source_property;
 739         else
 740           dest = &binding->target_property;
 741
 742         *dest = g_intern_string (name);
 743
 744         g_free (name_copy);
 745         break;
 746       }
 747
 748     case PROP_FLAGS:
 749       binding->flags = g_value_get_flags (value);
 750       break;
 751
 752     default:
 753       G_OBJECT_WARN_INVALID_PROPERTY_ID (gobject, prop_id, pspec);
 754       break;
 755     }
 756 }
 757
 758 static void
 759 g_binding_get_property (GObject    *gobject,
 760                         guint       prop_id,
 761                         GValue     *value,
 762                         GParamSpec *pspec)
 763 {
 764   GBinding *binding = G_BINDING (gobject);
 765
 766   switch (prop_id)
 767     {
 768     case PROP_SOURCE:
 769       g_value_take_object (value, g_weak_ref_get (&binding->context->source));
 770       break;
 771
 772     case PROP_SOURCE_PROPERTY:
 773       /* @source_property is interned, so we don’t need to take a copy */
 774       g_value_set_interned_string (value, binding->source_property);
 775       break;
 776
 777     case PROP_TARGET:
 778       g_value_take_object (value, g_weak_ref_get (&binding->context->target));
 779       break;
 780
 781     case PROP_TARGET_PROPERTY:
 782       /* @target_property is interned, so we don’t need to take a copy */
 783       g_value_set_interned_string (value, binding->target_property);
 784       break;
 785
 786     case PROP_FLAGS:
 787       g_value_set_flags (value, binding->flags);
 788       break;
 789
 790     default:
 791       G_OBJECT_WARN_INVALID_PROPERTY_ID (gobject, prop_id, pspec);
 792       break;
 793     }
 794 }
 795
 796 static void
 797 g_binding_constructed (GObject *gobject)
 798 {
 799   GBinding *binding = G_BINDING (gobject);
 800   GBindingTransformFunc transform_func = default_transform;
 801   GObject *source, *target;
 802   GQuark source_property_detail;
 803   GClosure *source_notify_closure;
 804
 805   /* assert that we were constructed correctly */
 806   source = g_weak_ref_get (&binding->context->source);
 807   target = g_weak_ref_get (&binding->context->target);
 808   g_assert (source != NULL);
 809   g_assert (target != NULL);
 810   g_assert (binding->source_property != NULL);
 811   g_assert (binding->target_property != NULL);
 812
 813   /* we assume a check was performed prior to construction - since
 814    * g_object_bind_property_full() does it; we cannot fail construction
 815    * anyway, so it would be hard for use to properly warn here
 816    */
 817   binding->source_pspec = g_object_class_find_property (G_OBJECT_GET_CLASS (source), binding->source_property);
 818   binding->target_pspec = g_object_class_find_property (G_OBJECT_GET_CLASS (target), binding->target_property);
 819   g_assert (binding->source_pspec != NULL);
 820   g_assert (binding->target_pspec != NULL);
 821
 822   /* switch to the invert boolean transform if needed */
 823   if (binding->flags & G_BINDING_INVERT_BOOLEAN)
 824     transform_func = default_invert_boolean_transform;
 825
 826   /* set the default transformation functions here */
 827   binding->transform_func = transform_func_new (transform_func, transform_func, NULL, NULL);
 828
 829   source_property_detail = g_quark_from_string (binding->source_property);
 830   source_notify_closure = g_cclosure_new (G_CALLBACK (on_source_notify),
 831                                           binding_context_ref (binding->context),
 832                                           (GClosureNotify) binding_context_unref);
 833   binding->source_notify = g_signal_connect_closure_by_id (source,
 834                                                            gobject_notify_signal_id,
 835                                                            source_property_detail,
 836                                                            source_notify_closure,
 837                                                            FALSE);
 838
 839   g_object_weak_ref (source, weak_unbind, binding_context_ref (binding->context));
 840
 841   if (binding->flags & G_BINDING_BIDIRECTIONAL)
 842     {
 843       GQuark target_property_detail;
 844       GClosure *target_notify_closure;
 845
 846       target_property_detail = g_quark_from_string (binding->target_property);
 847       target_notify_closure = g_cclosure_new (G_CALLBACK (on_target_notify),
 848                                               binding_context_ref (binding->context),
 849                                               (GClosureNotify) binding_context_unref);
 850       binding->target_notify = g_signal_connect_closure_by_id (target,
 851                                                                gobject_notify_signal_id,
 852                                                                target_property_detail,
 853                                                                target_notify_closure,
 854                                                                FALSE);
 855     }
 856
 857   if (target != source)
 858     {
 859       g_object_weak_ref (target, weak_unbind, binding_context_ref (binding->context));
 860
 861       /* Need to remember separately if a target weak notify was installed as
 862        * unlike for the source it can exist independently of the property
 863        * notification callback */
 864       binding->target_weak_notify_installed = TRUE;
 865     }
 866
 867   g_object_unref (source);
 868   g_object_unref (target);
 869 }
 870
 871 static void
 872 g_binding_class_init (GBindingClass *klass)
 873 {
 874   GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
 875
 876   gobject_notify_signal_id = g_signal_lookup ("notify", G_TYPE_OBJECT);
 877   g_assert (gobject_notify_signal_id != 0);
 878
 879   gobject_class->constructed = g_binding_constructed;
 880   gobject_class->set_property = g_binding_set_property;
 881   gobject_class->get_property = g_binding_get_property;
 882   gobject_class->finalize = g_binding_finalize;
 883
 884   /**
 885    * GBinding:source:
 886    *
 887    * The #GObject that should be used as the source of the binding
 888    *
 889    * Since: 2.26
 890    */
 891   g_object_class_install_property (gobject_class, PROP_SOURCE,
 892                                    g_param_spec_object ("source",
 893                                                         P_("Source"),
 894                                                         P_("The source of the binding"),
 895                                                         G_TYPE_OBJECT,
 896                                                         G_PARAM_CONSTRUCT_ONLY |
 897                                                         G_PARAM_READWRITE |
 898                                                         G_PARAM_STATIC_STRINGS));
 899   /**
 900    * GBinding:target:
 901    *
 902    * The #GObject that should be used as the target of the binding
 903    *
 904    * Since: 2.26
 905    */
 906   g_object_class_install_property (gobject_class, PROP_TARGET,
 907                                    g_param_spec_object ("target",
 908                                                         P_("Target"),
 909                                                         P_("The target of the binding"),
 910                                                         G_TYPE_OBJECT,
 911                                                         G_PARAM_CONSTRUCT_ONLY |
 912                                                         G_PARAM_READWRITE |
 913                                                         G_PARAM_STATIC_STRINGS));
 914   /**
 915    * GBinding:source-property:
 916    *
 917    * The name of the property of #GBinding:source that should be used
 918    * as the source of the binding.
 919    *
 920    * This should be in [canonical form][canonical-parameter-names] to get the
 921    * best performance.
 922    *
 923    * Since: 2.26
 924    */
 925   g_object_class_install_property (gobject_class, PROP_SOURCE_PROPERTY,
 926                                    g_param_spec_string ("source-property",
 927                                                         P_("Source Property"),
 928                                                         P_("The property on the source to bind"),
 929                                                         NULL,
 930                                                         G_PARAM_CONSTRUCT_ONLY |
 931                                                         G_PARAM_READWRITE |
 932                                                         G_PARAM_STATIC_STRINGS));
 933   /**
 934    * GBinding:target-property:
 935    *
 936    * The name of the property of #GBinding:target that should be used
 937    * as the target of the binding.
 938    *
 939    * This should be in [canonical form][canonical-parameter-names] to get the
 940    * best performance.
 941    *
 942    * Since: 2.26
 943    */
 944   g_object_class_install_property (gobject_class, PROP_TARGET_PROPERTY,
 945                                    g_param_spec_string ("target-property",
 946                                                         P_("Target Property"),
 947                                                         P_("The property on the target to bind"),
 948                                                         NULL,
 949                                                         G_PARAM_CONSTRUCT_ONLY |
 950                                                         G_PARAM_READWRITE |
 951                                                         G_PARAM_STATIC_STRINGS));
 952   /**
 953    * GBinding:flags:
 954    *
 955    * Flags to be used to control the #GBinding
 956    *
 957    * Since: 2.26
 958    */
 959   g_object_class_install_property (gobject_class, PROP_FLAGS,
 960                                    g_param_spec_flags ("flags",
 961                                                        P_("Flags"),
 962                                                        P_("The binding flags"),
 963                                                        G_TYPE_BINDING_FLAGS,
 964                                                        G_BINDING_DEFAULT,
 965                                                        G_PARAM_CONSTRUCT_ONLY |
 966                                                        G_PARAM_READWRITE |
 967                                                        G_PARAM_STATIC_STRINGS));
 968 }
 969
 970 static void
 971 g_binding_init (GBinding *binding)
 972 {
 973   g_mutex_init (&binding->unbind_lock);
 974
 975   binding->context = g_atomic_rc_box_new0 (BindingContext);
 976   g_weak_ref_init (&binding->context->binding, binding);
 977   g_weak_ref_init (&binding->context->source, NULL);
 978   g_weak_ref_init (&binding->context->target, NULL);
 979 }
 980
 981 /**
 982  * g_binding_get_flags:
 983  * @binding: a #GBinding
 984  *
 985  * Retrieves the flags passed when constructing the #GBinding.
 986  *
 987  * Returns: the #GBindingFlags used by the #GBinding
 988  *
 989  * Since: 2.26
 990  */
 991 GBindingFlags
 992 g_binding_get_flags (GBinding *binding)
 993 {
 994   g_return_val_if_fail (G_IS_BINDING (binding), G_BINDING_DEFAULT);
 995
 996   return binding->flags;
 997 }
 998
 999 /**
1000  * g_binding_get_source:
1001  * @binding: a #GBinding
1002  *
1003  * Retrieves the #GObject instance used as the source of the binding.
1004  *
1005  * A #GBinding can outlive the source #GObject as the binding does not hold a
1006  * strong reference to the source. If the source is destroyed before the
1007  * binding then this function will return %NULL.
1008  *
1009  * Use g_binding_dup_source() if the source or binding are used from different
1010  * threads as otherwise the pointer returned from this function might become
1011  * invalid if the source is finalized from another thread in the meantime.
1012  *
1013  * Returns: (transfer none) (nullable): the source #GObject, or %NULL if the
1014  *     source does not exist any more.
1015  *
1016  * Deprecated: 2.68: Use g_binding_dup_source() for a safer version of this
1017  * function.
1018  *
1019  * Since: 2.26
1020  */
1021 GObject *
1022 g_binding_get_source (GBinding *binding)
1023 {
1024   GObject *source;
1025
1026   g_return_val_if_fail (G_IS_BINDING (binding), NULL);
1027
1028   source = g_weak_ref_get (&binding->context->source);
1029   /* Unref here, this API is not thread-safe
1030    * FIXME: Remove this API when we next break API */
1031   if (source)
1032     g_object_unref (source);
1033
1034   return source;
1035 }
1036
1037 /**
1038  * g_binding_dup_source:
1039  * @binding: a #GBinding
1040  *
1041  * Retrieves the #GObject instance used as the source of the binding.
1042  *
1043  * A #GBinding can outlive the source #GObject as the binding does not hold a
1044  * strong reference to the source. If the source is destroyed before the
1045  * binding then this function will return %NULL.
1046  *
1047  * Returns: (transfer full) (nullable): the source #GObject, or %NULL if the
1048  *     source does not exist any more.
1049  *
1050  * Since: 2.68
1051  */
1052 GObject *
1053 g_binding_dup_source (GBinding *binding)
1054 {
1055   g_return_val_if_fail (G_IS_BINDING (binding), NULL);
1056
1057   return g_weak_ref_get (&binding->context->source);
1058 }
1059
1060 /**
1061  * g_binding_get_target:
1062  * @binding: a #GBinding
1063  *
1064  * Retrieves the #GObject instance used as the target of the binding.
1065  *
1066  * A #GBinding can outlive the target #GObject as the binding does not hold a
1067  * strong reference to the target. If the target is destroyed before the
1068  * binding then this function will return %NULL.
1069  *
1070  * Use g_binding_dup_target() if the target or binding are used from different
1071  * threads as otherwise the pointer returned from this function might become
1072  * invalid if the target is finalized from another thread in the meantime.
1073  *
1074  * Returns: (transfer none) (nullable): the target #GObject, or %NULL if the
1075  *     target does not exist any more.
1076  *
1077  * Deprecated: 2.68: Use g_binding_dup_target() for a safer version of this
1078  * function.
1079  *
1080  * Since: 2.26
1081  */
1082 GObject *
1083 g_binding_get_target (GBinding *binding)
1084 {
1085   GObject *target;
1086
1087   g_return_val_if_fail (G_IS_BINDING (binding), NULL);
1088
1089   target = g_weak_ref_get (&binding->context->target);
1090   /* Unref here, this API is not thread-safe
1091    * FIXME: Remove this API when we next break API */
1092   if (target)
1093     g_object_unref (target);
1094
1095   return target;
1096 }
1097
1098 /**
1099  * g_binding_dup_target:
1100  * @binding: a #GBinding
1101  *
1102  * Retrieves the #GObject instance used as the target of the binding.
1103  *
1104  * A #GBinding can outlive the target #GObject as the binding does not hold a
1105  * strong reference to the target. If the target is destroyed before the
1106  * binding then this function will return %NULL.
1107  *
1108  * Returns: (transfer full) (nullable): the target #GObject, or %NULL if the
1109  *     target does not exist any more.
1110  *
1111  * Since: 2.68
1112  */
1113 GObject *
1114 g_binding_dup_target (GBinding *binding)
1115 {
1116   g_return_val_if_fail (G_IS_BINDING (binding), NULL);
1117
1118   return g_weak_ref_get (&binding->context->target);
1119 }
1120
1121 /**
1122  * g_binding_get_source_property:
1123  * @binding: a #GBinding
1124  *
1125  * Retrieves the name of the property of #GBinding:source used as the source
1126  * of the binding.
1127  *
1128  * Returns: the name of the source property
1129  *
1130  * Since: 2.26
1131  */
1132 const gchar *
1133 g_binding_get_source_property (GBinding *binding)
1134 {
1135   g_return_val_if_fail (G_IS_BINDING (binding), NULL);
1136
1137   return binding->source_property;
1138 }
1139
1140 /**
1141  * g_binding_get_target_property:
1142  * @binding: a #GBinding
1143  *
1144  * Retrieves the name of the property of #GBinding:target used as the target
1145  * of the binding.
1146  *
1147  * Returns: the name of the target property
1148  *
1149  * Since: 2.26
1150  */
1151 const gchar *
1152 g_binding_get_target_property (GBinding *binding)
1153 {
1154   g_return_val_if_fail (G_IS_BINDING (binding), NULL);
1155
1156   return binding->target_property;
1157 }
1158
1159 /**
1160  * g_binding_unbind:
1161  * @binding: a #GBinding
1162  *
1163  * Explicitly releases the binding between the source and the target
1164  * property expressed by @binding.
1165  *
1166  * This function will release the reference that is being held on
1167  * the @binding instance if the binding is still bound; if you want to hold on
1168  * to the #GBinding instance after calling g_binding_unbind(), you will need
1169  * to hold a reference to it.
1170  *
1171  * Note however that this function does not take ownership of @binding, it
1172  * only unrefs the reference that was initially created by
1173  * g_object_bind_property() and is owned by the binding.
1174  *
1175  * Since: 2.38
1176  */
1177 void
1178 g_binding_unbind (GBinding *binding)
1179 {
1180   g_return_if_fail (G_IS_BINDING (binding));
1181
1182   g_binding_unbind_internal (binding, TRUE);
1183 }
1184
1185 /**
1186  * g_object_bind_property_full:
1187  * @source: (type GObject.Object): the source #GObject
1188  * @source_property: the property on @source to bind
1189  * @target: (type GObject.Object): the target #GObject
1190  * @target_property: the property on @target to bind
1191  * @flags: flags to pass to #GBinding
1192  * @transform_to: (scope notified) (nullable): the transformation function
1193  *     from the @source to the @target, or %NULL to use the default
1194  * @transform_from: (scope notified) (nullable): the transformation function
1195  *     from the @target to the @source, or %NULL to use the default
1196  * @user_data: custom data to be passed to the transformation functions,
1197  *     or %NULL
1198  * @notify: (nullable): a function to call when disposing the binding, to free
1199  *     resources used by the transformation functions, or %NULL if not required
1200  *
1201  * Complete version of g_object_bind_property().
1202  *
1203  * Creates a binding between @source_property on @source and @target_property
1204  * on @target, allowing you to set the transformation functions to be used by
1205  * the binding.
1206  *
1207  * If @flags contains %G_BINDING_BIDIRECTIONAL then the binding will be mutual:
1208  * if @target_property on @target changes then the @source_property on @source
1209  * will be updated as well. The @transform_from function is only used in case
1210  * of bidirectional bindings, otherwise it will be ignored
1211  *
1212  * The binding will automatically be removed when either the @source or the
1213  * @target instances are finalized. This will release the reference that is
1214  * being held on the #GBinding instance; if you want to hold on to the
1215  * #GBinding instance, you will need to hold a reference to it.
1216  *
1217  * To remove the binding, call g_binding_unbind().
1218  *
1219  * A #GObject can have multiple bindings.
1220  *
1221  * The same @user_data parameter will be used for both @transform_to
1222  * and @transform_from transformation functions; the @notify function will
1223  * be called once, when the binding is removed. If you need different data
1224  * for each transformation function, please use
1225  * g_object_bind_property_with_closures() instead.
1226  *
1227  * Returns: (transfer none): the #GBinding instance representing the
1228  *     binding between the two #GObject instances. The binding is released
1229  *     whenever the #GBinding reference count reaches zero.
1230  *
1231  * Since: 2.26
1232  */
1233 GBinding *
1234 g_object_bind_property_full (gpointer               source,
1235                              const gchar           *source_property,
1236                              gpointer               target,
1237                              const gchar           *target_property,
1238                              GBindingFlags          flags,
1239                              GBindingTransformFunc  transform_to,
1240                              GBindingTransformFunc  transform_from,
1241                              gpointer               user_data,
1242                              GDestroyNotify         notify)
1243 {
1244   GParamSpec *pspec;
1245   GBinding *binding;
1246
1247   g_return_val_if_fail (G_IS_OBJECT (source), NULL);
1248   g_return_val_if_fail (source_property != NULL, NULL);
1249   g_return_val_if_fail (g_param_spec_is_valid_name (source_property), NULL);
1250   g_return_val_if_fail (G_IS_OBJECT (target), NULL);
1251   g_return_val_if_fail (target_property != NULL, NULL);
1252   g_return_val_if_fail (g_param_spec_is_valid_name (target_property), NULL);
1253
1254   if (source == target && g_strcmp0 (source_property, target_property) == 0)
1255     {
1256       g_critical ("Unable to bind the same property on the same instance");
1257       return NULL;
1258     }
1259
1260   /* remove the G_BINDING_INVERT_BOOLEAN flag in case we have
1261    * custom transformation functions
1262    */
1263   if ((flags & G_BINDING_INVERT_BOOLEAN) &&
1264       (transform_to != NULL || transform_from != NULL))
1265     {
1266       flags &= ~G_BINDING_INVERT_BOOLEAN;
1267     }
1268
1269   pspec = g_object_class_find_property (G_OBJECT_GET_CLASS (source), source_property);
1270   if (pspec == NULL)
1271     {
1272       g_critical ("%s: The source object of type %s has no property called '%s'",
1273                   G_STRLOC,
1274                   G_OBJECT_TYPE_NAME (source),
1275                   source_property);
1276       return NULL;
1277     }
1278
1279   if (!(pspec->flags & G_PARAM_READABLE))
1280     {
1281       g_critical ("%s: The source object of type %s has no readable property called '%s'",
1282                   G_STRLOC,
1283                   G_OBJECT_TYPE_NAME (source),
1284                   source_property);
1285       return NULL;
1286     }
1287
1288   if ((flags & G_BINDING_BIDIRECTIONAL) &&
1289       ((pspec->flags & G_PARAM_CONSTRUCT_ONLY) || !(pspec->flags & G_PARAM_WRITABLE)))
1290     {
1291       g_critical ("%s: The source object of type %s has no writable property called '%s'",
1292                   G_STRLOC,
1293                   G_OBJECT_TYPE_NAME (source),
1294                   source_property);
1295       return NULL;
1296     }
1297
1298   if ((flags & G_BINDING_INVERT_BOOLEAN) &&
1299       !(G_PARAM_SPEC_VALUE_TYPE (pspec) == G_TYPE_BOOLEAN))
1300     {
1301       g_critical ("%s: The G_BINDING_INVERT_BOOLEAN flag can only be used "
1302                   "when binding boolean properties; the source property '%s' "
1303                   "is of type '%s'",
1304                   G_STRLOC,
1305                   source_property,
1306                   g_type_name (G_PARAM_SPEC_VALUE_TYPE (pspec)));
1307       return NULL;
1308     }
1309
1310   pspec = g_object_class_find_property (G_OBJECT_GET_CLASS (target), target_property);
1311   if (pspec == NULL)
1312     {
1313       g_critical ("%s: The target object of type %s has no property called '%s'",
1314                   G_STRLOC,
1315                   G_OBJECT_TYPE_NAME (target),
1316                   target_property);
1317       return NULL;
1318     }
1319
1320   if ((pspec->flags & G_PARAM_CONSTRUCT_ONLY) || !(pspec->flags & G_PARAM_WRITABLE))
1321     {
1322       g_critical ("%s: The target object of type %s has no writable property called '%s'",
1323                   G_STRLOC,
1324                   G_OBJECT_TYPE_NAME (target),
1325                   target_property);
1326       return NULL;
1327     }
1328
1329   if ((flags & G_BINDING_BIDIRECTIONAL) &&
1330       !(pspec->flags & G_PARAM_READABLE))
1331     {
1332       g_critical ("%s: The target object of type %s has no readable property called '%s'",
1333                   G_STRLOC,
1334                   G_OBJECT_TYPE_NAME (target),
1335                   target_property);
1336       return NULL;
1337     }
1338
1339   if ((flags & G_BINDING_INVERT_BOOLEAN) &&
1340       !(G_PARAM_SPEC_VALUE_TYPE (pspec) == G_TYPE_BOOLEAN))
1341     {
1342       g_critical ("%s: The G_BINDING_INVERT_BOOLEAN flag can only be used "
1343                   "when binding boolean properties; the target property '%s' "
1344                   "is of type '%s'",
1345                   G_STRLOC,
1346                   target_property,
1347                   g_type_name (G_PARAM_SPEC_VALUE_TYPE (pspec)));
1348       return NULL;
1349     }
1350
1351   binding = g_object_new (G_TYPE_BINDING,
1352                           "source", source,
1353                           "source-property", source_property,
1354                           "target", target,
1355                           "target-property", target_property,
1356                           "flags", flags,
1357                           NULL);
1358
1359   g_assert (binding->transform_func != NULL);
1360
1361   /* Use default functions if not provided here */
1362   if (transform_to == NULL)
1363     transform_to = binding->transform_func->transform_s2t;
1364
1365   if (transform_from == NULL)
1366     transform_from = binding->transform_func->transform_t2s;
1367
1368   g_clear_pointer (&binding->transform_func, transform_func_unref);
1369   binding->transform_func = transform_func_new (transform_to, transform_from, user_data, notify);
1370
1371   /* synchronize the target with the source by faking an emission of
1372    * the ::notify signal for the source property; this will also take
1373    * care of the bidirectional binding case because the eventual change
1374    * will emit a notification on the target
1375    */
1376   if (flags & G_BINDING_SYNC_CREATE)
1377     on_source_notify (source, binding->source_pspec, binding->context);
1378
1379   return binding;
1380 }
1381
1382 /**
1383  * g_object_bind_property:
1384  * @source: (type GObject.Object): the source #GObject
1385  * @source_property: the property on @source to bind
1386  * @target: (type GObject.Object): the target #GObject
1387  * @target_property: the property on @target to bind
1388  * @flags: flags to pass to #GBinding
1389  *
1390  * Creates a binding between @source_property on @source and @target_property
1391  * on @target.
1392  *
1393  * Whenever the @source_property is changed the @target_property is
1394  * updated using the same value. For instance:
1395  *
1396  * |[<!-- language="C" -->
1397  *   g_object_bind_property (action, "active", widget, "sensitive", 0);
1398  * ]|
1399  *
1400  * Will result in the "sensitive" property of the widget #GObject instance to be
1401  * updated with the same value of the "active" property of the action #GObject
1402  * instance.
1403  *
1404  * If @flags contains %G_BINDING_BIDIRECTIONAL then the binding will be mutual:
1405  * if @target_property on @target changes then the @source_property on @source
1406  * will be updated as well.
1407  *
1408  * The binding will automatically be removed when either the @source or the
1409  * @target instances are finalized. To remove the binding without affecting the
1410  * @source and the @target you can just call g_object_unref() on the returned
1411  * #GBinding instance.
1412  *
1413  * Removing the binding by calling g_object_unref() on it must only be done if
1414  * the binding, @source and @target are only used from a single thread and it
1415  * is clear that both @source and @target outlive the binding. Especially it
1416  * is not safe to rely on this if the binding, @source or @target can be
1417  * finalized from different threads. Keep another reference to the binding and
1418  * use g_binding_unbind() instead to be on the safe side.
1419  *
1420  * A #GObject can have multiple bindings.
1421  *
1422  * Returns: (transfer none): the #GBinding instance representing the
1423  *     binding between the two #GObject instances. The binding is released
1424  *     whenever the #GBinding reference count reaches zero.
1425  *
1426  * Since: 2.26
1427  */
1428 GBinding *
1429 g_object_bind_property (gpointer       source,
1430                         const gchar   *source_property,
1431                         gpointer       target,
1432                         const gchar   *target_property,
1433                         GBindingFlags  flags)
1434 {
1435   /* type checking is done in g_object_bind_property_full() */
1436
1437   return g_object_bind_property_full (source, source_property,
1438                                       target, target_property,
1439                                       flags,
1440                                       NULL,
1441                                       NULL,
1442                                       NULL, NULL);
1443 }
1444
1445 typedef struct _TransformData
1446 {
1447   GClosure *transform_to_closure;
1448   GClosure *transform_from_closure;
1449 } TransformData;
1450
1451 static gboolean
1452 bind_with_closures_transform_to (GBinding     *binding,
1453                                  const GValue *source,
1454                                  GValue       *target,
1455                                  gpointer      data)
1456 {
1457   TransformData *t_data = data;
1458   GValue params[3] = { G_VALUE_INIT, G_VALUE_INIT, G_VALUE_INIT };
1459   GValue retval = G_VALUE_INIT;
1460   gboolean res;
1461
1462   g_value_init (&params[0], G_TYPE_BINDING);
1463   g_value_set_object (&params[0], binding);
1464
1465   g_value_init (&params[1], G_TYPE_VALUE);
1466   g_value_set_boxed (&params[1], source);
1467
1468   g_value_init (&params[2], G_TYPE_VALUE);
1469   g_value_set_boxed (&params[2], target);
1470
1471   g_value_init (&retval, G_TYPE_BOOLEAN);
1472   g_value_set_boolean (&retval, FALSE);
1473
1474   g_closure_invoke (t_data->transform_to_closure, &retval, 3, params, NULL);
1475
1476   res = g_value_get_boolean (&retval);
1477   if (res)
1478     {
1479       const GValue *out_value = g_value_get_boxed (&params[2]);
1480
1481       g_assert (out_value != NULL);
1482
1483       g_value_copy (out_value, target);
1484     }
1485
1486   g_value_unset (&params[0]);
1487   g_value_unset (&params[1]);
1488   g_value_unset (&params[2]);
1489   g_value_unset (&retval);
1490
1491   return res;
1492 }
1493
1494 static gboolean
1495 bind_with_closures_transform_from (GBinding     *binding,
1496                                    const GValue *source,
1497                                    GValue       *target,
1498                                    gpointer      data)
1499 {
1500   TransformData *t_data = data;
1501   GValue params[3] = { G_VALUE_INIT, G_VALUE_INIT, G_VALUE_INIT };
1502   GValue retval = G_VALUE_INIT;
1503   gboolean res;
1504
1505   g_value_init (&params[0], G_TYPE_BINDING);
1506   g_value_set_object (&params[0], binding);
1507
1508   g_value_init (&params[1], G_TYPE_VALUE);
1509   g_value_set_boxed (&params[1], source);
1510
1511   g_value_init (&params[2], G_TYPE_VALUE);
1512   g_value_set_boxed (&params[2], target);
1513
1514   g_value_init (&retval, G_TYPE_BOOLEAN);
1515   g_value_set_boolean (&retval, FALSE);
1516
1517   g_closure_invoke (t_data->transform_from_closure, &retval, 3, params, NULL);
1518
1519   res = g_value_get_boolean (&retval);
1520   if (res)
1521     {
1522       const GValue *out_value = g_value_get_boxed (&params[2]);
1523
1524       g_assert (out_value != NULL);
1525
1526       g_value_copy (out_value, target);
1527     }
1528
1529   g_value_unset (&params[0]);
1530   g_value_unset (&params[1]);
1531   g_value_unset (&params[2]);
1532   g_value_unset (&retval);
1533
1534   return res;
1535 }
1536
1537 static void
1538 bind_with_closures_free_func (gpointer data)
1539 {
1540   TransformData *t_data = data;
1541
1542   if (t_data->transform_to_closure != NULL)
1543     g_closure_unref (t_data->transform_to_closure);
1544
1545   if (t_data->transform_from_closure != NULL)
1546     g_closure_unref (t_data->transform_from_closure);
1547
1548   g_slice_free (TransformData, t_data);
1549 }
1550
1551 /**
1552  * g_object_bind_property_with_closures: (rename-to g_object_bind_property_full)
1553  * @source: (type GObject.Object): the source #GObject
1554  * @source_property: the property on @source to bind
1555  * @target: (type GObject.Object): the target #GObject
1556  * @target_property: the property on @target to bind
1557  * @flags: flags to pass to #GBinding
1558  * @transform_to: a #GClosure wrapping the transformation function
1559  *     from the @source to the @target, or %NULL to use the default
1560  * @transform_from: a #GClosure wrapping the transformation function
1561  *     from the @target to the @source, or %NULL to use the default
1562  *
1563  * Creates a binding between @source_property on @source and @target_property
1564  * on @target, allowing you to set the transformation functions to be used by
1565  * the binding.
1566  *
1567  * This function is the language bindings friendly version of
1568  * g_object_bind_property_full(), using #GClosures instead of
1569  * function pointers.
1570  *
1571  * Returns: (transfer none): the #GBinding instance representing the
1572  *     binding between the two #GObject instances. The binding is released
1573  *     whenever the #GBinding reference count reaches zero.
1574  *
1575  * Since: 2.26
1576  */
1577 GBinding *
1578 g_object_bind_property_with_closures (gpointer       source,
1579                                       const gchar   *source_property,
1580                                       gpointer       target,
1581                                       const gchar   *target_property,
1582                                       GBindingFlags  flags,
1583                                       GClosure      *transform_to,
1584                                       GClosure      *transform_from)
1585 {
1586   TransformData *data;
1587
1588   data = g_slice_new0 (TransformData);
1589
1590   if (transform_to != NULL)
1591     {
1592       if (G_CLOSURE_NEEDS_MARSHAL (transform_to))
1593         g_closure_set_marshal (transform_to, g_cclosure_marshal_BOOLEAN__BOXED_BOXED);
1594
1595       data->transform_to_closure = g_closure_ref (transform_to);
1596       g_closure_sink (data->transform_to_closure);
1597     }
1598
1599   if (transform_from != NULL)
1600     {
1601       if (G_CLOSURE_NEEDS_MARSHAL (transform_from))
1602         g_closure_set_marshal (transform_from, g_cclosure_marshal_BOOLEAN__BOXED_BOXED);
1603
1604       data->transform_from_closure = g_closure_ref (transform_from);
1605       g_closure_sink (data->transform_from_closure);
1606     }
1607
1608   return g_object_bind_property_full (source, source_property,
1609                                       target, target_property,
1610                                       flags,
1611                                       transform_to != NULL ? bind_with_closures_transform_to : NULL,
1612                                       transform_from != NULL ? bind_with_closures_transform_from : NULL,
1613                                       data,
1614                                       bind_with_closures_free_func);
1615 }