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 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");
}

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);

exo_binding_new is deprecated and should not be used in newly-written code.

xfce 4.18: In favor of GBinding

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);

exo_binding_new_full is deprecated and should not be used in newly-written code.

xfce 4.18: In favor of GBinding

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);

exo_binding_new_with_negation is deprecated and should not be used in newly-written code.

xfce 4.18: In favor of GBinding

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);

exo_binding_unbind is deprecated and should not be used in newly-written code.

xfce 4.18: In favor of GBinding

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);

exo_mutual_binding_new is deprecated and should not be used in newly-written code.

xfce 4.18: In favor of GBinding

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);

exo_mutual_binding_new_full is deprecated and should not be used in newly-written code.

xfce 4.18: In favor of GBinding

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);

exo_mutual_binding_new_with_negation is deprecated and should not be used in newly-written code.

xfce 4.18: In favor of GBinding

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);

exo_mutual_binding_unbind is deprecated and should not be used in newly-written code.

xfce 4.18: In favor of GBinding

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;

ExoBinding is deprecated and should not be used in newly-written code.

xfce 4.18: In favor of GBinding

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;

ExoMutualBinding is deprecated and should not be used in newly-written code.

xfce 4.18: In favor of GBinding

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