1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
// 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::*, 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 [`ObjectExt::set()`][crate::prelude::ObjectExt::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 [`notify`][struct@crate::Object#notify] signal only
    /// if the value has effectively been changed. A binding is implemented
    /// using the [`notify`][struct@crate::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
    ///
    /// ## 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<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]
    #[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 [`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")]
    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 [`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")]
    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
    /// [`ObjectExt::bind_property()`][crate::prelude::ObjectExt::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")
    }
}