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