Struct Binding

Source

pub struct Binding { /* private fields */ }

Expand description

GObject instance (or source) and another property on another GObject instance (or target).

Whenever the source property changes, the same value is applied to the target property; for instance, the following binding:

⚠️ The following code is in c ⚠️

  g_object_bind_property (object1, "property-a",
                          object2, "property-b",
                          G_BINDING_DEFAULT);

will cause the property named “property-b” of @object2 to be updated every time GObject::set() or the specific accessor changes the value of the property “property-a” of @object1.

It is possible to create a bidirectional binding between two properties of two GObject instances, so that if either property changes, the other is updated as well, for instance:

⚠️ The following code is in c ⚠️

  g_object_bind_property (object1, "property-a",
                          object2, "property-b",
                          G_BINDING_BIDIRECTIONAL);

will keep the two properties in sync.

It is also possible to set a custom transformation function (in both directions, in case of a bidirectional binding) to apply a custom transformation from the source value to the target value before applying it; for instance, the following binding:

⚠️ The following code is in c ⚠️

  g_object_bind_property_full (adjustment1, "value",
                               adjustment2, "value",
                               G_BINDING_BIDIRECTIONAL,
                               celsius_to_fahrenheit,
                               fahrenheit_to_celsius,
                               NULL, NULL);

will keep the “value” property of the two adjustments in sync; the @celsius_to_fahrenheit function will be called whenever the “value” property of @adjustment1 changes and will transform the current value of the property before applying it to the “value” property of @adjustment2.

Vice versa, the @fahrenheit_to_celsius function will be called whenever the “value” property of @adjustment2 changes, and will transform the current value of the property before applying it to the “value” property of @adjustment1.

Note that #GBinding does not resolve cycles by itself; a cycle like

  object1:propertyA -> object2:propertyB
  object2:propertyB -> object3:propertyC
  object3:propertyC -> object1:propertyA

might lead to an infinite loop. The loop, in this particular case, can be avoided if the objects emit the GObject::notify signal only if the value has effectively been changed. A binding is implemented using the GObject::notify signal, so it is susceptible to all the various ways of blocking a signal emission, like signal_stop_emission() or signal_handler_block().

A binding will be severed, and the resources it allocates freed, whenever either one of the GObject instances it refers to are finalized, or when the #GBinding instance loses its last reference.

Bindings for languages with garbage collection can use unbind() to explicitly release a binding between the source and target properties, instead of relying on the last reference on the binding, source, and target instances to drop.