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 #[doc(alias = "GBinding")]
134 pub struct Binding(Object<crate::gobject_ffi::GBinding>);
135
136 match fn {
137 type_ => || crate::gobject_ffi::g_binding_get_type(),
138 }
139}
140
141impl Binding {
142 /// Retrieves the flags passed when constructing the [`Binding`][crate::Binding].
143 ///
144 /// # Returns
145 ///
146 /// the [`BindingFlags`][crate::BindingFlags] used by the [`Binding`][crate::Binding]
147 #[doc(alias = "g_binding_get_flags")]
148 #[doc(alias = "get_flags")]
149 pub fn flags(&self) -> BindingFlags {
150 unsafe {
151 from_glib(crate::gobject_ffi::g_binding_get_flags(
152 self.to_glib_none().0,
153 ))
154 }
155 }
156
157 /// Retrieves the name of the property of [`source`][struct@crate::Binding#source] used as the source
158 /// of the binding.
159 ///
160 /// # Returns
161 ///
162 /// the name of the source property
163 #[doc(alias = "g_binding_get_source_property")]
164 #[doc(alias = "get_source_property")]
165 #[doc(alias = "source-property")]
166 pub fn source_property(&self) -> crate::GString {
167 unsafe {
168 from_glib_none(crate::gobject_ffi::g_binding_get_source_property(
169 self.to_glib_none().0,
170 ))
171 }
172 }
173
174 /// Retrieves the name of the property of [`target`][struct@crate::Binding#target] used as the target
175 /// of the binding.
176 ///
177 /// # Returns
178 ///
179 /// the name of the target property
180 #[doc(alias = "g_binding_get_target_property")]
181 #[doc(alias = "get_target_property")]
182 #[doc(alias = "target-property")]
183 pub fn target_property(&self) -> crate::GString {
184 unsafe {
185 from_glib_none(crate::gobject_ffi::g_binding_get_target_property(
186 self.to_glib_none().0,
187 ))
188 }
189 }
190
191 /// Explicitly releases the binding between the source and the target
192 /// property expressed by `self`.
193 ///
194 /// This function will release the reference that is being held on
195 /// the `self` instance if the binding is still bound; if you want to hold on
196 /// to the [`Binding`][crate::Binding] instance after calling [`unbind()`][Self::unbind()], you will need
197 /// to hold a reference to it.
198 ///
199 /// Note however that this function does not take ownership of `self`, it
200 /// only unrefs the reference that was initially created by
201 /// [`ObjectExt::bind_property()`][crate::prelude::ObjectExt::bind_property()] and is owned by the binding.
202 #[doc(alias = "g_binding_unbind")]
203 pub fn unbind(&self) {
204 unsafe {
205 crate::gobject_ffi::g_binding_unbind(self.to_glib_none().0);
206 }
207 }
208}
209
210unsafe impl Send for Binding {}
211unsafe impl Sync for Binding {}