gobject.binding

[gobject.object.ObjectWrap] instance (or source) and another property on another [gobject.object.ObjectWrap] instance (or target).

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

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 method@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.object.ObjectWrap] instances, so that if either property changes, the other is updated as well, for instance:

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:

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 func@GObject.signal_stop_emission or func@GObject.signal_handler_block.

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

Bindings for languages with garbage collection can use [gobject.binding.Binding.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.

Fluent builder for [gobject.binding.Binding]