gobject/gbinding.c

   1 /* gbinding.c: Binding for object properties
   2  *
   3  * Copyright (C) 2010  Intel Corp.
   4  *
   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.
   9  *
  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.
  14  *
  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/>.
  17  *
  18  * Author: Emmanuele Bassi <ebassi@linux.intel.com>
  19  */
  20
  21 /**
  22  * SECTION:gbinding
  23  * @Title: GBinding
  24  * @Short_Description: Bind two object properties
  25  *
  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
  30  * binding:
  31  *
  32  * |[<!-- language="C" -->
  33  *   g_object_bind_property (object1, "property-a",
  34  *                           object2, "property-b",
  35  *                           G_BINDING_DEFAULT);
  36  * ]|
  37  *
  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.
  41  *
  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:
  45  *
  46  * |[<!-- language="C" -->
  47  *   g_object_bind_property (object1, "property-a",
  48  *                           object2, "property-b",
  49  *                           G_BINDING_BIDIRECTIONAL);
  50  * ]|
  51  *
  52  * will keep the two properties in sync.
  53  *
  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:
  58  *
  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,
  65  *                                NULL, NULL);
  66  * ]|
  67  *
  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.
  72  *
  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
  76  * of @adjustment1.
  77  *
  78  * Note that #GBinding does not resolve cycles by itself; a cycle like
  79  *
  80  * |[
  81  *   object1:propertyA -> object2:propertyB
  82  *   object2:propertyB -> object3:propertyC
  83  *   object3:propertyC -> object1:propertyA
  84  * ]|
  85  *
  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().
  92  *
  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.
  96  *
  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.
 101  *
 102  * #GBinding is available since GObject 2.26
 103  */
 104
 105 #include "config.h"
 106
 107 #include <string.h>
 108
 109 #include "gbinding.h"
 110 #include "genums.h"
 111 #include "gmarshal.h"
 112 #include "gobject.h"
 113 #include "gsignal.h"
 114 #include "gparamspecs.h"
 115 #include "gvaluetypes.h"
 116
 117 #include "glibintl.h"
 118
 119
 120 GType
 121 g_binding_flags_get_type (void)
 122 {
 123   static volatile gsize g_define_type_id__volatile = 0;
 124
 125   if (g_once_init_enter (&g_define_type_id__volatile))
 126     {
 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" },
 132         { 0, NULL, NULL }
 133       };
 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);
 137     }
 138
 139   return g_define_type_id__volatile;
 140 }
 141
 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))
 145
 146 typedef struct _GBindingClass           GBindingClass;
 147
 148 struct _GBinding
 149 {
 150   GObject parent_instance;
 151
 152   /* no reference is held on the objects, to avoid cycles */
 153   GObject *source;
 154   GObject *target;
 155
 156   /* the property names are interned, so they should not be freed */
 157   const gchar *source_property;
 158   const gchar *target_property;
 159
 160   GParamSpec *source_pspec;
 161   GParamSpec *target_pspec;
 162
 163   GBindingTransformFunc transform_s2t;
 164   GBindingTransformFunc transform_t2s;
 165
 166   GBindingFlags flags;
 167
 168   guint source_notify;
 169   guint target_notify;
 170
 171   gpointer transform_data;
 172   GDestroyNotify notify;
 173
 174   /* a guard, to avoid loops */
 175   guint is_frozen : 1;
 176 };
 177
 178 struct _GBindingClass
 179 {
 180   GObjectClass parent_class;
 181 };
 182
 183 enum
 184 {
 185   PROP_0,
 186
 187   PROP_SOURCE,
 188   PROP_TARGET,
 189   PROP_SOURCE_PROPERTY,
 190   PROP_TARGET_PROPERTY,
 191   PROP_FLAGS
 192 };
 193
 194 static guint gobject_notify_signal_id;
 195
 196 G_DEFINE_TYPE (GBinding, g_binding, G_TYPE_OBJECT)
 197
 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
 200  * be reaped as well
 201  */
 202 static void
 203 weak_unbind (gpointer  user_data,
 204              GObject  *where_the_object_was)
 205 {
 206   GBinding *binding = user_data;
 207
 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
 211    */
 212   if (binding->source == where_the_object_was)
 213     binding->source = NULL;
 214   else
 215     {
 216       if (binding->source_notify != 0)
 217         g_signal_handler_disconnect (binding->source, binding->source_notify);
 218
 219       g_object_weak_unref (binding->source, weak_unbind, user_data);
 220
 221       binding->source_notify = 0;
 222       binding->source = NULL;
 223     }
 224
 225   /* as above, but with the target */
 226   if (binding->target == where_the_object_was)
 227     binding->target = NULL;
 228   else
 229     {
 230       if (binding->target_notify != 0)
 231         g_signal_handler_disconnect (binding->target, binding->target_notify);
 232
 233       g_object_weak_unref (binding->target, weak_unbind, user_data);
 234
 235       binding->target_notify = 0;
 236       binding->target = NULL;
 237     }
 238
 239   /* this will take care of the binding itself */
 240   g_object_unref (binding);
 241 }
 242
 243 static gboolean
 244 default_transform (GBinding     *binding,
 245                    const GValue *value_a,
 246                    GValue       *value_b,
 247                    gpointer      user_data G_GNUC_UNUSED)
 248 {
 249   /* if it's not the same type, try to convert it using the GValue
 250    * transformation API; otherwise just copy it
 251    */
 252   if (!g_type_is_a (G_VALUE_TYPE (value_a), G_VALUE_TYPE (value_b)))
 253     {
 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)))
 257         {
 258           g_value_copy (value_a, value_b);
 259           return TRUE;
 260         }
 261
 262       if (g_value_type_transformable (G_VALUE_TYPE (value_a),
 263                                       G_VALUE_TYPE (value_b)))
 264         {
 265           if (g_value_transform (value_a, value_b))
 266             return TRUE;
 267         }
 268
 269       g_warning ("%s: Unable to convert a value of type %s to a "
 270                  "value of type %s",
 271                  G_STRLOC,
 272                  g_type_name (G_VALUE_TYPE (value_a)),
 273                  g_type_name (G_VALUE_TYPE (value_b)));
 274
 275       return FALSE;
 276     }
 277
 278   g_value_copy (value_a, value_b);
 279   return TRUE;
 280 }
 281
 282 static gboolean
 283 default_invert_boolean_transform (GBinding     *binding,
 284                                   const GValue *value_a,
 285                                   GValue       *value_b,
 286                                   gpointer      user_data G_GNUC_UNUSED)
 287 {
 288   gboolean value;
 289
 290   g_assert (G_VALUE_HOLDS_BOOLEAN (value_a));
 291   g_assert (G_VALUE_HOLDS_BOOLEAN (value_b));
 292
 293   value = g_value_get_boolean (value_a);
 294   value = !value;
 295
 296   g_value_set_boolean (value_b, value);
 297
 298   return TRUE;
 299 }
 300
 301 static void
 302 on_source_notify (GObject    *gobject,
 303                   GParamSpec *pspec,
 304                   GBinding   *binding)
 305 {
 306   GValue from_value = G_VALUE_INIT;
 307   GValue to_value = G_VALUE_INIT;
 308   gboolean res;
 309
 310   if (binding->is_frozen)
 311     return;
 312
 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));
 315
 316   g_object_get_property (binding->source, binding->source_pspec->name, &from_value);
 317
 318   res = binding->transform_s2t (binding,
 319                                 &from_value,
 320                                 &to_value,
 321                                 binding->transform_data);
 322   if (res)
 323     {
 324       binding->is_frozen = TRUE;
 325
 326       g_param_value_validate (binding->target_pspec, &to_value);
 327       g_object_set_property (binding->target, binding->target_pspec->name, &to_value);
 328
 329       binding->is_frozen = FALSE;
 330     }
 331
 332   g_value_unset (&from_value);
 333   g_value_unset (&to_value);
 334 }
 335
 336 static void
 337 on_target_notify (GObject    *gobject,
 338                   GParamSpec *pspec,
 339                   GBinding   *binding)
 340 {
 341   GValue from_value = G_VALUE_INIT;
 342   GValue to_value = G_VALUE_INIT;
 343   gboolean res;
 344
 345   if (binding->is_frozen)
 346     return;
 347
 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));
 350
 351   g_object_get_property (binding->target, binding->target_pspec->name, &from_value);
 352
 353   res = binding->transform_t2s (binding,
 354                                 &from_value,
 355                                 &to_value,
 356                                 binding->transform_data);
 357   if (res)
 358     {
 359       binding->is_frozen = TRUE;
 360
 361       g_param_value_validate (binding->source_pspec, &to_value);
 362       g_object_set_property (binding->source, binding->source_pspec->name, &to_value);
 363
 364       binding->is_frozen = FALSE;
 365     }
 366
 367   g_value_unset (&from_value);
 368   g_value_unset (&to_value);
 369 }
 370
 371 static inline void
 372 g_binding_unbind_internal (GBinding *binding,
 373                            gboolean  unref_binding)
 374 {
 375   gboolean source_is_target = binding->source == binding->target;
 376
 377   /* dispose of the transformation data */
 378   if (binding->notify != NULL)
 379     {
 380       binding->notify (binding->transform_data);
 381
 382       binding->transform_data = NULL;
 383       binding->notify = NULL;
 384     }
 385
 386   if (binding->source != NULL)
 387     {
 388       if (binding->source_notify != 0)
 389         g_signal_handler_disconnect (binding->source, binding->source_notify);
 390
 391       g_object_weak_unref (binding->source, weak_unbind, binding);
 392
 393       binding->source_notify = 0;
 394       binding->source = NULL;
 395     }
 396
 397   if (binding->target != NULL)
 398     {
 399       if (binding->target_notify != 0)
 400         g_signal_handler_disconnect (binding->target, binding->target_notify);
 401
 402       if (!source_is_target)
 403         g_object_weak_unref (binding->target, weak_unbind, binding);
 404
 405       binding->target_notify = 0;
 406       binding->target = NULL;
 407     }
 408
 409   if (unref_binding)
 410     g_object_unref (binding);
 411 }
 412
 413 static void
 414 g_binding_finalize (GObject *gobject)
 415 {
 416   GBinding *binding = G_BINDING (gobject);
 417
 418   g_binding_unbind_internal (binding, FALSE);
 419
 420   G_OBJECT_CLASS (g_binding_parent_class)->finalize (gobject);
 421 }
 422
 423 static void
 424 g_binding_set_property (GObject      *gobject,
 425                         guint         prop_id,
 426                         const GValue *value,
 427                         GParamSpec   *pspec)
 428 {
 429   GBinding *binding = G_BINDING (gobject);
 430
 431   switch (prop_id)
 432     {
 433     case PROP_SOURCE:
 434       binding->source = g_value_get_object (value);
 435       break;
 436
 437     case PROP_SOURCE_PROPERTY:
 438       binding->source_property = g_intern_string (g_value_get_string (value));
 439       break;
 440
 441     case PROP_TARGET:
 442       binding->target = g_value_get_object (value);
 443       break;
 444
 445     case PROP_TARGET_PROPERTY:
 446       binding->target_property = g_intern_string (g_value_get_string (value));
 447       break;
 448
 449     case PROP_FLAGS:
 450       binding->flags = g_value_get_flags (value);
 451       break;
 452
 453     default:
 454       G_OBJECT_WARN_INVALID_PROPERTY_ID (gobject, prop_id, pspec);
 455       break;
 456     }
 457 }
 458
 459 static void
 460 g_binding_get_property (GObject    *gobject,
 461                         guint       prop_id,
 462                         GValue     *value,
 463                         GParamSpec *pspec)
 464 {
 465   GBinding *binding = G_BINDING (gobject);
 466
 467   switch (prop_id)
 468     {
 469     case PROP_SOURCE:
 470       g_value_set_object (value, binding->source);
 471       break;
 472
 473     case PROP_SOURCE_PROPERTY:
 474       g_value_set_string (value, binding->source_property);
 475       break;
 476
 477     case PROP_TARGET:
 478       g_value_set_object (value, binding->target);
 479       break;
 480
 481     case PROP_TARGET_PROPERTY:
 482       g_value_set_string (value, binding->target_property);
 483       break;
 484
 485     case PROP_FLAGS:
 486       g_value_set_flags (value, binding->flags);
 487       break;
 488
 489     default:
 490       G_OBJECT_WARN_INVALID_PROPERTY_ID (gobject, prop_id, pspec);
 491       break;
 492     }
 493 }
 494
 495 static void
 496 g_binding_constructed (GObject *gobject)
 497 {
 498   GBinding *binding = G_BINDING (gobject);
 499   GBindingTransformFunc transform_func = default_transform;
 500   GQuark source_property_detail;
 501   GClosure *source_notify_closure;
 502
 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);
 508
 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
 512    */
 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);
 517
 518   /* switch to the invert boolean transform if needed */
 519   if (binding->flags & G_BINDING_INVERT_BOOLEAN)
 520     transform_func = default_invert_boolean_transform;
 521
 522   /* set the default transformation functions here */
 523   binding->transform_s2t = transform_func;
 524   binding->transform_t2s = transform_func;
 525
 526   binding->transform_data = NULL;
 527   binding->notify = NULL;
 528
 529   source_property_detail = g_quark_from_string (binding->source_property);
 530   source_notify_closure = g_cclosure_new (G_CALLBACK (on_source_notify),
 531                                           binding, NULL);
 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,
 536                                                            FALSE);
 537
 538   g_object_weak_ref (binding->source, weak_unbind, binding);
 539
 540   if (binding->flags & G_BINDING_BIDIRECTIONAL)
 541     {
 542       GQuark target_property_detail;
 543       GClosure *target_notify_closure;
 544
 545       target_property_detail = g_quark_from_string (binding->target_property);
 546       target_notify_closure = g_cclosure_new (G_CALLBACK (on_target_notify),
 547                                               binding, NULL);
 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,
 552                                                                FALSE);
 553     }
 554
 555   if (binding->target != binding->source)
 556     g_object_weak_ref (binding->target, weak_unbind, binding);
 557 }
 558
 559 static void
 560 g_binding_class_init (GBindingClass *klass)
 561 {
 562   GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
 563
 564   gobject_notify_signal_id = g_signal_lookup ("notify", G_TYPE_OBJECT);
 565   g_assert (gobject_notify_signal_id != 0);
 566
 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;
 571
 572   /**
 573    * GBinding:source:
 574    *
 575    * The #GObject that should be used as the source of the binding
 576    *
 577    * Since: 2.26
 578    */
 579   g_object_class_install_property (gobject_class, PROP_SOURCE,
 580                                    g_param_spec_object ("source",
 581                                                         P_("Source"),
 582                                                         P_("The source of the binding"),
 583                                                         G_TYPE_OBJECT,
 584                                                         G_PARAM_CONSTRUCT_ONLY |
 585                                                         G_PARAM_READWRITE |
 586                                                         G_PARAM_STATIC_STRINGS));
 587   /**
 588    * GBinding:target:
 589    *
 590    * The #GObject that should be used as the target of the binding
 591    *
 592    * Since: 2.26
 593    */
 594   g_object_class_install_property (gobject_class, PROP_TARGET,
 595                                    g_param_spec_object ("target",
 596                                                         P_("Target"),
 597                                                         P_("The target of the binding"),
 598                                                         G_TYPE_OBJECT,
 599                                                         G_PARAM_CONSTRUCT_ONLY |
 600                                                         G_PARAM_READWRITE |
 601                                                         G_PARAM_STATIC_STRINGS));
 602   /**
 603    * GBinding:source-property:
 604    *
 605    * The name of the property of #GBinding:source that should be used
 606    * as the source of the binding
 607    *
 608    * Since: 2.26
 609    */
 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"),
 614                                                         NULL,
 615                                                         G_PARAM_CONSTRUCT_ONLY |
 616                                                         G_PARAM_READWRITE |
 617                                                         G_PARAM_STATIC_STRINGS));
 618   /**
 619    * GBinding:target-property:
 620    *
 621    * The name of the property of #GBinding:target that should be used
 622    * as the target of the binding
 623    *
 624    * Since: 2.26
 625    */
 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"),
 630                                                         NULL,
 631                                                         G_PARAM_CONSTRUCT_ONLY |
 632                                                         G_PARAM_READWRITE |
 633                                                         G_PARAM_STATIC_STRINGS));
 634   /**
 635    * GBinding:flags:
 636    *
 637    * Flags to be used to control the #GBinding
 638    *
 639    * Since: 2.26
 640    */
 641   g_object_class_install_property (gobject_class, PROP_FLAGS,
 642                                    g_param_spec_flags ("flags",
 643                                                        P_("Flags"),
 644                                                        P_("The binding flags"),
 645                                                        G_TYPE_BINDING_FLAGS,
 646                                                        G_BINDING_DEFAULT,
 647                                                        G_PARAM_CONSTRUCT_ONLY |
 648                                                        G_PARAM_READWRITE |
 649                                                        G_PARAM_STATIC_STRINGS));
 650 }
 651
 652 static void
 653 g_binding_init (GBinding *binding)
 654 {
 655 }
 656
 657 /**
 658  * g_binding_get_flags:
 659  * @binding: a #GBinding
 660  *
 661  * Retrieves the flags passed when constructing the #GBinding.
 662  *
 663  * Returns: the #GBindingFlags used by the #GBinding
 664  *
 665  * Since: 2.26
 666  */
 667 GBindingFlags
 668 g_binding_get_flags (GBinding *binding)
 669 {
 670   g_return_val_if_fail (G_IS_BINDING (binding), G_BINDING_DEFAULT);
 671
 672   return binding->flags;
 673 }
 674
 675 /**
 676  * g_binding_get_source:
 677  * @binding: a #GBinding
 678  *
 679  * Retrieves the #GObject instance used as the source of the binding.
 680  *
 681  * Returns: (transfer none): the source #GObject
 682  *
 683  * Since: 2.26
 684  */
 685 GObject *
 686 g_binding_get_source (GBinding *binding)
 687 {
 688   g_return_val_if_fail (G_IS_BINDING (binding), NULL);
 689
 690   return binding->source;
 691 }
 692
 693 /**
 694  * g_binding_get_target:
 695  * @binding: a #GBinding
 696  *
 697  * Retrieves the #GObject instance used as the target of the binding.
 698  *
 699  * Returns: (transfer none): the target #GObject
 700  *
 701  * Since: 2.26
 702  */
 703 GObject *
 704 g_binding_get_target (GBinding *binding)
 705 {
 706   g_return_val_if_fail (G_IS_BINDING (binding), NULL);
 707
 708   return binding->target;
 709 }
 710
 711 /**
 712  * g_binding_get_source_property:
 713  * @binding: a #GBinding
 714  *
 715  * Retrieves the name of the property of #GBinding:source used as the source
 716  * of the binding.
 717  *
 718  * Returns: the name of the source property
 719  *
 720  * Since: 2.26
 721  */
 722 const gchar *
 723 g_binding_get_source_property (GBinding *binding)
 724 {
 725   g_return_val_if_fail (G_IS_BINDING (binding), NULL);
 726
 727   return binding->source_property;
 728 }
 729
 730 /**
 731  * g_binding_get_target_property:
 732  * @binding: a #GBinding
 733  *
 734  * Retrieves the name of the property of #GBinding:target used as the target
 735  * of the binding.
 736  *
 737  * Returns: the name of the target property
 738  *
 739  * Since: 2.26
 740  */
 741 const gchar *
 742 g_binding_get_target_property (GBinding *binding)
 743 {
 744   g_return_val_if_fail (G_IS_BINDING (binding), NULL);
 745
 746   return binding->target_property;
 747 }
 748
 749 /**
 750  * g_binding_unbind:
 751  * @binding: a #GBinding
 752  *
 753  * Explicitly releases the binding between the source and the target
 754  * property expressed by @binding.
 755  *
 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
 759  * to it.
 760  *
 761  * Since: 2.38
 762  */
 763 void
 764 g_binding_unbind (GBinding *binding)
 765 {
 766   g_return_if_fail (G_IS_BINDING (binding));
 767
 768   g_binding_unbind_internal (binding, TRUE);
 769 }
 770
 771 /**
 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,
 783  *     or %NULL
 784  * @notify: function to be called when disposing the binding, to free the
 785  *     resources used by the transformation functions
 786  *
 787  * Complete version of g_object_bind_property().
 788  *
 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
 791  * the binding.
 792  *
 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
 797  *
 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.
 802  *
 803  * A #GObject can have multiple bindings.
 804  *
 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.
 810  *
 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.
 814  *
 815  * Since: 2.26
 816  */
 817 GBinding *
 818 g_object_bind_property_full (gpointer               source,
 819                              const gchar           *source_property,
 820                              gpointer               target,
 821                              const gchar           *target_property,
 822                              GBindingFlags          flags,
 823                              GBindingTransformFunc  transform_to,
 824                              GBindingTransformFunc  transform_from,
 825                              gpointer               user_data,
 826                              GDestroyNotify         notify)
 827 {
 828   GParamSpec *pspec;
 829   GBinding *binding;
 830
 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);
 835
 836   if (source == target && g_strcmp0 (source_property, target_property) == 0)
 837     {
 838       g_warning ("Unable to bind the same property on the same instance");
 839       return NULL;
 840     }
 841
 842   /* remove the G_BINDING_INVERT_BOOLEAN flag in case we have
 843    * custom transformation functions
 844    */
 845   if ((flags & G_BINDING_INVERT_BOOLEAN) &&
 846       (transform_to != NULL || transform_from != NULL))
 847     {
 848       flags &= ~G_BINDING_INVERT_BOOLEAN;
 849     }
 850
 851   pspec = g_object_class_find_property (G_OBJECT_GET_CLASS (source), source_property);
 852   if (pspec == NULL)
 853     {
 854       g_warning ("%s: The source object of type %s has no property called '%s'",
 855                  G_STRLOC,
 856                  G_OBJECT_TYPE_NAME (source),
 857                  source_property);
 858       return NULL;
 859     }
 860
 861   if (!(pspec->flags & G_PARAM_READABLE))
 862     {
 863       g_warning ("%s: The source object of type %s has no readable property called '%s'",
 864                  G_STRLOC,
 865                  G_OBJECT_TYPE_NAME (source),
 866                  source_property);
 867       return NULL;
 868     }
 869
 870   if ((flags & G_BINDING_BIDIRECTIONAL) &&
 871       ((pspec->flags & G_PARAM_CONSTRUCT_ONLY) || !(pspec->flags & G_PARAM_WRITABLE)))
 872     {
 873       g_warning ("%s: The source object of type %s has no writable property called '%s'",
 874                  G_STRLOC,
 875                  G_OBJECT_TYPE_NAME (source),
 876                  source_property);
 877       return NULL;
 878     }
 879
 880   if ((flags & G_BINDING_INVERT_BOOLEAN) &&
 881       !(G_PARAM_SPEC_VALUE_TYPE (pspec) == G_TYPE_BOOLEAN))
 882     {
 883       g_warning ("%s: The G_BINDING_INVERT_BOOLEAN flag can only be used "
 884                  "when binding boolean properties; the source property '%s' "
 885                  "is of type '%s'",
 886                  G_STRLOC,
 887                  source_property,
 888                  g_type_name (G_PARAM_SPEC_VALUE_TYPE (pspec)));
 889       return NULL;
 890     }
 891
 892   pspec = g_object_class_find_property (G_OBJECT_GET_CLASS (target), target_property);
 893   if (pspec == NULL)
 894     {
 895       g_warning ("%s: The target object of type %s has no property called '%s'",
 896                  G_STRLOC,
 897                  G_OBJECT_TYPE_NAME (target),
 898                  target_property);
 899       return NULL;
 900     }
 901
 902   if ((pspec->flags & G_PARAM_CONSTRUCT_ONLY) || !(pspec->flags & G_PARAM_WRITABLE))
 903     {
 904       g_warning ("%s: The target object of type %s has no writable property called '%s'",
 905                  G_STRLOC,
 906                  G_OBJECT_TYPE_NAME (target),
 907                  target_property);
 908       return NULL;
 909     }
 910
 911   if ((flags & G_BINDING_BIDIRECTIONAL) &&
 912       !(pspec->flags & G_PARAM_READABLE))
 913     {
 914       g_warning ("%s: The target object of type %s has no readable property called '%s'",
 915                  G_STRLOC,
 916                  G_OBJECT_TYPE_NAME (target),
 917                  target_property);
 918       return NULL;
 919     }
 920
 921   if ((flags & G_BINDING_INVERT_BOOLEAN) &&
 922       !(G_PARAM_SPEC_VALUE_TYPE (pspec) == G_TYPE_BOOLEAN))
 923     {
 924       g_warning ("%s: The G_BINDING_INVERT_BOOLEAN flag can only be used "
 925                  "when binding boolean properties; the target property '%s' "
 926                  "is of type '%s'",
 927                  G_STRLOC,
 928                  target_property,
 929                  g_type_name (G_PARAM_SPEC_VALUE_TYPE (pspec)));
 930       return NULL;
 931     }
 932
 933   binding = g_object_new (G_TYPE_BINDING,
 934                           "source", source,
 935                           "source-property", source_property,
 936                           "target", target,
 937                           "target-property", target_property,
 938                           "flags", flags,
 939                           NULL);
 940
 941   if (transform_to != NULL)
 942     binding->transform_s2t = transform_to;
 943
 944   if (transform_from != NULL)
 945     binding->transform_t2s = transform_from;
 946
 947   binding->transform_data = user_data;
 948   binding->notify = notify;
 949
 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
 954    */
 955   if (flags & G_BINDING_SYNC_CREATE)
 956     on_source_notify (binding->source, binding->source_pspec, binding);
 957
 958   return binding;
 959 }
 960
 961 /**
 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
 968  *
 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:
 972  *
 973  * |[
 974  *   g_object_bind_property (action, "active", widget, "sensitive", 0);
 975  * ]|
 976  *
 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
 979  * instance.
 980  *
 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.
 984  *
 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.
 989  *
 990  * A #GObject can have multiple bindings.
 991  *
 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.
 995  *
 996  * Since: 2.26
 997  */
 998 GBinding *
 999 g_object_bind_property (gpointer       source,
1000                         const gchar   *source_property,
1001                         gpointer       target,
1002                         const gchar   *target_property,
1003                         GBindingFlags  flags)
1004 {
1005   /* type checking is done in g_object_bind_property_full() */
1006
1007   return g_object_bind_property_full (source, source_property,
1008                                       target, target_property,
1009                                       flags,
1010                                       NULL,
1011                                       NULL,
1012                                       NULL, NULL);
1013 }
1014
1015 typedef struct _TransformData
1016 {
1017   GClosure *transform_to_closure;
1018   GClosure *transform_from_closure;
1019 } TransformData;
1020
1021 static gboolean
1022 bind_with_closures_transform_to (GBinding     *binding,
1023                                  const GValue *source,
1024                                  GValue       *target,
1025                                  gpointer      data)
1026 {
1027   TransformData *t_data = data;
1028   GValue params[3] = { G_VALUE_INIT, G_VALUE_INIT, G_VALUE_INIT };
1029   GValue retval = G_VALUE_INIT;
1030   gboolean res;
1031
1032   g_value_init (&params[0], G_TYPE_BINDING);
1033   g_value_set_object (&params[0], binding);
1034
1035   g_value_init (&params[1], G_TYPE_VALUE);
1036   g_value_set_boxed (&params[1], source);
1037
1038   g_value_init (&params[2], G_TYPE_VALUE);
1039   g_value_set_boxed (&params[2], target);
1040
1041   g_value_init (&retval, G_TYPE_BOOLEAN);
1042   g_value_set_boolean (&retval, FALSE);
1043
1044   g_closure_invoke (t_data->transform_to_closure, &retval, 3, params, NULL);
1045
1046   res = g_value_get_boolean (&retval);
1047   if (res)
1048     {
1049       const GValue *out_value = g_value_get_boxed (&params[2]);
1050
1051       g_assert (out_value != NULL);
1052
1053       g_value_copy (out_value, target);
1054     }
1055
1056   g_value_unset (&params[0]);
1057   g_value_unset (&params[1]);
1058   g_value_unset (&params[2]);
1059   g_value_unset (&retval);
1060
1061   return res;
1062 }
1063
1064 static gboolean
1065 bind_with_closures_transform_from (GBinding     *binding,
1066                                    const GValue *source,
1067                                    GValue       *target,
1068                                    gpointer      data)
1069 {
1070   TransformData *t_data = data;
1071   GValue params[3] = { G_VALUE_INIT, G_VALUE_INIT, G_VALUE_INIT };
1072   GValue retval = G_VALUE_INIT;
1073   gboolean res;
1074
1075   g_value_init (&params[0], G_TYPE_BINDING);
1076   g_value_set_object (&params[0], binding);
1077
1078   g_value_init (&params[1], G_TYPE_VALUE);
1079   g_value_set_boxed (&params[1], source);
1080
1081   g_value_init (&params[2], G_TYPE_VALUE);
1082   g_value_set_boxed (&params[2], target);
1083
1084   g_value_init (&retval, G_TYPE_BOOLEAN);
1085   g_value_set_boolean (&retval, FALSE);
1086
1087   g_closure_invoke (t_data->transform_from_closure, &retval, 3, params, NULL);
1088
1089   res = g_value_get_boolean (&retval);
1090   if (res)
1091     {
1092       const GValue *out_value = g_value_get_boxed (&params[2]);
1093
1094       g_assert (out_value != NULL);
1095
1096       g_value_copy (out_value, target);
1097     }
1098
1099   g_value_unset (&params[0]);
1100   g_value_unset (&params[1]);
1101   g_value_unset (&params[2]);
1102   g_value_unset (&retval);
1103
1104   return res;
1105 }
1106
1107 static void
1108 bind_with_closures_free_func (gpointer data)
1109 {
1110   TransformData *t_data = data;
1111
1112   if (t_data->transform_to_closure != NULL)
1113     g_closure_unref (t_data->transform_to_closure);
1114
1115   if (t_data->transform_from_closure != NULL)
1116     g_closure_unref (t_data->transform_from_closure);
1117
1118   g_slice_free (TransformData, t_data);
1119 }
1120
1121 /**
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
1132  *
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
1135  * the binding.
1136  *
1137  * This function is the language bindings friendly version of
1138  * g_object_bind_property_full(), using #GClosures instead of
1139  * function pointers.
1140  *
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.
1144  *
1145  * Since: 2.26
1146  */
1147 GBinding *
1148 g_object_bind_property_with_closures (gpointer       source,
1149                                       const gchar   *source_property,
1150                                       gpointer       target,
1151                                       const gchar   *target_property,
1152                                       GBindingFlags  flags,
1153                                       GClosure      *transform_to,
1154                                       GClosure      *transform_from)
1155 {
1156   TransformData *data;
1157
1158   data = g_slice_new0 (TransformData);
1159
1160   if (transform_to != NULL)
1161     {
1162       if (G_CLOSURE_NEEDS_MARSHAL (transform_to))
1163         g_closure_set_marshal (transform_to, g_cclosure_marshal_BOOLEAN__BOXED_BOXED);
1164
1165       data->transform_to_closure = g_closure_ref (transform_to);
1166       g_closure_sink (data->transform_to_closure);
1167     }
1168
1169   if (transform_from != NULL)
1170     {
1171       if (G_CLOSURE_NEEDS_MARSHAL (transform_from))
1172         g_closure_set_marshal (transform_from, g_cclosure_marshal_BOOLEAN__BOXED_BOXED);
1173
1174       data->transform_from_closure = g_closure_ref (transform_from);
1175       g_closure_sink (data->transform_from_closure);
1176     }
1177
1178   return g_object_bind_property_full (source, source_property,
1179                                       target, target_property,
1180                                       flags,
1181                                       transform_to != NULL ? bind_with_closures_transform_to : NULL,
1182                                       transform_from != NULL ? bind_with_closures_transform_from : NULL,
1183                                       data,
1184                                       bind_with_closures_free_func);
1185 }