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 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, write to the
  17  * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
  18  * Boston, MA 02111-1307, USA.
  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). Whenever the source property changes, the same
  31  * value is applied to the target property; for instance, the following
  32  * binding:
  33  *
  34  * |[
  35  *   g_object_bind_property (object1, "property-a",
  36  *                           object2, "property-b",
  37  *                           G_BINDING_DEFAULT);
  38  * ]|
  39  *
  40  * will cause <emphasis>object2:property-b</emphasis> to be updated every
  41  * time g_object_set() or the specific accessor changes the value of
  42  * <emphasis>object1:property-a</emphasis>.
  43  *
  44  * It is possible to create a bidirectional binding between two properties
  45  * of two #GObject instances, so that if either property changes, the
  46  * other is updated as well, for instance:
  47  *
  48  * |[
  49  *   g_object_bind_property (object1, "property-a",
  50  *                           object2, "property-b",
  51  *                           G_BINDING_BIDIRECTIONAL);
  52  * ]|
  53  *
  54  * will keep the two properties in sync.
  55  *
  56  * It is also possible to set a custom transformation function (in both
  57  * directions, in case of a bidirectional binding) to apply a custom
  58  * transformation from the source value to the target value before
  59  * applying it; for instance, the following binding:
  60  *
  61  * |[
  62  *   g_object_bind_property_full (adjustment1, "value",
  63  *                                adjustment2, "value",
  64  *                                G_BINDING_BIDIRECTIONAL,
  65  *                                celsius_to_fahrenheit,
  66  *                                fahrenheit_to_celsius,
  67  *                                NULL, NULL);
  68  * ]|
  69  *
  70  * will keep the <emphasis>value</emphasis> property of the two adjustments
  71  * in sync; the <function>celsius_to_fahrenheit</function> function will be
  72  * called whenever the <emphasis>adjustment1:value</emphasis> property changes
  73  * and will transform the current value of the property before applying it
  74  * to the <emphasis>adjustment2:value</emphasis> property; vice versa, the
  75  * <function>fahrenheit_to_celsius</function> function will be called whenever
  76  * the <emphasis>adjustment2:value</emphasis> property changes, and will
  77  * transform the current value of the property before applying it to the
  78  * <emphasis>adjustment1:value</emphasis>.
  79  *
  80  * Note that #GBinding does not resolve cycles by itself; a cycle like
  81  *
  82  * |[
  83  *   object1:propertyA -> object2:propertyB
  84  *   object2:propertyB -> object3:propertyC
  85  *   object3:propertyC -> object1:propertyA
  86  * ]|
  87  *
  88  * might lead to an infinite loop. The loop, in this particular case,
  89  * can be avoided if the objects emit the #GObject::notify signal only
  90  * if the value has effectively been changed. A binding is implemented
  91  * using the #GObject::notify signal, so it is susceptible to all the
  92  * various ways of blocking a signal emission, like g_signal_stop_emission()
  93  * or g_signal_handler_block().
  94  *
  95  * A binding will be severed, and the resources it allocates freed, whenever
  96  * either one of the #GObject instances it refers to are finalized, or when
  97  * the #GBinding instance loses its last reference.
  98  *
  99  * <note><para>Bindings for languages with garbage collection can use
 100  * g_binding_unbind() to explicitly release a binding between the source
 101  * and target properties, instead of relying on the last reference on the
 102  * binding, source, and target instances to drop.</para></note>
 103  *
 104  * #GBinding is available since GObject 2.26
 105  */
 106
 107 #include "config.h"
 108
 109 #include <string.h>
 110
 111 #include "gbinding.h"
 112 #include "genums.h"
 113 #include "gmarshal.h"
 114 #include "gobject.h"
 115 #include "gsignal.h"
 116 #include "gparamspecs.h"
 117 #include "gvaluetypes.h"
 118
 119 #include "glibintl.h"
 120
 121
 122 GType
 123 g_binding_flags_get_type (void)
 124 {
 125   static volatile gsize g_define_type_id__volatile = 0;
 126
 127   if (g_once_init_enter (&g_define_type_id__volatile))
 128     {
 129       static const GFlagsValue values[] = {
 130         { G_BINDING_DEFAULT, "G_BINDING_DEFAULT", "default" },
 131         { G_BINDING_BIDIRECTIONAL, "G_BINDING_BIDIRECTIONAL", "bidirectional" },
 132         { G_BINDING_SYNC_CREATE, "G_BINDING_SYNC_CREATE", "sync-create" },
 133         { G_BINDING_INVERT_BOOLEAN, "G_BINDING_INVERT_BOOLEAN", "invert-boolean" },
 134         { 0, NULL, NULL }
 135       };
 136       GType g_define_type_id =
 137         g_flags_register_static (g_intern_static_string ("GBindingFlags"), values);
 138       g_once_init_leave (&g_define_type_id__volatile, g_define_type_id);
 139     }
 140
 141   return g_define_type_id__volatile;
 142 }
 143
 144 #define G_BINDING_CLASS(klass)          (G_TYPE_CHECK_CLASS_CAST ((klass), G_TYPE_BINDING, GBindingClass))
 145 #define G_IS_BINDING_CLASS(klass)       (G_TYPE_CHECK_CLASS_TYPE ((klass), G_TYPE_BINDING))
 146 #define G_BINDING_GET_CLASS(obj)        (G_TYPE_INSTANCE_GET_CLASS ((obj), G_TYPE_BINDING, GBindingClass))
 147
 148 typedef struct _GBindingClass           GBindingClass;
 149
 150 struct _GBinding
 151 {
 152   GObject parent_instance;
 153
 154   /* no reference is held on the objects, to avoid cycles */
 155   GObject *source;
 156   GObject *target;
 157
 158   /* the property names are interned, so they should not be freed */
 159   const gchar *source_property;
 160   const gchar *target_property;
 161
 162   GParamSpec *source_pspec;
 163   GParamSpec *target_pspec;
 164
 165   GBindingTransformFunc transform_s2t;
 166   GBindingTransformFunc transform_t2s;
 167
 168   GBindingFlags flags;
 169
 170   guint source_notify;
 171   guint target_notify;
 172
 173   gpointer transform_data;
 174   GDestroyNotify notify;
 175
 176   /* a guard, to avoid loops */
 177   guint is_frozen : 1;
 178 };
 179
 180 struct _GBindingClass
 181 {
 182   GObjectClass parent_class;
 183 };
 184
 185 enum
 186 {
 187   PROP_0,
 188
 189   PROP_SOURCE,
 190   PROP_TARGET,
 191   PROP_SOURCE_PROPERTY,
 192   PROP_TARGET_PROPERTY,
 193   PROP_FLAGS
 194 };
 195
 196 static GQuark quark_gbinding = 0;
 197
 198 G_DEFINE_TYPE (GBinding, g_binding, G_TYPE_OBJECT);
 199
 200 static inline void
 201 add_binding_qdata (GObject  *gobject,
 202                    GBinding *binding)
 203 {
 204   GHashTable *bindings;
 205
 206   bindings = g_object_get_qdata (gobject, quark_gbinding);
 207   if (bindings == NULL)
 208     {
 209       bindings = g_hash_table_new (NULL, NULL);
 210
 211       g_object_set_qdata_full (gobject, quark_gbinding,
 212                                bindings,
 213                                (GDestroyNotify) g_hash_table_unref);
 214     }
 215
 216   g_hash_table_add (bindings, binding);
 217 }
 218
 219 static inline void
 220 remove_binding_qdata (GObject  *gobject,
 221                       GBinding *binding)
 222 {
 223   GHashTable *bindings;
 224
 225   bindings = g_object_get_qdata (gobject, quark_gbinding);
 226   if (binding != NULL)
 227     g_hash_table_remove (bindings, binding);
 228 }
 229
 230 /* the basic assumption is that if either the source or the target
 231  * goes away then the binding does not exist any more and it should
 232  * be reaped as well
 233  */
 234 static void
 235 weak_unbind (gpointer  user_data,
 236              GObject  *where_the_object_was)
 237 {
 238   GBinding *binding = user_data;
 239
 240   /* if what went away was the source, unset it so that GBinding::finalize
 241    * does not try to access it; otherwise, disconnect everything and remove
 242    * the GBinding instance from the object's qdata
 243    */
 244   if (binding->source == where_the_object_was)
 245     binding->source = NULL;
 246   else
 247     {
 248       if (binding->source_notify != 0)
 249         g_signal_handler_disconnect (binding->source, binding->source_notify);
 250
 251       g_object_weak_unref (binding->source, weak_unbind, user_data);
 252       remove_binding_qdata (binding->source, binding);
 253
 254       binding->source_notify = 0;
 255       binding->source = NULL;
 256     }
 257
 258   /* as above, but with the target */
 259   if (binding->target == where_the_object_was)
 260     binding->target = NULL;
 261   else
 262     {
 263       if (binding->target_notify != 0)
 264         g_signal_handler_disconnect (binding->target, binding->target_notify);
 265
 266       g_object_weak_unref (binding->target, weak_unbind, user_data);
 267       remove_binding_qdata (binding->target, binding);
 268
 269       binding->target_notify = 0;
 270       binding->target = NULL;
 271     }
 272
 273   /* this will take care of the binding itself */
 274   g_object_unref (binding);
 275 }
 276
 277 static inline gboolean
 278 default_transform (const GValue *value_a,
 279                    GValue       *value_b)
 280 {
 281   /* if it's not the same type, try to convert it using the GValue
 282    * transformation API; otherwise just copy it
 283    */
 284   if (!g_type_is_a (G_VALUE_TYPE (value_a), G_VALUE_TYPE (value_b)))
 285     {
 286       /* are these two types compatible (can be directly copied)? */
 287       if (g_value_type_compatible (G_VALUE_TYPE (value_a),
 288                                    G_VALUE_TYPE (value_b)))
 289         {
 290           g_value_copy (value_a, value_b);
 291           goto done;
 292         }
 293
 294       if (g_value_type_transformable (G_VALUE_TYPE (value_a),
 295                                       G_VALUE_TYPE (value_b)))
 296         {
 297           if (g_value_transform (value_a, value_b))
 298             goto done;
 299
 300           g_warning ("%s: Unable to convert a value of type %s to a "
 301                      "value of type %s",
 302                      G_STRLOC,
 303                      g_type_name (G_VALUE_TYPE (value_a)),
 304                      g_type_name (G_VALUE_TYPE (value_b)));
 305
 306           return FALSE;
 307         }
 308     }
 309   else
 310     g_value_copy (value_a, value_b);
 311
 312 done:
 313   return TRUE;
 314 }
 315
 316 static inline gboolean
 317 default_invert_boolean_transform (const GValue *value_a,
 318                                   GValue       *value_b)
 319 {
 320   gboolean value;
 321
 322   g_assert (G_VALUE_HOLDS_BOOLEAN (value_a));
 323   g_assert (G_VALUE_HOLDS_BOOLEAN (value_b));
 324
 325   value = g_value_get_boolean (value_a);
 326   value = !value;
 327
 328   g_value_set_boolean (value_b, value);
 329
 330   return TRUE;
 331 }
 332
 333 static gboolean
 334 default_transform_to (GBinding     *binding,
 335                       const GValue *value_a,
 336                       GValue       *value_b,
 337                       gpointer      user_data G_GNUC_UNUSED)
 338 {
 339   if (binding->flags & G_BINDING_INVERT_BOOLEAN)
 340     return default_invert_boolean_transform (value_a, value_b);
 341
 342   return default_transform (value_a, value_b);
 343 }
 344
 345 static gboolean
 346 default_transform_from (GBinding     *binding,
 347                         const GValue *value_a,
 348                         GValue       *value_b,
 349                         gpointer      user_data G_GNUC_UNUSED)
 350 {
 351   if (binding->flags & G_BINDING_INVERT_BOOLEAN)
 352     return default_invert_boolean_transform (value_a, value_b);
 353
 354   return default_transform (value_a, value_b);
 355 }
 356
 357 static void
 358 on_source_notify (GObject    *gobject,
 359                   GParamSpec *pspec,
 360                   GBinding   *binding)
 361 {
 362   const gchar *p_name;
 363   GValue from_value = G_VALUE_INIT;
 364   GValue to_value = G_VALUE_INIT;
 365   gboolean res;
 366
 367   if (binding->is_frozen)
 368     return;
 369
 370   p_name = g_intern_string (pspec->name);
 371
 372   if (p_name != binding->source_property)
 373     return;
 374
 375   g_value_init (&from_value, G_PARAM_SPEC_VALUE_TYPE (binding->source_pspec));
 376   g_value_init (&to_value, G_PARAM_SPEC_VALUE_TYPE (binding->target_pspec));
 377
 378   g_object_get_property (binding->source, binding->source_pspec->name, &from_value);
 379
 380   res = binding->transform_s2t (binding,
 381                                 &from_value,
 382                                 &to_value,
 383                                 binding->transform_data);
 384   if (res)
 385     {
 386       binding->is_frozen = TRUE;
 387
 388       g_param_value_validate (binding->target_pspec, &to_value);
 389       g_object_set_property (binding->target, binding->target_pspec->name, &to_value);
 390
 391       binding->is_frozen = FALSE;
 392     }
 393
 394   g_value_unset (&from_value);
 395   g_value_unset (&to_value);
 396 }
 397
 398 static void
 399 on_target_notify (GObject    *gobject,
 400                   GParamSpec *pspec,
 401                   GBinding   *binding)
 402 {
 403   const gchar *p_name;
 404   GValue from_value = G_VALUE_INIT;
 405   GValue to_value = G_VALUE_INIT;
 406   gboolean res;
 407
 408   if (binding->is_frozen)
 409     return;
 410
 411   p_name = g_intern_string (pspec->name);
 412
 413   if (p_name != binding->target_property)
 414     return;
 415
 416   g_value_init (&from_value, G_PARAM_SPEC_VALUE_TYPE (binding->target_pspec));
 417   g_value_init (&to_value, G_PARAM_SPEC_VALUE_TYPE (binding->source_pspec));
 418
 419   g_object_get_property (binding->target, binding->target_pspec->name, &from_value);
 420
 421   res = binding->transform_t2s (binding,
 422                                 &from_value,
 423                                 &to_value,
 424                                 binding->transform_data);
 425   if (res)
 426     {
 427       binding->is_frozen = TRUE;
 428
 429       g_param_value_validate (binding->source_pspec, &to_value);
 430       g_object_set_property (binding->source, binding->source_pspec->name, &to_value);
 431
 432       binding->is_frozen = FALSE;
 433     }
 434
 435   g_value_unset (&from_value);
 436   g_value_unset (&to_value);
 437 }
 438
 439 static inline void
 440 g_binding_unbind_internal (GBinding *binding,
 441                            gboolean  unref_binding)
 442 {
 443   /* dispose of the transformation data */
 444   if (binding->notify != NULL)
 445     {
 446       binding->notify (binding->transform_data);
 447
 448       binding->transform_data = NULL;
 449       binding->notify = NULL;
 450     }
 451
 452   if (binding->source != NULL)
 453     {
 454       if (binding->source_notify != 0)
 455         g_signal_handler_disconnect (binding->source, binding->source_notify);
 456
 457       g_object_weak_unref (binding->source, weak_unbind, binding);
 458       remove_binding_qdata (binding->source, binding);
 459
 460       binding->source_notify = 0;
 461       binding->source = NULL;
 462     }
 463
 464   if (binding->target != NULL)
 465     {
 466       if (binding->target_notify != 0)
 467         g_signal_handler_disconnect (binding->target, binding->target_notify);
 468
 469       g_object_weak_unref (binding->target, weak_unbind, binding);
 470       remove_binding_qdata (binding->target, binding);
 471
 472       binding->target_notify = 0;
 473       binding->target = NULL;
 474     }
 475
 476   if (unref_binding)
 477     g_object_unref (binding);
 478 }
 479
 480 static void
 481 g_binding_finalize (GObject *gobject)
 482 {
 483   GBinding *binding = G_BINDING (gobject);
 484
 485   g_binding_unbind_internal (binding, FALSE);
 486
 487   G_OBJECT_CLASS (g_binding_parent_class)->finalize (gobject);
 488 }
 489
 490 static void
 491 g_binding_set_property (GObject      *gobject,
 492                         guint         prop_id,
 493                         const GValue *value,
 494                         GParamSpec   *pspec)
 495 {
 496   GBinding *binding = G_BINDING (gobject);
 497
 498   switch (prop_id)
 499     {
 500     case PROP_SOURCE:
 501       binding->source = g_value_get_object (value);
 502       break;
 503
 504     case PROP_SOURCE_PROPERTY:
 505       binding->source_property = g_intern_string (g_value_get_string (value));
 506       break;
 507
 508     case PROP_TARGET:
 509       binding->target = g_value_get_object (value);
 510       break;
 511
 512     case PROP_TARGET_PROPERTY:
 513       binding->target_property = g_intern_string (g_value_get_string (value));
 514       break;
 515
 516     case PROP_FLAGS:
 517       binding->flags = g_value_get_flags (value);
 518       break;
 519
 520     default:
 521       G_OBJECT_WARN_INVALID_PROPERTY_ID (gobject, prop_id, pspec);
 522       break;
 523     }
 524 }
 525
 526 static void
 527 g_binding_get_property (GObject    *gobject,
 528                         guint       prop_id,
 529                         GValue     *value,
 530                         GParamSpec *pspec)
 531 {
 532   GBinding *binding = G_BINDING (gobject);
 533
 534   switch (prop_id)
 535     {
 536     case PROP_SOURCE:
 537       g_value_set_object (value, binding->source);
 538       break;
 539
 540     case PROP_SOURCE_PROPERTY:
 541       g_value_set_string (value, binding->source_property);
 542       break;
 543
 544     case PROP_TARGET:
 545       g_value_set_object (value, binding->target);
 546       break;
 547
 548     case PROP_TARGET_PROPERTY:
 549       g_value_set_string (value, binding->target_property);
 550       break;
 551
 552     case PROP_FLAGS:
 553       g_value_set_flags (value, binding->flags);
 554       break;
 555
 556     default:
 557       G_OBJECT_WARN_INVALID_PROPERTY_ID (gobject, prop_id, pspec);
 558       break;
 559     }
 560 }
 561
 562 static void
 563 g_binding_constructed (GObject *gobject)
 564 {
 565   GBinding *binding = G_BINDING (gobject);
 566
 567   /* assert that we were constructed correctly */
 568   g_assert (binding->source != NULL);
 569   g_assert (binding->target != NULL);
 570   g_assert (binding->source_property != NULL);
 571   g_assert (binding->target_property != NULL);
 572
 573   /* we assume a check was performed prior to construction - since
 574    * g_object_bind_property_full() does it; we cannot fail construction
 575    * anyway, so it would be hard for use to properly warn here
 576    */
 577   binding->source_pspec = g_object_class_find_property (G_OBJECT_GET_CLASS (binding->source), binding->source_property);
 578   binding->target_pspec = g_object_class_find_property (G_OBJECT_GET_CLASS (binding->target), binding->target_property);
 579   g_assert (binding->source_pspec != NULL);
 580   g_assert (binding->target_pspec != NULL);
 581
 582   /* set the default transformation functions here */
 583   binding->transform_s2t = default_transform_to;
 584   binding->transform_t2s = default_transform_from;
 585
 586   binding->transform_data = NULL;
 587   binding->notify = NULL;
 588
 589   binding->source_notify = g_signal_connect (binding->source, "notify",
 590                                              G_CALLBACK (on_source_notify),
 591                                              binding);
 592
 593   g_object_weak_ref (binding->source, weak_unbind, binding);
 594   add_binding_qdata (binding->source, binding);
 595
 596   if (binding->flags & G_BINDING_BIDIRECTIONAL)
 597     binding->target_notify = g_signal_connect (binding->target, "notify",
 598                                                G_CALLBACK (on_target_notify),
 599                                                binding);
 600
 601   if (binding->target != binding->source)
 602     {
 603       g_object_weak_ref (binding->target, weak_unbind, binding);
 604       add_binding_qdata (binding->target, binding);
 605     }
 606 }
 607
 608 static void
 609 g_binding_class_init (GBindingClass *klass)
 610 {
 611   GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
 612
 613   quark_gbinding = g_quark_from_static_string ("g-binding");
 614
 615   gobject_class->constructed = g_binding_constructed;
 616   gobject_class->set_property = g_binding_set_property;
 617   gobject_class->get_property = g_binding_get_property;
 618   gobject_class->finalize = g_binding_finalize;
 619
 620   /**
 621    * GBinding:source:
 622    *
 623    * The #GObject that should be used as the source of the binding
 624    *
 625    * Since: 2.26
 626    */
 627   g_object_class_install_property (gobject_class, PROP_SOURCE,
 628                                    g_param_spec_object ("source",
 629                                                         P_("Source"),
 630                                                         P_("The source of the binding"),
 631                                                         G_TYPE_OBJECT,
 632                                                         G_PARAM_CONSTRUCT_ONLY |
 633                                                         G_PARAM_READWRITE |
 634                                                         G_PARAM_STATIC_STRINGS));
 635   /**
 636    * GBinding:target:
 637    *
 638    * The #GObject that should be used as the target of the binding
 639    *
 640    * Since: 2.26
 641    */
 642   g_object_class_install_property (gobject_class, PROP_TARGET,
 643                                    g_param_spec_object ("target",
 644                                                         P_("Target"),
 645                                                         P_("The target of the binding"),
 646                                                         G_TYPE_OBJECT,
 647                                                         G_PARAM_CONSTRUCT_ONLY |
 648                                                         G_PARAM_READWRITE |
 649                                                         G_PARAM_STATIC_STRINGS));
 650   /**
 651    * GBinding:source-property:
 652    *
 653    * The name of the property of #GBinding:source that should be used
 654    * as the source of the binding
 655    *
 656    * Since: 2.26
 657    */
 658   g_object_class_install_property (gobject_class, PROP_SOURCE_PROPERTY,
 659                                    g_param_spec_string ("source-property",
 660                                                         P_("Source Property"),
 661                                                         P_("The property on the source to bind"),
 662                                                         NULL,
 663                                                         G_PARAM_CONSTRUCT_ONLY |
 664                                                         G_PARAM_READWRITE |
 665                                                         G_PARAM_STATIC_STRINGS));
 666   /**
 667    * GBinding:target-property:
 668    *
 669    * The name of the property of #GBinding:target that should be used
 670    * as the target of the binding
 671    *
 672    * Since: 2.26
 673    */
 674   g_object_class_install_property (gobject_class, PROP_TARGET_PROPERTY,
 675                                    g_param_spec_string ("target-property",
 676                                                         P_("Target Property"),
 677                                                         P_("The property on the target to bind"),
 678                                                         NULL,
 679                                                         G_PARAM_CONSTRUCT_ONLY |
 680                                                         G_PARAM_READWRITE |
 681                                                         G_PARAM_STATIC_STRINGS));
 682   /**
 683    * GBinding:flags:
 684    *
 685    * Flags to be used to control the #GBinding
 686    *
 687    * Since: 2.26
 688    */
 689   g_object_class_install_property (gobject_class, PROP_FLAGS,
 690                                    g_param_spec_flags ("flags",
 691                                                        P_("Flags"),
 692                                                        P_("The binding flags"),
 693                                                        G_TYPE_BINDING_FLAGS,
 694                                                        G_BINDING_DEFAULT,
 695                                                        G_PARAM_CONSTRUCT_ONLY |
 696                                                        G_PARAM_READWRITE |
 697                                                        G_PARAM_STATIC_STRINGS));
 698 }
 699
 700 static void
 701 g_binding_init (GBinding *binding)
 702 {
 703 }
 704
 705 /**
 706  * g_binding_get_flags:
 707  * @binding: a #GBinding
 708  *
 709  * Retrieves the flags passed when constructing the #GBinding
 710  *
 711  * Return value: the #GBindingFlags used by the #GBinding
 712  *
 713  * Since: 2.26
 714  */
 715 GBindingFlags
 716 g_binding_get_flags (GBinding *binding)
 717 {
 718   g_return_val_if_fail (G_IS_BINDING (binding), G_BINDING_DEFAULT);
 719
 720   return binding->flags;
 721 }
 722
 723 /**
 724  * g_binding_get_source:
 725  * @binding: a #GBinding
 726  *
 727  * Retrieves the #GObject instance used as the source of the binding
 728  *
 729  * Return value: (transfer none): the source #GObject
 730  *
 731  * Since: 2.26
 732  */
 733 GObject *
 734 g_binding_get_source (GBinding *binding)
 735 {
 736   g_return_val_if_fail (G_IS_BINDING (binding), NULL);
 737
 738   return binding->source;
 739 }
 740
 741 /**
 742  * g_binding_get_target:
 743  * @binding: a #GBinding
 744  *
 745  * Retrieves the #GObject instance used as the target of the binding
 746  *
 747  * Return value: (transfer none): the target #GObject
 748  *
 749  * Since: 2.26
 750  */
 751 GObject *
 752 g_binding_get_target (GBinding *binding)
 753 {
 754   g_return_val_if_fail (G_IS_BINDING (binding), NULL);
 755
 756   return binding->target;
 757 }
 758
 759 /**
 760  * g_binding_get_source_property:
 761  * @binding: a #GBinding
 762  *
 763  * Retrieves the name of the property of #GBinding:source used as the source
 764  * of the binding
 765  *
 766  * Return value: the name of the source property
 767  *
 768  * Since: 2.26
 769  */
 770 const gchar *
 771 g_binding_get_source_property (GBinding *binding)
 772 {
 773   g_return_val_if_fail (G_IS_BINDING (binding), NULL);
 774
 775   return binding->source_property;
 776 }
 777
 778 /**
 779  * g_binding_get_target_property:
 780  * @binding: a #GBinding
 781  *
 782  * Retrieves the name of the property of #GBinding:target used as the target
 783  * of the binding
 784  *
 785  * Return value: the name of the target property
 786  *
 787  * Since: 2.26
 788  */
 789 const gchar *
 790 g_binding_get_target_property (GBinding *binding)
 791 {
 792   g_return_val_if_fail (G_IS_BINDING (binding), NULL);
 793
 794   return binding->target_property;
 795 }
 796
 797 /**
 798  * g_binding_unbind:
 799  * @binding: a #GBinding
 800  *
 801  * Explicitly releases the binding between the source and the target
 802  * property expressed by @binding.
 803  *
 804  * <note>This function will release the reference that is being held on
 805  * the @binding instance; if you want to hold on to the #GBinding instance
 806  * after calling g_binding_unbind(), you will need to hold a reference
 807  * to it.</note>
 808  *
 809  * Since: 2.38
 810  */
 811 void
 812 g_binding_unbind (GBinding *binding)
 813 {
 814   g_return_if_fail (G_IS_BINDING (binding));
 815
 816   g_binding_unbind_internal (binding, TRUE);
 817 }
 818
 819 /**
 820  * g_object_bind_property_full:
 821  * @source: (type GObject.Object): the source #GObject
 822  * @source_property: the property on @source to bind
 823  * @target: (type GObject.Object): the target #GObject
 824  * @target_property: the property on @target to bind
 825  * @flags: flags to pass to #GBinding
 826  * @transform_to: (scope notified) (allow-none): the transformation function
 827  *   from the @source to the @target, or %NULL to use the default
 828  * @transform_from: (scope notified) (allow-none): the transformation function
 829  *   from the @target to the @source, or %NULL to use the default
 830  * @user_data: custom data to be passed to the transformation functions,
 831  *   or %NULL
 832  * @notify: function to be called when disposing the binding, to free the
 833  *   resources used by the transformation functions
 834  *
 835  * Complete version of g_object_bind_property().
 836  *
 837  * Creates a binding between @source_property on @source and @target_property
 838  * on @target, allowing you to set the transformation functions to be used by
 839  * the binding.
 840  *
 841  * If @flags contains %G_BINDING_BIDIRECTIONAL then the binding will be mutual:
 842  * if @target_property on @target changes then the @source_property on @source
 843  * will be updated as well. The @transform_from function is only used in case
 844  * of bidirectional bindings, otherwise it will be ignored
 845  *
 846  * The binding will automatically be removed when either the @source or the
 847  * @target instances are finalized. To remove the binding without affecting the
 848  * @source and the @target you can just call g_object_unref() on the returned
 849  * #GBinding instance.
 850  *
 851  * A #GObject can have multiple bindings.
 852  *
 853  * <note>The same @user_data parameter will be used for both @transform_to
 854  * and @transform_from transformation functions; the @notify function will
 855  * be called once, when the binding is removed. If you need different data
 856  * for each transformation function, please use
 857  * g_object_bind_property_with_closures() instead.</note>
 858  *
 859  * Return value: (transfer none): the #GBinding instance representing the
 860  *   binding between the two #GObject instances. The binding is released
 861  *   whenever the #GBinding reference count reaches zero.
 862  *
 863  * Since: 2.26
 864  */
 865 GBinding *
 866 g_object_bind_property_full (gpointer               source,
 867                              const gchar           *source_property,
 868                              gpointer               target,
 869                              const gchar           *target_property,
 870                              GBindingFlags          flags,
 871                              GBindingTransformFunc  transform_to,
 872                              GBindingTransformFunc  transform_from,
 873                              gpointer               user_data,
 874                              GDestroyNotify         notify)
 875 {
 876   GParamSpec *pspec;
 877   GBinding *binding;
 878
 879   g_return_val_if_fail (G_IS_OBJECT (source), NULL);
 880   g_return_val_if_fail (source_property != NULL, NULL);
 881   g_return_val_if_fail (G_IS_OBJECT (target), NULL);
 882   g_return_val_if_fail (target_property != NULL, NULL);
 883
 884   if (source == target && g_strcmp0 (source_property, target_property) == 0)
 885     {
 886       g_warning ("Unable to bind the same property on the same instance");
 887       return NULL;
 888     }
 889
 890   /* remove the G_BINDING_INVERT_BOOLEAN flag in case we have
 891    * custom transformation functions
 892    */
 893   if ((flags & G_BINDING_INVERT_BOOLEAN) &&
 894       (transform_to != NULL || transform_from != NULL))
 895     {
 896       flags &= ~G_BINDING_INVERT_BOOLEAN;
 897     }
 898
 899   pspec = g_object_class_find_property (G_OBJECT_GET_CLASS (source), source_property);
 900   if (pspec == NULL)
 901     {
 902       g_warning ("%s: The source object of type %s has no property called '%s'",
 903                  G_STRLOC,
 904                  G_OBJECT_TYPE_NAME (source),
 905                  source_property);
 906       return NULL;
 907     }
 908
 909   if (!(pspec->flags & G_PARAM_READABLE))
 910     {
 911       g_warning ("%s: The source object of type %s has no readable property called '%s'",
 912                  G_STRLOC,
 913                  G_OBJECT_TYPE_NAME (source),
 914                  source_property);
 915       return NULL;
 916     }
 917
 918   if ((flags & G_BINDING_BIDIRECTIONAL) &&
 919       ((pspec->flags & G_PARAM_CONSTRUCT_ONLY) || !(pspec->flags & G_PARAM_WRITABLE)))
 920     {
 921       g_warning ("%s: The source object of type %s has no writable property called '%s'",
 922                  G_STRLOC,
 923                  G_OBJECT_TYPE_NAME (source),
 924                  source_property);
 925       return NULL;
 926     }
 927
 928   if ((flags & G_BINDING_INVERT_BOOLEAN) &&
 929       !(G_PARAM_SPEC_VALUE_TYPE (pspec) == G_TYPE_BOOLEAN))
 930     {
 931       g_warning ("%s: The G_BINDING_INVERT_BOOLEAN flag can only be used "
 932                  "when binding boolean properties; the source property '%s' "
 933                  "is of type '%s'",
 934                  G_STRLOC,
 935                  source_property,
 936                  g_type_name (G_PARAM_SPEC_VALUE_TYPE (pspec)));
 937       return NULL;
 938     }
 939
 940   pspec = g_object_class_find_property (G_OBJECT_GET_CLASS (target), target_property);
 941   if (pspec == NULL)
 942     {
 943       g_warning ("%s: The target object of type %s has no property called '%s'",
 944                  G_STRLOC,
 945                  G_OBJECT_TYPE_NAME (target),
 946                  target_property);
 947       return NULL;
 948     }
 949
 950   if ((pspec->flags & G_PARAM_CONSTRUCT_ONLY) || !(pspec->flags & G_PARAM_WRITABLE))
 951     {
 952       g_warning ("%s: The target object of type %s has no writable property called '%s'",
 953                  G_STRLOC,
 954                  G_OBJECT_TYPE_NAME (target),
 955                  target_property);
 956       return NULL;
 957     }
 958
 959   if ((flags & G_BINDING_BIDIRECTIONAL) &&
 960       !(pspec->flags & G_PARAM_READABLE))
 961     {
 962       g_warning ("%s: The target object of type %s has no readable property called '%s'",
 963                  G_STRLOC,
 964                  G_OBJECT_TYPE_NAME (target),
 965                  target_property);
 966       return NULL;
 967     }
 968
 969   if ((flags & G_BINDING_INVERT_BOOLEAN) &&
 970       !(G_PARAM_SPEC_VALUE_TYPE (pspec) == G_TYPE_BOOLEAN))
 971     {
 972       g_warning ("%s: The G_BINDING_INVERT_BOOLEAN flag can only be used "
 973                  "when binding boolean properties; the target property '%s' "
 974                  "is of type '%s'",
 975                  G_STRLOC,
 976                  target_property,
 977                  g_type_name (G_PARAM_SPEC_VALUE_TYPE (pspec)));
 978       return NULL;
 979     }
 980
 981   binding = g_object_new (G_TYPE_BINDING,
 982                           "source", source,
 983                           "source-property", source_property,
 984                           "target", target,
 985                           "target-property", target_property,
 986                           "flags", flags,
 987                           NULL);
 988
 989   if (transform_to != NULL)
 990     binding->transform_s2t = transform_to;
 991
 992   if (transform_from != NULL)
 993     binding->transform_t2s = transform_from;
 994
 995   binding->transform_data = user_data;
 996   binding->notify = notify;
 997
 998   /* synchronize the target with the source by faking an emission of
 999    * the ::notify signal for the source property; this will also take
1000    * care of the bidirectional binding case because the eventual change
1001    * will emit a notification on the target
1002    */
1003   if (flags & G_BINDING_SYNC_CREATE)
1004     on_source_notify (binding->source, binding->source_pspec, binding);
1005
1006   return binding;
1007 }
1008
1009 /**
1010  * g_object_bind_property:
1011  * @source: (type GObject.Object): the source #GObject
1012  * @source_property: the property on @source to bind
1013  * @target: (type GObject.Object): the target #GObject
1014  * @target_property: the property on @target to bind
1015  * @flags: flags to pass to #GBinding
1016  *
1017  * Creates a binding between @source_property on @source and @target_property
1018  * on @target. Whenever the @source_property is changed the @target_property is
1019  * updated using the same value. For instance:
1020  *
1021  * |[
1022  *   g_object_bind_property (action, "active", widget, "sensitive", 0);
1023  * ]|
1024  *
1025  * Will result in the "sensitive" property of the widget #GObject instance to be
1026  * updated with the same value of the "active" property of the action #GObject
1027  * instance.
1028  *
1029  * If @flags contains %G_BINDING_BIDIRECTIONAL then the binding will be mutual:
1030  * if @target_property on @target changes then the @source_property on @source
1031  * will be updated as well.
1032  *
1033  * The binding will automatically be removed when either the @source or the
1034  * @target instances are finalized. To remove the binding without affecting the
1035  * @source and the @target you can just call g_object_unref() on the returned
1036  * #GBinding instance.
1037  *
1038  * A #GObject can have multiple bindings.
1039  *
1040  * Return value: (transfer none): the #GBinding instance representing the
1041  *   binding between the two #GObject instances. The binding is released
1042  *   whenever the #GBinding reference count reaches zero.
1043  *
1044  * Since: 2.26
1045  */
1046 GBinding *
1047 g_object_bind_property (gpointer       source,
1048                         const gchar   *source_property,
1049                         gpointer       target,
1050                         const gchar   *target_property,
1051                         GBindingFlags  flags)
1052 {
1053   /* type checking is done in g_object_bind_property_full() */
1054
1055   return g_object_bind_property_full (source, source_property,
1056                                       target, target_property,
1057                                       flags,
1058                                       NULL,
1059                                       NULL,
1060                                       NULL, NULL);
1061 }
1062
1063 typedef struct _TransformData
1064 {
1065   GClosure *transform_to_closure;
1066   GClosure *transform_from_closure;
1067 } TransformData;
1068
1069 static gboolean
1070 bind_with_closures_transform_to (GBinding     *binding,
1071                                  const GValue *source,
1072                                  GValue       *target,
1073                                  gpointer      data)
1074 {
1075   TransformData *t_data = data;
1076   GValue params[3] = { G_VALUE_INIT, G_VALUE_INIT, G_VALUE_INIT };
1077   GValue retval = G_VALUE_INIT;
1078   gboolean res;
1079
1080   g_value_init (&params[0], G_TYPE_BINDING);
1081   g_value_set_object (&params[0], binding);
1082
1083   g_value_init (&params[1], G_TYPE_VALUE);
1084   g_value_set_boxed (&params[1], source);
1085
1086   g_value_init (&params[2], G_TYPE_VALUE);
1087   g_value_set_boxed (&params[2], target);
1088
1089   g_value_init (&retval, G_TYPE_BOOLEAN);
1090   g_value_set_boolean (&retval, FALSE);
1091
1092   g_closure_invoke (t_data->transform_to_closure, &retval, 3, params, NULL);
1093
1094   res = g_value_get_boolean (&retval);
1095   if (res)
1096     {
1097       const GValue *out_value = g_value_get_boxed (&params[2]);
1098
1099       g_assert (out_value != NULL);
1100
1101       g_value_copy (out_value, target);
1102     }
1103
1104   g_value_unset (&params[0]);
1105   g_value_unset (&params[1]);
1106   g_value_unset (&params[2]);
1107   g_value_unset (&retval);
1108
1109   return res;
1110 }
1111
1112 static gboolean
1113 bind_with_closures_transform_from (GBinding     *binding,
1114                                    const GValue *source,
1115                                    GValue       *target,
1116                                    gpointer      data)
1117 {
1118   TransformData *t_data = data;
1119   GValue params[3] = { G_VALUE_INIT, G_VALUE_INIT, G_VALUE_INIT };
1120   GValue retval = G_VALUE_INIT;
1121   gboolean res;
1122
1123   g_value_init (&params[0], G_TYPE_BINDING);
1124   g_value_set_object (&params[0], binding);
1125
1126   g_value_init (&params[1], G_TYPE_VALUE);
1127   g_value_set_boxed (&params[1], source);
1128
1129   g_value_init (&params[2], G_TYPE_VALUE);
1130   g_value_set_boxed (&params[2], target);
1131
1132   g_value_init (&retval, G_TYPE_BOOLEAN);
1133   g_value_set_boolean (&retval, FALSE);
1134
1135   g_closure_invoke (t_data->transform_from_closure, &retval, 3, params, NULL);
1136
1137   res = g_value_get_boolean (&retval);
1138   if (res)
1139     {
1140       const GValue *out_value = g_value_get_boxed (&params[2]);
1141
1142       g_assert (out_value != NULL);
1143
1144       g_value_copy (out_value, target);
1145     }
1146
1147   g_value_unset (&params[0]);
1148   g_value_unset (&params[1]);
1149   g_value_unset (&params[2]);
1150   g_value_unset (&retval);
1151
1152   return res;
1153 }
1154
1155 static void
1156 bind_with_closures_free_func (gpointer data)
1157 {
1158   TransformData *t_data = data;
1159
1160   if (t_data->transform_to_closure != NULL)
1161     g_closure_unref (t_data->transform_to_closure);
1162
1163   if (t_data->transform_from_closure != NULL)
1164     g_closure_unref (t_data->transform_from_closure);
1165
1166   g_slice_free (TransformData, t_data);
1167 }
1168
1169 /**
1170  * g_object_bind_property_with_closures:
1171  * @source: (type GObject.Object): the source #GObject
1172  * @source_property: the property on @source to bind
1173  * @target: (type GObject.Object): the target #GObject
1174  * @target_property: the property on @target to bind
1175  * @flags: flags to pass to #GBinding
1176  * @transform_to: a #GClosure wrapping the transformation function
1177  *   from the @source to the @target, or %NULL to use the default
1178  * @transform_from: a #GClosure wrapping the transformation function
1179  *   from the @target to the @source, or %NULL to use the default
1180  *
1181  * Creates a binding between @source_property on @source and @target_property
1182  * on @target, allowing you to set the transformation functions to be used by
1183  * the binding.
1184  *
1185  * This function is the language bindings friendly version of
1186  * g_object_bind_property_full(), using #GClosure<!-- -->s instead of
1187  * function pointers.
1188  *
1189  * Rename to: g_object_bind_property_full
1190  *
1191  * Return value: (transfer none): the #GBinding instance representing the
1192  *   binding between the two #GObject instances. The binding is released
1193  *   whenever the #GBinding reference count reaches zero.
1194  *
1195  * Since: 2.26
1196  */
1197 GBinding *
1198 g_object_bind_property_with_closures (gpointer       source,
1199                                       const gchar   *source_property,
1200                                       gpointer       target,
1201                                       const gchar   *target_property,
1202                                       GBindingFlags  flags,
1203                                       GClosure      *transform_to,
1204                                       GClosure      *transform_from)
1205 {
1206   TransformData *data;
1207
1208   data = g_slice_new0 (TransformData);
1209
1210   if (transform_to != NULL)
1211     {
1212       if (G_CLOSURE_NEEDS_MARSHAL (transform_to))
1213         g_closure_set_marshal (transform_to, g_cclosure_marshal_BOOLEAN__BOXED_BOXED);
1214
1215       data->transform_to_closure = g_closure_ref (transform_to);
1216       g_closure_sink (data->transform_to_closure);
1217     }
1218
1219   if (transform_from != NULL)
1220     {
1221       if (G_CLOSURE_NEEDS_MARSHAL (transform_from))
1222         g_closure_set_marshal (transform_from, g_cclosure_marshal_BOOLEAN__BOXED_BOXED);
1223
1224       data->transform_from_closure = g_closure_ref (transform_from);
1225       g_closure_sink (data->transform_from_closure);
1226     }
1227
1228   return g_object_bind_property_full (source, source_property,
1229                                       target, target_property,
1230                                       flags,
1231                                       transform_to != NULL ? bind_with_closures_transform_to : NULL,
1232                                       transform_from != NULL ? bind_with_closures_transform_from : NULL,
1233                                       data,
1234                                       bind_with_closures_free_func);
1235 }