glib/gobject/auto/
binding.rs

1// This file was generated by gir (https://github.com/gtk-rs/gir)
2// from gir-files (https://github.com/gtk-rs/gir-files)
3// DO NOT EDIT
4
5use crate::{ffi, translate::*, BindingFlags};
6
7crate::wrapper! {
8    /// `GObject` instance (or source) and another property on another `GObject`
9    /// instance (or target).
10    ///
11    /// Whenever the source property changes, the same value is applied to the
12    /// target property; for instance, the following binding:
13    ///
14    /// **⚠️ The following code is in c ⚠️**
15    ///
16    /// ```c
17    ///   g_object_bind_property (object1, "property-a",
18    ///                           object2, "property-b",
19    ///                           G_BINDING_DEFAULT);
20    /// ```
21    ///
22    /// will cause the property named "property-b" of `object2` to be updated
23    /// every time [method[`Object`][crate::Object]] or the specific accessor changes the value of
24    /// the property "property-a" of `object1`.
25    ///
26    /// It is possible to create a bidirectional binding between two properties
27    /// of two `GObject` instances, so that if either property changes, the
28    /// other is updated as well, for instance:
29    ///
30    /// **⚠️ The following code is in c ⚠️**
31    ///
32    /// ```c
33    ///   g_object_bind_property (object1, "property-a",
34    ///                           object2, "property-b",
35    ///                           G_BINDING_BIDIRECTIONAL);
36    /// ```
37    ///
38    /// will keep the two properties in sync.
39    ///
40    /// It is also possible to set a custom transformation function (in both
41    /// directions, in case of a bidirectional binding) to apply a custom
42    /// transformation from the source value to the target value before
43    /// applying it; for instance, the following binding:
44    ///
45    /// **⚠️ The following code is in c ⚠️**
46    ///
47    /// ```c
48    ///   g_object_bind_property_full (adjustment1, "value",
49    ///                                adjustment2, "value",
50    ///                                G_BINDING_BIDIRECTIONAL,
51    ///                                celsius_to_fahrenheit,
52    ///                                fahrenheit_to_celsius,
53    ///                                NULL, NULL);
54    /// ```
55    ///
56    /// will keep the "value" property of the two adjustments in sync; the
57    /// `celsius_to_fahrenheit` function will be called whenever the "value"
58    /// property of `adjustment1` changes and will transform the current value
59    /// of the property before applying it to the "value" property of `adjustment2`.
60    ///
61    /// Vice versa, the `fahrenheit_to_celsius` function will be called whenever
62    /// the "value" property of `adjustment2` changes, and will transform the
63    /// current value of the property before applying it to the "value" property
64    /// of `adjustment1`.
65    ///
66    /// Note that [`Binding`][crate::Binding] does not resolve cycles by itself; a cycle like
67    ///
68    /// ```text
69    ///   object1:propertyA -> object2:propertyB
70    ///   object2:propertyB -> object3:propertyC
71    ///   object3:propertyC -> object1:propertyA
72    /// ```
73    ///
74    /// might lead to an infinite loop. The loop, in this particular case,
75    /// can be avoided if the objects emit the `GObject::notify` signal only
76    /// if the value has effectively been changed. A binding is implemented
77    /// using the `GObject::notify` signal, so it is susceptible to all the
78    /// various ways of blocking a signal emission, like [func[`Object`][crate::Object]]
79    /// or [func[`Object`][crate::Object]].
80    ///
81    /// A binding will be severed, and the resources it allocates freed, whenever
82    /// either one of the `GObject` instances it refers to are finalized, or when
83    /// the [`Binding`][crate::Binding] instance loses its last reference.
84    ///
85    /// Bindings for languages with garbage collection can use
86    /// [method[`Object`][crate::Object].unbind] to explicitly release a binding between the source
87    /// and target properties, instead of relying on the last reference on the
88    /// binding, source, and target instances to drop.
89    ///
90    /// ## Properties
91    ///
92    ///
93    /// #### `flags`
94    ///  Flags to be used to control the [`Binding`][crate::Binding]
95    ///
96    /// Readable | Writeable | Construct Only
97    ///
98    ///
99    /// #### `source`
100    ///  The [`Object`][crate::Object] that should be used as the source of the binding
101    ///
102    /// Readable | Writeable | Construct Only
103    ///
104    ///
105    /// #### `source-property`
106    ///  The name of the property of [`source`][struct@crate::Binding#source] that should be used
107    /// as the source of the binding.
108    ///
109    /// This should be in [canonical form][canonical-parameter-names] to get the
110    /// best performance.
111    ///
112    /// Readable | Writeable | Construct Only
113    ///
114    ///
115    /// #### `target`
116    ///  The [`Object`][crate::Object] that should be used as the target of the binding
117    ///
118    /// Readable | Writeable | Construct Only
119    ///
120    ///
121    /// #### `target-property`
122    ///  The name of the property of [`target`][struct@crate::Binding#target] that should be used
123    /// as the target of the binding.
124    ///
125    /// This should be in [canonical form][canonical-parameter-names] to get the
126    /// best performance.
127    ///
128    /// Readable | Writeable | Construct Only
129    ///
130    /// # Implements
131    ///
132    /// [`ObjectExt`][trait@crate::prelude::ObjectExt]
133    // rustdoc-stripper-ignore-next-stop
134    /// `GObject` instance (or source) and another property on another `GObject`
135    /// instance (or target).
136    ///
137    /// Whenever the source property changes, the same value is applied to the
138    /// target property; for instance, the following binding:
139    ///
140    /// **⚠️ The following code is in c ⚠️**
141    ///
142    /// ```c
143    ///   g_object_bind_property (object1, "property-a",
144    ///                           object2, "property-b",
145    ///                           G_BINDING_DEFAULT);
146    /// ```
147    ///
148    /// will cause the property named "property-b" of `object2` to be updated
149    /// every time [method[`Object`][crate::Object]] or the specific accessor changes the value of
150    /// the property "property-a" of `object1`.
151    ///
152    /// It is possible to create a bidirectional binding between two properties
153    /// of two `GObject` instances, so that if either property changes, the
154    /// other is updated as well, for instance:
155    ///
156    /// **⚠️ The following code is in c ⚠️**
157    ///
158    /// ```c
159    ///   g_object_bind_property (object1, "property-a",
160    ///                           object2, "property-b",
161    ///                           G_BINDING_BIDIRECTIONAL);
162    /// ```
163    ///
164    /// will keep the two properties in sync.
165    ///
166    /// It is also possible to set a custom transformation function (in both
167    /// directions, in case of a bidirectional binding) to apply a custom
168    /// transformation from the source value to the target value before
169    /// applying it; for instance, the following binding:
170    ///
171    /// **⚠️ The following code is in c ⚠️**
172    ///
173    /// ```c
174    ///   g_object_bind_property_full (adjustment1, "value",
175    ///                                adjustment2, "value",
176    ///                                G_BINDING_BIDIRECTIONAL,
177    ///                                celsius_to_fahrenheit,
178    ///                                fahrenheit_to_celsius,
179    ///                                NULL, NULL);
180    /// ```
181    ///
182    /// will keep the "value" property of the two adjustments in sync; the
183    /// `celsius_to_fahrenheit` function will be called whenever the "value"
184    /// property of `adjustment1` changes and will transform the current value
185    /// of the property before applying it to the "value" property of `adjustment2`.
186    ///
187    /// Vice versa, the `fahrenheit_to_celsius` function will be called whenever
188    /// the "value" property of `adjustment2` changes, and will transform the
189    /// current value of the property before applying it to the "value" property
190    /// of `adjustment1`.
191    ///
192    /// Note that [`Binding`][crate::Binding] does not resolve cycles by itself; a cycle like
193    ///
194    /// ```text
195    ///   object1:propertyA -> object2:propertyB
196    ///   object2:propertyB -> object3:propertyC
197    ///   object3:propertyC -> object1:propertyA
198    /// ```
199    ///
200    /// might lead to an infinite loop. The loop, in this particular case,
201    /// can be avoided if the objects emit the `GObject::notify` signal only
202    /// if the value has effectively been changed. A binding is implemented
203    /// using the `GObject::notify` signal, so it is susceptible to all the
204    /// various ways of blocking a signal emission, like [func[`Object`][crate::Object]]
205    /// or [func[`Object`][crate::Object]].
206    ///
207    /// A binding will be severed, and the resources it allocates freed, whenever
208    /// either one of the `GObject` instances it refers to are finalized, or when
209    /// the [`Binding`][crate::Binding] instance loses its last reference.
210    ///
211    /// Bindings for languages with garbage collection can use
212    /// [method[`Object`][crate::Object].unbind] to explicitly release a binding between the source
213    /// and target properties, instead of relying on the last reference on the
214    /// binding, source, and target instances to drop.
215    ///
216    /// ## Properties
217    ///
218    ///
219    /// #### `flags`
220    ///  Flags to be used to control the [`Binding`][crate::Binding]
221    ///
222    /// Readable | Writeable | Construct Only
223    ///
224    ///
225    /// #### `source`
226    ///  The [`Object`][crate::Object] that should be used as the source of the binding
227    ///
228    /// Readable | Writeable | Construct Only
229    ///
230    ///
231    /// #### `source-property`
232    ///  The name of the property of [`source`][struct@crate::Binding#source] that should be used
233    /// as the source of the binding.
234    ///
235    /// This should be in [canonical form][canonical-parameter-names] to get the
236    /// best performance.
237    ///
238    /// Readable | Writeable | Construct Only
239    ///
240    ///
241    /// #### `target`
242    ///  The [`Object`][crate::Object] that should be used as the target of the binding
243    ///
244    /// Readable | Writeable | Construct Only
245    ///
246    ///
247    /// #### `target-property`
248    ///  The name of the property of [`target`][struct@crate::Binding#target] that should be used
249    /// as the target of the binding.
250    ///
251    /// This should be in [canonical form][canonical-parameter-names] to get the
252    /// best performance.
253    ///
254    /// Readable | Writeable | Construct Only
255    ///
256    /// # Implements
257    ///
258    /// [`ObjectExt`][trait@crate::prelude::ObjectExt]
259    #[doc(alias = "GBinding")]
260    pub struct Binding(Object<crate::gobject_ffi::GBinding>);
261
262    match fn {
263        type_ => || crate::gobject_ffi::g_binding_get_type(),
264    }
265}
266
267impl Binding {
268    /// Retrieves the flags passed when constructing the [`Binding`][crate::Binding].
269    ///
270    /// # Returns
271    ///
272    /// the [`BindingFlags`][crate::BindingFlags] used by the [`Binding`][crate::Binding]
273    // rustdoc-stripper-ignore-next-stop
274    /// Retrieves the flags passed when constructing the [`Binding`][crate::Binding].
275    ///
276    /// # Returns
277    ///
278    /// the [`BindingFlags`][crate::BindingFlags] used by the [`Binding`][crate::Binding]
279    #[doc(alias = "g_binding_get_flags")]
280    #[doc(alias = "get_flags")]
281    pub fn flags(&self) -> BindingFlags {
282        unsafe {
283            from_glib(crate::gobject_ffi::g_binding_get_flags(
284                self.to_glib_none().0,
285            ))
286        }
287    }
288
289    /// Retrieves the name of the property of [`source`][struct@crate::Binding#source] used as the source
290    /// of the binding.
291    ///
292    /// # Returns
293    ///
294    /// the name of the source property
295    // rustdoc-stripper-ignore-next-stop
296    /// Retrieves the name of the property of [`source`][struct@crate::Binding#source] used as the source
297    /// of the binding.
298    ///
299    /// # Returns
300    ///
301    /// the name of the source property
302    #[doc(alias = "g_binding_get_source_property")]
303    #[doc(alias = "get_source_property")]
304    #[doc(alias = "source-property")]
305    pub fn source_property(&self) -> crate::GString {
306        unsafe {
307            from_glib_none(crate::gobject_ffi::g_binding_get_source_property(
308                self.to_glib_none().0,
309            ))
310        }
311    }
312
313    /// Retrieves the name of the property of [`target`][struct@crate::Binding#target] used as the target
314    /// of the binding.
315    ///
316    /// # Returns
317    ///
318    /// the name of the target property
319    // rustdoc-stripper-ignore-next-stop
320    /// Retrieves the name of the property of [`target`][struct@crate::Binding#target] used as the target
321    /// of the binding.
322    ///
323    /// # Returns
324    ///
325    /// the name of the target property
326    #[doc(alias = "g_binding_get_target_property")]
327    #[doc(alias = "get_target_property")]
328    #[doc(alias = "target-property")]
329    pub fn target_property(&self) -> crate::GString {
330        unsafe {
331            from_glib_none(crate::gobject_ffi::g_binding_get_target_property(
332                self.to_glib_none().0,
333            ))
334        }
335    }
336
337    /// Explicitly releases the binding between the source and the target
338    /// property expressed by `self`.
339    ///
340    /// This function will release the reference that is being held on
341    /// the `self` instance if the binding is still bound; if you want to hold on
342    /// to the [`Binding`][crate::Binding] instance after calling [`unbind()`][Self::unbind()], you will need
343    /// to hold a reference to it.
344    ///
345    /// Note however that this function does not take ownership of `self`, it
346    /// only unrefs the reference that was initially created by
347    /// [`ObjectExt::bind_property()`][crate::prelude::ObjectExt::bind_property()] and is owned by the binding.
348    // rustdoc-stripper-ignore-next-stop
349    /// Explicitly releases the binding between the source and the target
350    /// property expressed by `self`.
351    ///
352    /// This function will release the reference that is being held on
353    /// the `self` instance if the binding is still bound; if you want to hold on
354    /// to the [`Binding`][crate::Binding] instance after calling [`unbind()`][Self::unbind()], you will need
355    /// to hold a reference to it.
356    ///
357    /// Note however that this function does not take ownership of `self`, it
358    /// only unrefs the reference that was initially created by
359    /// [`ObjectExt::bind_property()`][crate::prelude::ObjectExt::bind_property()] and is owned by the binding.
360    #[doc(alias = "g_binding_unbind")]
361    pub fn unbind(&self) {
362        unsafe {
363            crate::gobject_ffi::g_binding_unbind(self.to_glib_none().0);
364        }
365    }
366}
367
368unsafe impl Send for Binding {}
369unsafe impl Sync for Binding {}