// 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::translate::*;
use crate::BindingFlags;
use std::fmt;

crate::wrapper! {
    /// [`Binding`][crate::Binding] is the representation of a binding between a property on a
    /// [`Object`][crate::Object] instance (or source) and another property on another [`Object`][crate::Object]
    /// 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 [`ObjectExtManual::set()`][crate::prelude::ObjectExtManual::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`][crate::Object] 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 `signal::Object::notify` signal only
    /// if the value has effectively been changed. A binding is implemented
    /// using the `signal::Object::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 [`Object`][crate::Object] 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
    /// [`unbind()`][Self::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.
    ///
    /// [`Binding`][crate::Binding] is available since GObject 2.26
    ///
    /// # Implements
    ///
    /// [`ObjectExt`][trait@crate::prelude::ObjectExt]
    #[doc(alias = "GBinding")]
    pub struct Binding(Object<gobject_ffi::GBinding>);

    match fn {
        type_ => || 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]
    // rustdoc-stripper-ignore-next-stop
    /// Flags to be used to control the [`Binding`][crate::Binding]
    #[doc(alias = "g_binding_get_flags")]
    #[doc(alias = "get_flags")]
    pub fn flags(&self) -> BindingFlags {
        unsafe { from_glib(gobject_ffi::g_binding_get_flags(self.to_glib_none().0)) }
    }

    /// Retrieves the name of the property of `property::Binding::source` used as the source
    /// of the binding.
    ///
    /// # Returns
    ///
    /// the name of the source property
    // rustdoc-stripper-ignore-next-stop
    /// The name of the property of `property::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.
    #[doc(alias = "g_binding_get_source_property")]
    #[doc(alias = "get_source_property")]
    pub fn source_property(&self) -> crate::GString {
        unsafe {
            from_glib_none(gobject_ffi::g_binding_get_source_property(
                self.to_glib_none().0,
            ))
        }
    }

    /// Retrieves the name of the property of `property::Binding::target` used as the target
    /// of the binding.
    ///
    /// # Returns
    ///
    /// the name of the target property
    // rustdoc-stripper-ignore-next-stop
    /// The name of the property of `property::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.
    #[doc(alias = "g_binding_get_target_property")]
    #[doc(alias = "get_target_property")]
    pub fn target_property(&self) -> crate::GString {
        unsafe {
            from_glib_none(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
    /// [`ObjectExtManual::bind_property()`][crate::prelude::ObjectExtManual::bind_property()] and is owned by the binding.
    #[doc(alias = "g_binding_unbind")]
    pub fn unbind(&self) {
        unsafe {
            gobject_ffi::g_binding_unbind(self.to_glib_none().0);
        }
    }
}

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

impl fmt::Display for Binding {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        f.write_str("Binding")
    }
}