Binding Properties Functions

## Binding Properties Functions Binding Properties Functions — Functions used to bind two object properties together |

## Synopsis

    #include <exo/exo.h>

                        ExoBinding;
                        ExoMutualBinding;
    gboolean            (*ExoBindingTransform)              (const GValue *src_value,
                                                             GValue *dst_value,
                                                             gpointer user_data);
    ExoBinding*         exo_binding_new                     (GObject *src_object,
                                                             const gchar *src_property,
                                                             GObject *dst_object,
                                                             const gchar *dst_property);
    ExoBinding*         exo_binding_new_full                (GObject *src_object,
                                                             const gchar *src_property,
                                                             GObject *dst_object,
                                                             const gchar *dst_property,
                                                             ExoBindingTransform transform,
                                                             GDestroyNotify destroy_notify,
                                                             gpointer user_data);
    ExoBinding*         exo_binding_new_with_negation       (GObject *src_object,
                                                             const gchar *src_property,
                                                             GObject *dst_object,
                                                             const gchar *dst_property);
    void                exo_binding_unbind                  (ExoBinding *binding);
    ExoMutualBinding*   exo_mutual_binding_new              (GObject *object1,
                                                             const gchar *property1,
                                                             GObject *object2,
                                                             const gchar *property2);
    ExoMutualBinding*   exo_mutual_binding_new_full         (GObject *object1,
                                                             const gchar *property1,
                                                             GObject *object2,
                                                             const gchar *property2,
                                                             ExoBindingTransform transform,
                                                             ExoBindingTransform reverse_transform,
                                                             GDestroyNotify destroy_notify,
                                                             gpointer user_data);
    ExoMutualBinding*   exo_mutual_binding_new_with_negation
                                                            (GObject *object1,
                                                             const gchar *property1,
                                                             GObject *object2,
                                                             const gchar *property2);
    void                exo_mutual_binding_unbind           (ExoMutualBinding *binding);

## Description

Binding properties is synchronizing values of several properties, so that when one of the bound properties changes, the other bound properties are automatically changed to the new value as well. These functions eliminate the need to write property change notification callbacks manually. It also increases the reliability of your project as you don't need to repeat similar code (and errors) manually.

Both uni-directional and mutual bindings are supported and you can specify functions to perform explicit transformation of values if required. Multiple properties can be bound together in a complex way and infinite loops are eliminated automatically.

For example, lets say, your program has a GtkEntry widget that allows the user to enter some text for the program, but this entry widget should only be sensitive if a GtkCheckButton is active.

Example 3. Connecting a GtkCheckButton and a GtkEntry

    {
      GtkWidget *button;
      GtkWidget *entry;

      button = gtk_check_button_new_with_label ("Activate me");
      entry = gtk_entry_new ();

      exo_binding_new (G_OBJECT (button), "active",
                       G_OBJECT (entry), "sensitive");

      /* add button and entry to the gui... */
    }

As you can see, all you need to do is to call one function to connect the sensitivity of the entry widget with the state of the check button. No need to write signal handlers for this purpose any more.

## Details

### ExoBinding

    typedef struct {
    } ExoBinding;

Opaque structure representing a one-way binding between two properties. It is automatically removed if one of the bound objects is finalized.

### ExoMutualBinding

    typedef struct {
    } ExoMutualBinding;

Opaque structure representing a mutual binding between two properties. It is automatically freed if one of the bound objects is finalized.

### ExoBindingTransform ()

    gboolean            (*ExoBindingTransform)              (const GValue *src_value,
                                                             GValue *dst_value,
                                                             gpointer user_data);

Function type used for binding transformation functions.

Accomplished transformation from `src_value` to `dst_value`. `src_value` and `dst_value` are already initialized before this function gets called.

`src_value` : | Value to transform.
`dst_value` : | Value to store the result of the transformation into.
`user_data` : | User data supplied at binding creation.
Returns : | `FALSE` if transformation failed, else `TRUE`.

### exo_binding_new ()

    ExoBinding*         exo_binding_new                     (GObject *src_object,
                                                             const gchar *src_property,
                                                             GObject *dst_object,
                                                             const gchar *dst_property);

One-way binds `src_property` in `src_object` to `dst_property` in `dst_object`.

Before binding the value of `dst_property` is set to the value of `src_property`.

