Class

GObjectBinding

Description [src]

final class GObject.Binding : GObject.Object {
  /* No available fields */
}

GBinding is the representation of a binding between a property on a 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:

  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 g_object_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:

  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 g_signal_stop_emission() or g_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 g_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.

GBinding is available since GObject 2.26

Available since:2.26

Hierarchy

hierarchy this GBinding ancestor_0 GObject ancestor_0--this

Ancestors

Instance methods

g_binding_dup_source

Retrieves the GObject instance used as the source of the binding.

Available since: 2.68

g_binding_dup_target

Retrieves the GObject instance used as the target of the binding.

Available since: 2.68

g_binding_get_flags

Retrieves the flags passed when constructing the GBinding.

Available since: 2.26

g_binding_get_source

Retrieves the GObject instance used as the source of the binding.

Available since: 2.26

Deprecated since: 2.68

g_binding_get_source_property

Retrieves the name of the property of GBinding:source used as the source of the binding.

Available since: 2.26

g_binding_get_target

Retrieves the GObject instance used as the target of the binding.

Available since: 2.26

Deprecated since: 2.68

g_binding_get_target_property

Retrieves the name of the property of GBinding:target used as the target of the binding.

Available since: 2.26

g_binding_unbind

Explicitly releases the binding between the source and the target property expressed by binding.

Available since: 2.38

Methods inherited from GObject (43)
g_object_add_toggle_ref

Increases the reference count of the object by one and sets a callback to be called when all other references to the object are dropped, or when this is already the last reference to the object and another reference is established.

Available since: 2.8

g_object_add_weak_pointer

Adds a weak reference from weak_pointer to object to indicate that the pointer located at weak_pointer_location is only valid during the lifetime of object. When the object is finalized, weak_pointer will be set to NULL.

g_object_bind_property

Creates a binding between source_property on source and target_property on target.

Available since: 2.26

g_object_bind_property_full

Complete version of g_object_bind_property().

Available since: 2.26

g_object_bind_property_with_closures

Creates a binding between source_property on source and target_property on target, allowing you to set the transformation functions to be used by the binding.

Available since: 2.26

g_object_connect

A convenience function to connect multiple signals at once.

g_object_disconnect

A convenience function to disconnect multiple signals at once.

g_object_dup_data

This is a variant of g_object_get_data() which returns a ‘duplicate’ of the value. dup_func defines the meaning of ‘duplicate’ in this context, it could e.g. take a reference on a ref-counted object.

Available since: 2.34

g_object_dup_qdata

This is a variant of g_object_get_qdata() which returns a ‘duplicate’ of the value. dup_func defines the meaning of ‘duplicate’ in this context, it could e.g. take a reference on a ref-counted object.

Available since: 2.34

g_object_force_floating

This function is intended for GObject implementations to re-enforce a [floating][floating-ref] object reference. Doing this is seldom required: all GInitiallyUnowneds are created with a floating reference which usually just needs to be sunken by calling g_object_ref_sink().

Available since: 2.10

g_object_freeze_notify

Increases the freeze count on object. If the freeze count is non-zero, the emission of “notify” signals on object is stopped. The signals are queued until the freeze count is decreased to zero. Duplicate notifications are squashed so that at most one GObject::notify signal is emitted for each property modified while the object is frozen.

g_object_get

Gets properties of an object.

g_object_get_data

Gets a named field from the objects table of associations (see g_object_set_data()).

g_object_get_property

Gets a property of an object.

g_object_get_qdata

This function gets back user data pointers stored via g_object_set_qdata().

g_object_get_valist

Gets properties of an object.

g_object_getv

Gets n_properties properties for an object. Obtained properties will be set to values. All properties must be valid. Warnings will be emitted and undefined behaviour may result if invalid properties are passed in.

Available since: 2.54

g_object_is_floating

Checks whether object has a [floating][floating-ref] reference.

Available since: 2.10

g_object_notify

Emits a “notify” signal for the property property_name on object.

g_object_notify_by_pspec

Emits a “notify” signal for the property specified by pspec on object.

Available since: 2.26

g_object_ref

Increases the reference count of object.

g_object_ref_sink

Increase the reference count of object, and possibly remove the [floating][floating-ref] reference, if object has a floating reference.

Available since: 2.10

g_object_remove_toggle_ref

Removes a reference added with g_object_add_toggle_ref(). The reference count of the object is decreased by one.

Available since: 2.8

Properties

GObject.Binding:flags

Flags to be used to control the GBinding.

Available since: 2.26

GObject.Binding:source

The GObject that should be used as the source of the binding.

Available since: 2.26

GObject.Binding:source-property

The name of the property of GBinding:source that should be used as the source of the binding.

Available since: 2.26

GObject.Binding:target

The GObject that should be used as the target of the binding.

Available since: 2.26

GObject.Binding:target-property

The name of the property of GBinding:target that should be used as the target of the binding.

Available since: 2.26

Signals

Signals inherited from GObject (1)
GObject.Object::notify

The notify signal is emitted on an object when one of its properties has its value set through g_object_set_property(), g_object_set(), et al.