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 2. 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 {
  GObject         *src_object;
  ExoBindingBase   base;
  ExoBindingLink   link;
} 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 {
  ExoBindingBase  base;
  ExoBindingLink  direct;
  ExoBindingLink  reverse;
} 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.