`src_object` : | The source GObject.
`src_property` : | The name of the property to bind from.
`dst_object` : | The destination GObject.
`dst_property` : | The name of the property to bind to.
Returns : | The descriptor of the binding. It is automatically removed if one of the objects is finalized.

### exo_binding_new_full ()

    ExoBinding*         exo_binding_new_full                (GObject *src_object,
                                                             const gchar *src_property,
                                                             GObject *dst_object,
                                                             const gchar *dst_property,
                                                             ExoBindingTransform transform,
                                                             GDestroyNotify destroy_notify,
                                                             gpointer user_data);

One-way binds `src_property` in `src_object` to `dst_property` in `dst_object`.

Before binding the value of `dst_property` is set to the value of `src_property`.

`src_object` : | The source GObject.
`src_property` : | The name of the property to bind from.
`dst_object` : | The destination GObject.
`dst_property` : | The name of the property to bind to.
`transform` : | Transformation function or `NULL`.
`destroy_notify` : | Callback function that is called on disconnection with `user_data` or `NULL`.
`user_data` : | User data associated with the binding.
Returns : | The descriptor of the binding. It is automatically removed if one of the objects is finalized.

### exo_binding_new_with_negation ()

    ExoBinding*         exo_binding_new_with_negation       (GObject *src_object,
                                                             const gchar *src_property,
                                                             GObject *dst_object,
                                                             const gchar *dst_property);

Convenience function for binding with boolean negation of value.

`src_object` : | The source GObject.
`src_property` : | The name of the property to bind from.
`dst_object` : | The destination GObject.
`dst_property` : | The name of the property to bind to.
Returns : | The descriptor of the binding. It is automatically removed if one of the objects is finalized.

### exo_binding_unbind ()

    void                exo_binding_unbind                  (ExoBinding *binding);

Disconnects the binding between two properties. Should be rarely used by applications.

This functions also calls the `destroy_notify` function that was specified when `binding` was created.

`binding` : | An ExoBinding to unbind.

### exo_mutual_binding_new ()

    ExoMutualBinding*   exo_mutual_binding_new              (GObject *object1,
                                                             const gchar *property1,
                                                             GObject *object2,
                                                             const gchar *property2);

Mutually binds values of two properties.

Before binding the value of `property2` is set to the value of `property1`.

`object1` : | The first GObject.
`property1` : | The first property to bind.
`object2` : | The second GObject.
`property2` : | The second property to bind.
Returns : | The descriptor of the binding. It is automatically removed if one of the objects is finalized.

### exo_mutual_binding_new_full ()

    ExoMutualBinding*   exo_mutual_binding_new_full         (GObject *object1,
                                                             const gchar *property1,
                                                             GObject *object2,
                                                             const gchar *property2,
                                                             ExoBindingTransform transform,
                                                             ExoBindingTransform reverse_transform,
                                                             GDestroyNotify destroy_notify,
                                                             gpointer user_data);

Mutually binds values of two properties.

Before binding the value of `property2` is set to the value of `property1`.

Both `transform` and `reverse_transform` should simultaneously be `NULL` or non-`NULL`. If they are non-`NULL`, they should be reverse in each other.

`object1` : | The first GObject.
`property1` : | The first property to bind.
`object2` : | The second GObject.
`property2` : | The second property to bind.
`transform` : | Transformation function or `NULL`.
`reverse_transform` : | The inverse transformation function or `NULL`.
`destroy_notify` : | Callback function called on disconnection with `user_data` as argument or `NULL`.
`user_data` : | User data associated with the binding.
Returns : | The descriptor of the binding. It is automatically removed if one of the objects is finalized.

### exo_mutual_binding_new_with_negation ()

    ExoMutualBinding*   exo_mutual_binding_new_with_negation
                                                            (GObject *object1,
                                                             const gchar *property1,
                                                             GObject *object2,
                                                             const gchar *property2);

Convenience function for binding with boolean negation of value.

`object1` : | The first GObject.
`property1` : | The first property to bind.
`object2` : | The second GObject.
`property2` : | The second property to bind.
Returns : | The descriptor of the binding. It is automatically removed if one of the objects if finalized.

### exo_mutual_binding_unbind ()

    void                exo_mutual_binding_unbind           (ExoMutualBinding *binding);

Disconnects the binding between two properties. Should be rarely used by applications.

This functions also calls the `destroy_notify` function that was specified when `binding` was created.

`binding` : | An ExoMutualBinding to unbind.

## See Also

GObject Reference Manual, Extensions to GObject