Binding Properties Functions: Exo Reference Manual

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

## Functions

gboolean | (*ExoBindingTransform) ()
ExoBinding * | exo_binding_new ()
ExoBinding * | exo_binding_new_full ()
ExoBinding * | exo_binding_new_with_negation ()
void | exo_binding_unbind ()
ExoMutualBinding * | exo_mutual_binding_new ()
ExoMutualBinding * | exo_mutual_binding_new_full ()
ExoMutualBinding * | exo_mutual_binding_new_with_negation ()
void | exo_mutual_binding_unbind ()

## Types and Values

| ExoBinding
| ExoMutualBinding

## Includes

    #include <exo/exo.h>

## 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

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    {
      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");
    }

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.

## Functions

### 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.

#### Parameters

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` .

#### Parameters

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` .

#### Parameters

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.

#### Parameters

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.

#### Parameters

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` .

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

binding | An ExoMutualBinding to unbind. |

## Types and Values

### ExoBinding

    typedef struct _ExoBinding 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 ExoMutualBinding;

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

## See Also

GObject Reference Manual, Extensions to GObject