glib/gobject/auto/

binding.rs

// This file was generated by gir (https://github.com/gtk-rs/gir)
// from gir-files (https://github.com/gtk-rs/gir-files)
// DO NOT EDIT

use crate::{ffi, translate::*, BindingFlags};

crate::wrapper! {
    /// `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 ⚠️**
    ///
    /// ```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 [method[`Object`][crate::Object]] 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 ⚠️**
    ///
    /// ```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 ⚠️**
    ///
    /// ```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 [`Binding`][crate::Binding] does not resolve cycles by itself; a cycle like
    ///
    /// ```text
    ///   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[`Object`][crate::Object]]
    /// or [func[`Object`][crate::Object]].
    ///
    /// 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 [`Binding`][crate::Binding] instance loses its last reference.
    ///
    /// Bindings for languages with garbage collection can use
    /// [method[`Object`][crate::Object].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.
    ///
    /// ## Properties
    ///
    ///
    /// #### `flags`
    ///  Flags to be used to control the [`Binding`][crate::Binding]
    ///
    /// Readable | Writeable | Construct Only
    ///
    ///
    /// #### `source`
    ///  The [`Object`][crate::Object] that should be used as the source of the binding
    ///
    /// Readable | Writeable | Construct Only
    ///
    ///
    /// #### `source-property`
    ///  The name of the property of [`source`][struct@crate::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.
    ///
    /// Readable | Writeable | Construct Only
    ///
    ///
    /// #### `target`
    ///  The [`Object`][crate::Object] that should be used as the target of the binding
    ///
    /// Readable | Writeable | Construct Only
    ///
    ///
    /// #### `target-property`
    ///  The name of the property of [`target`][struct@crate::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.
    ///
    /// Readable | Writeable | Construct Only
    ///
    /// # Implements
    ///
    /// [`ObjectExt`][trait@crate::prelude::ObjectExt]
    #[doc(alias = "GBinding")]
    pub struct Binding(Object<crate::gobject_ffi::GBinding>);

    match fn {
        type_ => || crate::gobject_ffi::g_binding_get_type(),
    }
}

impl Binding {
    /// Retrieves the flags passed when constructing the [`Binding`][crate::Binding].
    ///
    /// # Returns
    ///
    /// the [`BindingFlags`][crate::BindingFlags] used by the [`Binding`][crate::Binding]
    #[doc(alias = "g_binding_get_flags")]
    #[doc(alias = "get_flags")]
    pub fn flags(&self) -> BindingFlags {
        unsafe {
            from_glib(crate::gobject_ffi::g_binding_get_flags(
                self.to_glib_none().0,
            ))
        }
    }

    /// Retrieves the name of the property of [`source`][struct@crate::Binding#source] used as the source
    /// of the binding.
    ///
    /// # Returns
    ///
    /// the name of the source property
    #[doc(alias = "g_binding_get_source_property")]
    #[doc(alias = "get_source_property")]
    #[doc(alias = "source-property")]
    pub fn source_property(&self) -> crate::GString {
        unsafe {
            from_glib_none(crate::gobject_ffi::g_binding_get_source_property(
                self.to_glib_none().0,
            ))
        }
    }

    /// Retrieves the name of the property of [`target`][struct@crate::Binding#target] used as the target
    /// of the binding.
    ///
    /// # Returns
    ///
    /// the name of the target property
    #[doc(alias = "g_binding_get_target_property")]
    #[doc(alias = "get_target_property")]
    #[doc(alias = "target-property")]
    pub fn target_property(&self) -> crate::GString {
        unsafe {
            from_glib_none(crate::gobject_ffi::g_binding_get_target_property(
                self.to_glib_none().0,
            ))
        }
    }

    /// Explicitly releases the binding between the source and the target
    /// property expressed by `self`.
    ///
    /// This function will release the reference that is being held on
    /// the `self` instance if the binding is still bound; if you want to hold on
    /// to the [`Binding`][crate::Binding] instance after calling [`unbind()`][Self::unbind()], you will need
    /// to hold a reference to it.
    ///
    /// Note however that this function does not take ownership of `self`, it
    /// only unrefs the reference that was initially created by
    /// [`ObjectExt::bind_property()`][crate::prelude::ObjectExt::bind_property()] and is owned by the binding.
    #[doc(alias = "g_binding_unbind")]
    pub fn unbind(&self) {
        unsafe {
            crate::gobject_ffi::g_binding_unbind(self.to_glib_none().0);
        }
    }
}

unsafe impl Send for Binding {}
unsafe impl Sync for Binding {}