Copyright | Will Thompson and Iñaki García Etxebarria |
---|---|
License | LGPL-2.1 |
Maintainer | Iñaki García Etxebarria |
Safe Haskell | Safe-Inferred |
Language | Haskell2010 |
Binding
is the representation of a binding between a property on a
Object
instance (or source) and another property on another Object
instance (or target).
Whenever the source property changes, the same value is applied to the target property; for instance, the following binding:
C code
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 Object
instances, so that if either property changes, the
other is updated as well, for instance:
C code
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:
C code
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
celsiusToFahrenheit
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 fahrenheitToCelsius
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 Binding
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 Object::notify signal only
if the value has effectively been changed. A binding is implemented
using the Object::notify signal, so it is susceptible to all the
various ways of blocking a signal emission, like signalStopEmission
or signalHandlerBlock
.
A binding will be severed, and the resources it allocates freed, whenever
either one of the Object
instances it refers to are finalized, or when
the Binding
instance loses its last reference.
Bindings for languages with garbage collection can use
bindingUnbind
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.
Binding
is available since GObject 2.26
Since: 2.26
Synopsis
- newtype Binding = Binding (ManagedPtr Binding)
- class (GObject o, IsDescendantOf Binding o) => IsBinding o
- toBinding :: (MonadIO m, IsBinding o) => o -> m Binding
- bindingDupSource :: (HasCallStack, MonadIO m, IsBinding a) => a -> m (Maybe Object)
- bindingDupTarget :: (HasCallStack, MonadIO m, IsBinding a) => a -> m (Maybe Object)
- bindingGetFlags :: (HasCallStack, MonadIO m, IsBinding a) => a -> m [BindingFlags]
- bindingGetSource :: (HasCallStack, MonadIO m, IsBinding a) => a -> m (Maybe Object)
- bindingGetSourceProperty :: (HasCallStack, MonadIO m, IsBinding a) => a -> m Text
- bindingGetTarget :: (HasCallStack, MonadIO m, IsBinding a) => a -> m (Maybe Object)
- bindingGetTargetProperty :: (HasCallStack, MonadIO m, IsBinding a) => a -> m Text
- bindingUnbind :: (HasCallStack, MonadIO m, IsBinding a) => a -> m ()
- constructBindingFlags :: (IsBinding o, MonadIO m) => [BindingFlags] -> m (GValueConstruct o)
- getBindingFlags :: (MonadIO m, IsBinding o) => o -> m [BindingFlags]
- constructBindingSource :: (IsBinding o, MonadIO m, IsObject a) => a -> m (GValueConstruct o)
- getBindingSource :: (MonadIO m, IsBinding o) => o -> m (Maybe Object)
- constructBindingSourceProperty :: (IsBinding o, MonadIO m) => Text -> m (GValueConstruct o)
- getBindingSourceProperty :: (MonadIO m, IsBinding o) => o -> m Text
- constructBindingTarget :: (IsBinding o, MonadIO m, IsObject a) => a -> m (GValueConstruct o)
- getBindingTarget :: (MonadIO m, IsBinding o) => o -> m (Maybe Object)
- constructBindingTargetProperty :: (IsBinding o, MonadIO m) => Text -> m (GValueConstruct o)
- getBindingTargetProperty :: (MonadIO m, IsBinding o) => o -> m Text
Exported types
Memory-managed wrapper type.
Instances
Eq Binding Source # | |
GObject Binding Source # | |
Defined in GI.GObject.Objects.Binding | |
ManagedPtrNewtype Binding Source # | |
Defined in GI.GObject.Objects.Binding toManagedPtr :: Binding -> ManagedPtr Binding | |
TypedObject Binding Source # | |
Defined in GI.GObject.Objects.Binding | |
HasParentTypes Binding Source # | |
Defined in GI.GObject.Objects.Binding | |
IsGValue (Maybe Binding) Source # | Convert |
Defined in GI.GObject.Objects.Binding gvalueGType_ :: IO GType gvalueSet_ :: Ptr GValue -> Maybe Binding -> IO () gvalueGet_ :: Ptr GValue -> IO (Maybe Binding) | |
type ParentTypes Binding Source # | |
Defined in GI.GObject.Objects.Binding |
class (GObject o, IsDescendantOf Binding o) => IsBinding o Source #
Instances
(GObject o, IsDescendantOf Binding o) => IsBinding o Source # | |
Defined in GI.GObject.Objects.Binding |
Methods
Click to display all available methods, including inherited ones
Methods
bindProperty, bindPropertyFull, dupSource, dupTarget, forceFloating, freezeNotify, getv, isFloating, notify, notifyByPspec, ref, refSink, runDispose, stealData, stealQdata, thawNotify, unbind, unref, watchClosure.
Getters
getData, getFlags, getProperty, getQdata, getSource, getSourceProperty, getTarget, getTargetProperty.
Setters
dupSource
dupTarget
getFlags
:: (HasCallStack, MonadIO m, IsBinding a) | |
=> a |
|
-> m [BindingFlags] | Returns: the |
Retrieves the flags passed when constructing the Binding
.
Since: 2.26
getSource
:: (HasCallStack, MonadIO m, IsBinding a) | |
=> a |
|
-> m (Maybe Object) | Returns: the source |
Deprecated: (Since version 2.68)Use bindingDupSource
for a safer version of thisfunction.
Retrieves the Object
instance used as the source of the binding.
A Binding
can outlive the source Object
as the binding does not hold a
strong reference to the source. If the source is destroyed before the
binding then this function will return Nothing
.
Use bindingDupSource
if the source or binding are used from different
threads as otherwise the pointer returned from this function might become
invalid if the source is finalized from another thread in the meantime.
Since: 2.26
getSourceProperty
bindingGetSourceProperty Source #
:: (HasCallStack, MonadIO m, IsBinding a) | |
=> a |
|
-> m Text | Returns: the name of the source property |
Retrieves the name of the property of Binding:source used as the source of the binding.
Since: 2.26
getTarget
:: (HasCallStack, MonadIO m, IsBinding a) | |
=> a |
|
-> m (Maybe Object) | Returns: the target |
Deprecated: (Since version 2.68)Use bindingDupTarget
for a safer version of thisfunction.
Retrieves the Object
instance used as the target of the binding.
A Binding
can outlive the target Object
as the binding does not hold a
strong reference to the target. If the target is destroyed before the
binding then this function will return Nothing
.
Use bindingDupTarget
if the target or binding are used from different
threads as otherwise the pointer returned from this function might become
invalid if the target is finalized from another thread in the meantime.
Since: 2.26
getTargetProperty
bindingGetTargetProperty Source #
:: (HasCallStack, MonadIO m, IsBinding a) | |
=> a |
|
-> m Text | Returns: the name of the target property |
Retrieves the name of the property of Binding:target used as the target of the binding.
Since: 2.26
unbind
:: (HasCallStack, MonadIO m, IsBinding a) | |
=> a |
|
-> m () |
Explicitly releases the binding between the source and the target
property expressed by binding
.
This function will release the reference that is being held on
the binding
instance if the binding is still bound; if you want to hold on
to the Binding
instance after calling bindingUnbind
, you will need
to hold a reference to it.
Note however that this function does not take ownership of binding
, it
only unrefs the reference that was initially created by
objectBindProperty
and is owned by the binding.
Since: 2.38
Properties
flags
Flags to be used to control the Binding
Since: 2.26
constructBindingFlags :: (IsBinding o, MonadIO m) => [BindingFlags] -> m (GValueConstruct o) Source #
Construct a GValueConstruct
with valid value for the “flags
” property. This is rarely needed directly, but it is used by new
.
getBindingFlags :: (MonadIO m, IsBinding o) => o -> m [BindingFlags] Source #
Get the value of the “flags
” property.
When overloading is enabled, this is equivalent to
get
binding #flags
source
The Object
that should be used as the source of the binding
Since: 2.26
constructBindingSource :: (IsBinding o, MonadIO m, IsObject a) => a -> m (GValueConstruct o) Source #
Construct a GValueConstruct
with valid value for the “source
” property. This is rarely needed directly, but it is used by new
.
getBindingSource :: (MonadIO m, IsBinding o) => o -> m (Maybe Object) Source #
Get the value of the “source
” property.
When overloading is enabled, this is equivalent to
get
binding #source
sourceProperty
The name of the property of Binding:source that should be used as the source of the binding.
This should be in [canonical form][canonical-parameter-names] to get the best performance.
Since: 2.26
constructBindingSourceProperty :: (IsBinding o, MonadIO m) => Text -> m (GValueConstruct o) Source #
Construct a GValueConstruct
with valid value for the “source-property
” property. This is rarely needed directly, but it is used by new
.
getBindingSourceProperty :: (MonadIO m, IsBinding o) => o -> m Text Source #
Get the value of the “source-property
” property.
When overloading is enabled, this is equivalent to
get
binding #sourceProperty
target
The Object
that should be used as the target of the binding
Since: 2.26
constructBindingTarget :: (IsBinding o, MonadIO m, IsObject a) => a -> m (GValueConstruct o) Source #
Construct a GValueConstruct
with valid value for the “target
” property. This is rarely needed directly, but it is used by new
.
getBindingTarget :: (MonadIO m, IsBinding o) => o -> m (Maybe Object) Source #
Get the value of the “target
” property.
When overloading is enabled, this is equivalent to
get
binding #target
targetProperty
The name of the property of Binding:target that should be used as the target of the binding.
This should be in [canonical form][canonical-parameter-names] to get the best performance.
Since: 2.26
constructBindingTargetProperty :: (IsBinding o, MonadIO m) => Text -> m (GValueConstruct o) Source #
Construct a GValueConstruct
with valid value for the “target-property
” property. This is rarely needed directly, but it is used by new
.
getBindingTargetProperty :: (MonadIO m, IsBinding o) => o -> m Text Source #
Get the value of the “target-property
” property.
When overloading is enabled, this is equivalent to
get
binding #targetProperty