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 {}