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  * #GBinding is available since GObject 2.26
 100  */
 101
 102 #include "config.h"
 103
 104 #include <string.h>
 105
 106 #include "gbinding.h"
 107 #include "genums.h"
 108 #include "gobject.h"
 109 #include "gsignal.h"
 110 #include "gparamspecs.h"
 111 #include "gvaluetypes.h"
 112
 113 #include "glibintl.h"
 114
 115
 116 GType
 117 g_binding_flags_get_type (void)
 118 {
 119   static volatile gsize g_define_type_id__volatile = 0;
 120
 121   if (g_once_init_enter (&g_define_type_id__volatile))
 122     {
 123       static const GFlagsValue values[] = {
 124         { G_BINDING_DEFAULT, "G_BINDING_DEFAULT", "default" },
 125         { G_BINDING_BIDIRECTIONAL, "G_BINDING_BIDIRECTIONAL", "bidirectional" },
 126         { G_BINDING_SYNC_CREATE, "G_BINDING_SYNC_CREATE", "sync-create" },
 127         { 0, NULL, NULL }
 128       };
 129       GType g_define_type_id =
 130         g_flags_register_static (g_intern_static_string ("GBindingFlags"), values);
 131       g_once_init_leave (&g_define_type_id__volatile, g_define_type_id);
 132     }
 133
 134   return g_define_type_id__volatile;
 135 }
 136
 137 #define G_BINDING_CLASS(klass)          (G_TYPE_CHECK_CLASS_CAST ((klass), G_TYPE_BINDING, GBindingClass))
 138 #define G_IS_BINDING_CLASS(klass)       (G_TYPE_CHECK_CLASS_TYPE ((klass), G_TYPE_BINDING))
 139 #define G_BINDING_GET_CLASS(obj)        (G_TYPE_INSTANCE_GET_CLASS ((obj), G_TYPE_BINDING, GBindingClass))
 140
 141 typedef struct _GBindingClass           GBindingClass;
 142
 143 struct _GBinding
 144 {
 145   GObject parent_instance;
 146
 147   /* no reference is held on the objects, to avoid cycles */
 148   GObject *source;
 149   GObject *target;
 150
 151   /* the property names are interned, so they should not be freed */
 152   gchar *source_property;
 153   gchar *target_property;
 154
 155   GParamSpec *source_pspec;
 156   GParamSpec *target_pspec;
 157
 158   GBindingTransformFunc transform_s2t;
 159   GBindingTransformFunc transform_t2s;
 160
 161   GBindingFlags flags;
 162
 163   guint source_notify;
 164   guint target_notify;
 165
 166   gpointer transform_data;
 167   GDestroyNotify notify;
 168
 169   /* a guard, to avoid loops */
 170   guint is_frozen : 1;
 171 };
 172
 173 struct _GBindingClass
 174 {
 175   GObjectClass parent_class;
 176 };
 177
 178 enum
 179 {
 180   PROP_0,
 181
 182   PROP_SOURCE,
 183   PROP_TARGET,
 184   PROP_SOURCE_PROPERTY,
 185   PROP_TARGET_PROPERTY,
 186   PROP_FLAGS
 187 };
 188
 189 static GQuark quark_gbinding = 0;
 190
 191 G_DEFINE_TYPE (GBinding, g_binding, G_TYPE_OBJECT);
 192
 193 static inline void
 194 add_binding_qdata (GObject  *gobject,
 195                    GBinding *binding)
 196 {
 197   GHashTable *bindings;
 198
 199   bindings = g_object_get_qdata (gobject, quark_gbinding);
 200   if (bindings == NULL)
 201     {
 202       bindings = g_hash_table_new (NULL, NULL);
 203
 204       g_object_set_qdata_full (gobject, quark_gbinding,
 205                                bindings,
 206                                (GDestroyNotify) g_hash_table_destroy);
 207     }
 208
 209   g_hash_table_insert (bindings, binding, GUINT_TO_POINTER (1));
 210 }
 211
 212 static inline void
 213 remove_binding_qdata (GObject  *gobject,
 214                       GBinding *binding)
 215 {
 216   GHashTable *bindings;
 217
 218   bindings = g_object_get_qdata (gobject, quark_gbinding);
 219   g_hash_table_remove (bindings, binding);
 220 }
 221
 222 /* the basic assumption is that if either the source or the target
 223  * goes away then the binding does not exist any more and it should
 224  * be reaped as well
 225  */
 226 static void
 227 weak_unbind (gpointer  user_data,
 228              GObject  *where_the_object_was)
 229 {
 230   GBinding *binding = user_data;
 231
 232   /* if what went away was the source, unset it so that GBinding::finalize
 233    * does not try to access it; otherwise, disconnect everything and remove
 234    * the GBinding instance from the object's qdata
 235    */
 236   if (binding->source == where_the_object_was)
 237     binding->source = NULL;
 238   else
 239     {
 240       if (binding->source_notify != 0)
 241         g_signal_handler_disconnect (binding->source, binding->source_notify);
 242
 243       g_object_weak_unref (binding->source, weak_unbind, user_data);
 244       remove_binding_qdata (binding->source, binding);
 245       binding->source = NULL;
 246     }
 247
 248   /* as above, but with the target */
 249   if (binding->target == where_the_object_was)
 250     binding->target = NULL;
 251   else
 252     {
 253       if (binding->target_notify != 0)
 254         g_signal_handler_disconnect (binding->target, binding->target_notify);
 255
 256       g_object_weak_unref (binding->target, weak_unbind, user_data);
 257       remove_binding_qdata (binding->target, binding);
 258       binding->target = NULL;
 259     }
 260
 261   /* this will take care of the binding itself */
 262   g_object_unref (binding);
 263 }
 264
 265 static inline gboolean
 266 default_transform (const GValue *value_a,
 267                    GValue       *value_b)
 268 {
 269   /* if it's not the same type, try to convert it using the GValue
 270    * transformation API; otherwise just copy it
 271    */
 272   if (!g_type_is_a (G_VALUE_TYPE (value_a), G_VALUE_TYPE (value_b)))
 273     {
 274       /* are these two types compatible (can be directly copied)? */
 275       if (g_value_type_compatible (G_VALUE_TYPE (value_a),
 276                                    G_VALUE_TYPE (value_b)))
 277         {
 278           g_value_copy (value_a, value_b);
 279           goto done;
 280         }
 281
 282       if (g_value_type_transformable (G_VALUE_TYPE (value_a),
 283                                       G_VALUE_TYPE (value_b)))
 284         {
 285           if (g_value_transform (value_a, value_b))
 286             goto done;
 287
 288           g_warning ("%s: Unable to convert a value of type %s to a "
 289                      "value of type %s",
 290                      G_STRLOC,
 291                      g_type_name (G_VALUE_TYPE (value_a)),
 292                      g_type_name (G_VALUE_TYPE (value_b)));
 293
 294           return FALSE;
 295         }
 296     }
 297   else
 298     g_value_copy (value_a, value_b);
 299
 300 done:
 301   return TRUE;
 302 }
 303
 304 static gboolean
 305 default_transform_to (GBinding     *binding G_GNUC_UNUSED,
 306                       const GValue *value_a,
 307                       GValue       *value_b,
 308                       gpointer      user_data G_GNUC_UNUSED)
 309 {
 310   return default_transform (value_a, value_b);
 311 }
 312
 313 static gboolean
 314 default_transform_from (GBinding     *binding G_GNUC_UNUSED,
 315                         const GValue *value_a,
 316                         GValue       *value_b,
 317                         gpointer      user_data G_GNUC_UNUSED)
 318 {
 319   return default_transform (value_a, value_b);
 320 }
 321
 322 static void
 323 on_source_notify (GObject    *gobject,
 324                   GParamSpec *pspec,
 325                   GBinding   *binding)
 326 {
 327   const gchar *p_name;
 328   GValue source_value = { 0, };
 329   GValue target_value = { 0, };
 330   gboolean res;
 331
 332   if (binding->is_frozen)
 333     return;
 334
 335   p_name = g_intern_string (pspec->name);
 336
 337   if (p_name != binding->source_property)
 338     return;
 339
 340   g_value_init (&source_value, G_PARAM_SPEC_VALUE_TYPE (binding->source_pspec));
 341   g_value_init (&target_value, G_PARAM_SPEC_VALUE_TYPE (binding->target_pspec));
 342
 343   g_object_get_property (binding->source, binding->source_pspec->name, &source_value);
 344
 345   res = binding->transform_s2t (binding,
 346                                 &source_value,
 347                                 &target_value,
 348                                 binding->transform_data);
 349   if (res)
 350     {
 351       binding->is_frozen = TRUE;
 352
 353       g_param_value_validate (binding->target_pspec, &target_value);
 354       g_object_set_property (binding->target, binding->target_pspec->name, &target_value);
 355
 356       binding->is_frozen = FALSE;
 357     }
 358
 359   g_value_unset (&source_value);
 360   g_value_unset (&target_value);
 361 }
 362
 363 static void
 364 on_target_notify (GObject    *gobject,
 365                   GParamSpec *pspec,
 366                   GBinding   *binding)
 367 {
 368   const gchar *p_name;
 369   GValue source_value = { 0, };
 370   GValue target_value = { 0, };
 371   gboolean res;
 372
 373   if (binding->is_frozen)
 374     return;
 375
 376   p_name = g_intern_string (pspec->name);
 377
 378   if (p_name != binding->target_property)
 379     return;
 380
 381   g_value_init (&source_value, G_PARAM_SPEC_VALUE_TYPE (binding->target_pspec));
 382   g_value_init (&target_value, G_PARAM_SPEC_VALUE_TYPE (binding->source_pspec));
 383
 384   g_object_get_property (binding->target, binding->target_pspec->name, &source_value);
 385
 386   res = binding->transform_t2s (binding,
 387                                 &source_value,
 388                                 &target_value,
 389                                 binding->transform_data);
 390   if (res)
 391     {
 392       binding->is_frozen = TRUE;
 393
 394       g_param_value_validate (binding->source_pspec, &target_value);
 395       g_object_set_property (binding->source, binding->source_pspec->name, &target_value);
 396
 397       binding->is_frozen = FALSE;
 398     }
 399
 400   g_value_unset (&source_value);
 401   g_value_unset (&target_value);
 402 }
 403
 404 static void
 405 g_binding_finalize (GObject *gobject)
 406 {
 407   GBinding *binding = G_BINDING (gobject);
 408
 409   /* dispose of the transformation data */
 410   if (binding->notify != NULL)
 411     {
 412       binding->notify (binding->transform_data);
 413
 414       binding->transform_data = NULL;
 415       binding->notify = NULL;
 416     }
 417
 418   /* we need this in case the source and target instance are still
 419    * valid, and it was the GBinding that was unreferenced
 420    */
 421   if (binding->source != NULL)
 422     {
 423       if (binding->source_notify != 0)
 424         g_signal_handler_disconnect (binding->source, binding->source_notify);
 425
 426       g_object_weak_unref (binding->source, weak_unbind, binding);
 427       remove_binding_qdata (binding->source, binding);
 428     }
 429
 430   if (binding->target != NULL)
 431     {
 432       if (binding->target_notify != 0)
 433         g_signal_handler_disconnect (binding->target, binding->target_notify);
 434
 435       g_object_weak_unref (binding->target, weak_unbind, binding);
 436       remove_binding_qdata (binding->target, binding);
 437     }
 438
 439   G_OBJECT_CLASS (g_binding_parent_class)->finalize (gobject);
 440 }
 441
 442 static void
 443 g_binding_set_property (GObject      *gobject,
 444                         guint         prop_id,
 445                         const GValue *value,
 446                         GParamSpec   *pspec)
 447 {
 448   GBinding *binding = G_BINDING (gobject);
 449
 450   switch (prop_id)
 451     {
 452     case PROP_SOURCE:
 453       binding->source = g_value_get_object (value);
 454       break;
 455
 456     case PROP_SOURCE_PROPERTY:
 457       binding->source_property = g_intern_string (g_value_get_string (value));
 458       break;
 459
 460     case PROP_TARGET:
 461       binding->target = g_value_get_object (value);
 462       break;
 463
 464     case PROP_TARGET_PROPERTY:
 465       binding->target_property = g_intern_string (g_value_get_string (value));
 466       break;
 467
 468     case PROP_FLAGS:
 469       binding->flags = g_value_get_flags (value);
 470       break;
 471
 472     default:
 473       G_OBJECT_WARN_INVALID_PROPERTY_ID (gobject, prop_id, pspec);
 474       break;
 475     }
 476 }
 477
 478 static void
 479 g_binding_get_property (GObject    *gobject,
 480                         guint       prop_id,
 481                         GValue     *value,
 482                         GParamSpec *pspec)
 483 {
 484   GBinding *binding = G_BINDING (gobject);
 485
 486   switch (prop_id)
 487     {
 488     case PROP_SOURCE:
 489       g_value_set_object (value, binding->source);
 490       break;
 491
 492     case PROP_SOURCE_PROPERTY:
 493       g_value_set_string (value, binding->source_property);
 494       break;
 495
 496     case PROP_TARGET:
 497       g_value_set_object (value, binding->target);
 498       break;
 499
 500     case PROP_TARGET_PROPERTY:
 501       g_value_set_string (value, binding->target_property);
 502       break;
 503
 504     case PROP_FLAGS:
 505       g_value_set_flags (value, binding->flags);
 506       break;
 507
 508     default:
 509       G_OBJECT_WARN_INVALID_PROPERTY_ID (gobject, prop_id, pspec);
 510       break;
 511     }
 512 }
 513
 514 static void
 515 g_binding_constructed (GObject *gobject)
 516 {
 517   GBinding *binding = G_BINDING (gobject);
 518
 519   /* assert that we were constructed correctly */
 520   g_assert (binding->source != NULL);
 521   g_assert (binding->target != NULL);
 522   g_assert (binding->source_property != NULL);
 523   g_assert (binding->target_property != NULL);
 524
 525   /* we assume a check was performed prior to construction - since
 526    * g_object_bind_property_full() does it; we cannot fail construction
 527    * anyway, so it would be hard for use to properly warn here
 528    */
 529   binding->source_pspec = g_object_class_find_property (G_OBJECT_GET_CLASS (binding->source), binding->source_property);
 530   binding->target_pspec = g_object_class_find_property (G_OBJECT_GET_CLASS (binding->target), binding->target_property);
 531   g_assert (binding->source_pspec != NULL);
 532   g_assert (binding->target_pspec != NULL);
 533
 534   /* set the default transformation functions here */
 535   binding->transform_s2t = default_transform_to;
 536   binding->transform_t2s = default_transform_from;
 537
 538   binding->transform_data = NULL;
 539   binding->notify = NULL;
 540
 541   binding->source_notify = g_signal_connect (binding->source, "notify",
 542                                              G_CALLBACK (on_source_notify),
 543                                              binding);
 544
 545   g_object_weak_ref (binding->source, weak_unbind, binding);
 546   add_binding_qdata (binding->source, binding);
 547
 548   if (binding->flags & G_BINDING_BIDIRECTIONAL)
 549     binding->target_notify = g_signal_connect (binding->target, "notify",
 550                                                G_CALLBACK (on_target_notify),
 551                                                binding);
 552
 553   g_object_weak_ref (binding->target, weak_unbind, binding);
 554   add_binding_qdata (binding->target, binding);
 555
 556 }
 557
 558 static void
 559 g_binding_class_init (GBindingClass *klass)
 560 {
 561   GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
 562
 563   quark_gbinding = g_quark_from_static_string ("g-binding");
 564
 565   gobject_class->constructed = g_binding_constructed;
 566   gobject_class->set_property = g_binding_set_property;
 567   gobject_class->get_property = g_binding_get_property;
 568   gobject_class->finalize = g_binding_finalize;
 569
 570   /**
 571    * GBinding:source:
 572    *
 573    * The #GObject that should be used as the source of the binding
 574    *
 575    * Since: 2.26
 576    */
 577   g_object_class_install_property (gobject_class, PROP_SOURCE,
 578                                    g_param_spec_object ("source",
 579                                                         P_("Source"),
 580                                                         P_("The source of the binding"),
 581                                                         G_TYPE_OBJECT,
 582                                                         G_PARAM_CONSTRUCT_ONLY |
 583                                                         G_PARAM_READWRITE |
 584                                                         G_PARAM_STATIC_STRINGS));
 585   /**
 586    * GBinding:target:
 587    *
 588    * The #GObject that should be used as the target of the binding
 589    *
 590    * Since: 2.26
 591    */
 592   g_object_class_install_property (gobject_class, PROP_TARGET,
 593                                    g_param_spec_object ("target",
 594                                                         P_("Target"),
 595                                                         P_("The target of the binding"),
 596                                                         G_TYPE_OBJECT,
 597                                                         G_PARAM_CONSTRUCT_ONLY |
 598                                                         G_PARAM_READWRITE |
 599                                                         G_PARAM_STATIC_STRINGS));
 600   /**
 601    * GBinding:source-property:
 602    *
 603    * The name of the property of #GBinding:source that should be used
 604    * as the source of the binding
 605    *
 606    * Since: 2.26
 607    */
 608   g_object_class_install_property (gobject_class, PROP_SOURCE_PROPERTY,
 609                                    g_param_spec_string ("source-property",
 610                                                         P_("Source Property"),
 611                                                         P_("The property on the source to bind"),
 612                                                         NULL,
 613                                                         G_PARAM_CONSTRUCT_ONLY |
 614                                                         G_PARAM_READWRITE |
 615                                                         G_PARAM_STATIC_STRINGS));
 616   /**
 617    * GBinding:target-property:
 618    *
 619    * The name of the property of #GBinding:target that should be used
 620    * as the target of the binding
 621    *
 622    * Since: 2.26
 623    */
 624   g_object_class_install_property (gobject_class, PROP_TARGET_PROPERTY,
 625                                    g_param_spec_string ("target-property",
 626                                                         P_("Target Property"),
 627                                                         P_("The property on the target to bind"),
 628                                                         NULL,
 629                                                         G_PARAM_CONSTRUCT_ONLY |
 630                                                         G_PARAM_READWRITE |
 631                                                         G_PARAM_STATIC_STRINGS));
 632   /**
 633    * GBinding:flags:
 634    *
 635    * Flags to be used to control the #GBinding
 636    *
 637    * Since: 2.26
 638    */
 639   g_object_class_install_property (gobject_class, PROP_FLAGS,
 640                                    g_param_spec_flags ("flags",
 641                                                        P_("Flags"),
 642                                                        P_("The binding flags"),
 643                                                        G_TYPE_BINDING_FLAGS,
 644                                                        G_BINDING_DEFAULT,
 645                                                        G_PARAM_CONSTRUCT_ONLY |
 646                                                        G_PARAM_READWRITE |
 647                                                        G_PARAM_STATIC_STRINGS));
 648 }
 649
 650 static void
 651 g_binding_init (GBinding *binding)
 652 {
 653 }
 654
 655 /**
 656  * g_binding_get_flags:
 657  * @binding: a #GBinding
 658  *
 659  * Retrieves the flags passed when constructing the #GBinding
 660  *
 661  * Return value: the #GBindingFlags used by the #GBinding
 662  *
 663  * Since: 2.26
 664  */
 665 GBindingFlags
 666 g_binding_get_flags (GBinding *binding)
 667 {
 668   g_return_val_if_fail (G_IS_BINDING (binding), G_BINDING_DEFAULT);
 669
 670   return binding->flags;
 671 }
 672
 673 /**
 674  * g_binding_get_source:
 675  * @binding: a #GBinding
 676  *
 677  * Retrieves the #GObject instance used as the source of the binding
 678  *
 679  * Return value: (transfer none): the source #GObject
 680  *
 681  * Since: 2.26
 682  */
 683 GObject *
 684 g_binding_get_source (GBinding *binding)
 685 {
 686   g_return_val_if_fail (G_IS_BINDING (binding), NULL);
 687
 688   return binding->source;
 689 }
 690
 691 /**
 692  * g_binding_get_target:
 693  * @binding: a #GBinding
 694  *
 695  * Retrieves the #GObject instance used as the target of the binding
 696  *
 697  * Return value: (transfer none): the target #GObject
 698  *
 699  * Since: 2.26
 700  */
 701 GObject *
 702 g_binding_get_target (GBinding *binding)
 703 {
 704   g_return_val_if_fail (G_IS_BINDING (binding), NULL);
 705
 706   return binding->target;
 707 }
 708
 709 /**
 710  * g_binding_get_source_property:
 711  * @binding: a #GBinding
 712  *
 713  * Retrieves the name of the property of #GBinding:source used as the source
 714  * of the binding
 715  *
 716  * Return value: the name of the source property
 717  *
 718  * Since: 2.26
 719  */
 720 G_CONST_RETURN gchar *
 721 g_binding_get_source_property (GBinding *binding)
 722 {
 723   g_return_val_if_fail (G_IS_BINDING (binding), NULL);
 724
 725   return binding->source_property;
 726 }
 727
 728 /**
 729  * g_binding_get_target_property:
 730  * @binding: a #GBinding
 731  *
 732  * Retrieves the name of the property of #GBinding:target used as the target
 733  * of the binding
 734  *
 735  * Return value: the name of the target property
 736  *
 737  * Since: 2.26
 738  */
 739 G_CONST_RETURN gchar *
 740 g_binding_get_target_property (GBinding *binding)
 741 {
 742   g_return_val_if_fail (G_IS_BINDING (binding), NULL);
 743
 744   return binding->target_property;
 745 }
 746
 747 /**
 748  * g_object_bind_property_full:
 749  * @source: the source #GObject
 750  * @source_property: the property on @source to bind
 751  * @target: the target #GObject
 752  * @target_property: the property on @target to bind
 753  * @flags: flags to pass to #GBinding
 754  * @transform_to: (scope notified) (allow-none): the transformation function
 755  *   from the @source to the @target, or %NULL to use the default
 756  * @transform_from: (scope notified) (allow-none): the transformation function
 757  *   from the @target to the @source, or %NULL to use the default
 758  * @user_data: custom data to be passed to the transformation functions,
 759  *   or %NULL
 760  * @notify: function to be called when disposing the binding, to free the
 761  *   resources used by the transformation functions
 762  *
 763  * Complete version of g_object_bind_property().
 764  *
 765  * Creates a binding between @source_property on @source and @target_property
 766  * on @target, allowing you to set the transformation functions to be used by
 767  * the binding.
 768  *
 769  * If @flags contains %G_BINDING_BIDIRECTIONAL then the binding will be mutual:
 770  * if @target_property on @target changes then the @source_property on @source
 771  * will be updated as well. The @transform_from function is only used in case
 772  * of bidirectional bindings, otherwise it will be ignored
 773  *
 774  * The binding will automatically be removed when either the @source or the
 775  * @target instances are finalized. To remove the binding without affecting the
 776  * @source and the @target you can just call g_object_unref() on the returned
 777  * #GBinding instance.
 778  *
 779  * A #GObject can have multiple bindings.
 780  *
 781  * Return value: (transfer none): the #GBinding instance representing the
 782  *   binding between the two #GObject instances. The binding is released
 783  *   whenever the #GBinding reference count reaches zero.
 784  *
 785  * Since: 2.26
 786  */
 787 GBinding *
 788 g_object_bind_property_full (gpointer               source,
 789                              const gchar           *source_property,
 790                              gpointer               target,
 791                              const gchar           *target_property,
 792                              GBindingFlags          flags,
 793                              GBindingTransformFunc  transform_to,
 794                              GBindingTransformFunc  transform_from,
 795                              gpointer               user_data,
 796                              GDestroyNotify         notify)
 797 {
 798   GParamSpec *pspec;
 799   GBinding *binding;
 800
 801   g_return_val_if_fail (G_IS_OBJECT (source), NULL);
 802   g_return_val_if_fail (source_property != NULL, NULL);
 803   g_return_val_if_fail (G_IS_OBJECT (target), NULL);
 804   g_return_val_if_fail (target_property != NULL, NULL);
 805
 806   if (source == target && g_strcmp0 (source_property, target_property) == 0)
 807     {
 808       g_warning ("Unable to bind the same property on the same instance");
 809       return NULL;
 810     }
 811
 812   if (transform_to == NULL)
 813     transform_to = default_transform_to;
 814
 815   if (transform_from == NULL)
 816     transform_from = default_transform_from;
 817
 818   pspec = g_object_class_find_property (G_OBJECT_GET_CLASS (source), source_property);
 819   if (pspec == NULL)
 820     {
 821       g_warning ("%s: The source object of type %s has no property called '%s'",
 822                  G_STRLOC,
 823                  G_OBJECT_TYPE_NAME (source),
 824                  source_property);
 825       return NULL;
 826     }
 827
 828   if (!(pspec->flags & G_PARAM_READABLE))
 829     {
 830       g_warning ("%s: The source object of type %s has no readable property called '%s'",
 831                  G_STRLOC,
 832                  G_OBJECT_TYPE_NAME (source),
 833                  source_property);
 834       return NULL;
 835     }
 836
 837   if ((flags & G_BINDING_BIDIRECTIONAL) &&
 838       ((pspec->flags & G_PARAM_CONSTRUCT_ONLY) || !(pspec->flags & G_PARAM_WRITABLE)))
 839     {
 840       g_warning ("%s: The source object of type %s has no writable property called '%s'",
 841                  G_STRLOC,
 842                  G_OBJECT_TYPE_NAME (source),
 843                  source_property);
 844       return NULL;
 845     }
 846
 847   pspec = g_object_class_find_property (G_OBJECT_GET_CLASS (target), target_property);
 848   if (pspec == NULL)
 849     {
 850       g_warning ("%s: The target object of type %s has no property called '%s'",
 851                  G_STRLOC,
 852                  G_OBJECT_TYPE_NAME (target),
 853                  target_property);
 854       return NULL;
 855     }
 856
 857   if ((pspec->flags & G_PARAM_CONSTRUCT_ONLY) || !(pspec->flags & G_PARAM_WRITABLE))
 858     {
 859       g_warning ("%s: The target object of type %s has no writable property called '%s'",
 860                  G_STRLOC,
 861                  G_OBJECT_TYPE_NAME (target),
 862                  target_property);
 863       return NULL;
 864     }
 865
 866   if ((flags & G_BINDING_BIDIRECTIONAL) &&
 867       !(pspec->flags & G_PARAM_READABLE))
 868     {
 869       g_warning ("%s: The starget object of type %s has no writable property called '%s'",
 870                  G_STRLOC,
 871                  G_OBJECT_TYPE_NAME (target),
 872                  target_property);
 873       return NULL;
 874     }
 875
 876   binding = g_object_new (G_TYPE_BINDING,
 877                           "source", source,
 878                           "source-property", source_property,
 879                           "target", target,
 880                           "target-property", target_property,
 881                           "flags", flags,
 882                           NULL);
 883
 884   /* making these properties would be awkward, though not impossible */
 885   binding->transform_s2t = transform_to;
 886   binding->transform_t2s = transform_from;
 887   binding->transform_data = user_data;
 888   binding->notify = notify;
 889
 890   /* synchronize the target with the source by faking an emission of
 891    * the ::notify signal for the source property; this will also take
 892    * care of the bidirectional binding case because the eventual change
 893    * will emit a notification on the target
 894    */
 895   if (flags & G_BINDING_SYNC_CREATE)
 896     on_source_notify (binding->source, binding->source_pspec, binding);
 897
 898   return binding;
 899 }
 900
 901 /**
 902  * g_object_bind_property:
 903  * @source: the source #GObject
 904  * @source_property: the property on @source to bind
 905  * @target: the target #GObject
 906  * @target_property: the property on @target to bind
 907  * @flags: flags to pass to #GBinding
 908  *
 909  * Creates a binding between @source_property on @source and @target_property
 910  * on @target. Whenever the @source_property is changed the @target_property is
 911  * updated using the same value. For instance:
 912  *
 913  * |[
 914  *   g_object_bind_property (action, "active", widget, "sensitive", 0);
 915  * ]|
 916  *
 917  * Will result in the "sensitive" property of the widget #GObject instance to be
 918  * updated with the same value of the "active" property of the action #GObject
 919  * instance.
 920  *
 921  * If @flags contains %G_BINDING_BIDIRECTIONAL then the binding will be mutual:
 922  * if @target_property on @target changes then the @source_property on @source
 923  * will be updated as well.
 924  *
 925  * The binding will automatically be removed when either the @source or the
 926  * @target instances are finalized. To remove the binding without affecting the
 927  * @source and the @target you can just call g_object_unref() on the returned
 928  * #GBinding instance.
 929  *
 930  * A #GObject can have multiple bindings.
 931  *
 932  * Return value: (transfer none): the #GBinding instance representing the
 933  *   binding between the two #GObject instances. The binding is released
 934  *   whenever the #GBinding reference count reaches zero.
 935  *
 936  * Since: 2.26
 937  */
 938 GBinding *
 939 g_object_bind_property (gpointer       source,
 940                         const gchar   *source_property,
 941                         gpointer       target,
 942                         const gchar   *target_property,
 943                         GBindingFlags  flags)
 944 {
 945   /* type checking is done in g_object_bind_property_full() */
 946
 947   return g_object_bind_property_full (source, source_property,
 948                                       target, target_property,
 949                                       flags,
 950                                       NULL,
 951                                       NULL,
 952                                       NULL, NULL);
 953 }