gio/auto/property_action.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, Action};
6use glib::{prelude::*, translate::*};
7
8glib::wrapper! {
9 /// A `GPropertyAction` is a way to get a [`Action`][crate::Action] with a state value
10 /// reflecting and controlling the value of a [`glib::Object`][crate::glib::Object] property.
11 ///
12 /// The state of the action will correspond to the value of the property.
13 /// Changing it will change the property (assuming the requested value
14 /// matches the requirements as specified in the [type@GObject.ParamSpec]).
15 ///
16 /// Only the most common types are presently supported. Booleans are
17 /// mapped to booleans, strings to strings, signed/unsigned integers to
18 /// int32/uint32 and floats and doubles to doubles.
19 ///
20 /// If the property is an enum then the state will be string-typed and
21 /// conversion will automatically be performed between the enum value and
22 /// ‘nick’ string as per the [type@GObject.EnumValue] table.
23 ///
24 /// Flags types are not currently supported.
25 ///
26 /// Properties of object types, boxed types and pointer types are not
27 /// supported and probably never will be.
28 ///
29 /// Properties of [type@GLib.Variant] types are not currently supported.
30 ///
31 /// If the property is boolean-valued then the action will have a `NULL`
32 /// parameter type, and activating the action (with no parameter) will
33 /// toggle the value of the property.
34 ///
35 /// In all other cases, the parameter type will correspond to the type of
36 /// the property.
37 ///
38 /// The general idea here is to reduce the number of locations where a
39 /// particular piece of state is kept (and therefore has to be synchronised
40 /// between). `GPropertyAction` does not have a separate state that is kept
41 /// in sync with the property value — its state is the property value.
42 ///
43 /// For example, it might be useful to create a [`Action`][crate::Action] corresponding
44 /// to the `visible-child-name` property of a [`GtkStack`](https://docs.gtk.org/gtk4/class.Stack.html)
45 /// so that the current page can be switched from a menu. The active radio
46 /// indication in the menu is then directly determined from the active page of
47 /// the `GtkStack`.
48 ///
49 /// An anti-example would be binding the `active-id` property on a
50 /// [`GtkComboBox`](https://docs.gtk.org/gtk4/class.ComboBox.html). This is
51 /// because the state of the combo box itself is probably uninteresting and is
52 /// actually being used to control something else.
53 ///
54 /// Another anti-example would be to bind to the `visible-child-name`
55 /// property of a [`GtkStack`](https://docs.gtk.org/gtk4/class.Stack.html) if
56 /// this value is actually stored in [`Settings`][crate::Settings]. In that case, the
57 /// real source of the value is* [`Settings`][crate::Settings]. If you want
58 /// a [`Action`][crate::Action] to control a setting stored in [`Settings`][crate::Settings],
59 /// see [`SettingsExt::create_action()`][crate::prelude::SettingsExt::create_action()] instead, and possibly combine its
60 /// use with [`SettingsExtManual::bind()`][crate::prelude::SettingsExtManual::bind()].
61 ///
62 /// ## Properties
63 ///
64 ///
65 /// #### `enabled`
66 /// If @action is currently enabled.
67 ///
68 /// If the action is disabled then calls to g_action_activate() and
69 /// g_action_change_state() have no effect.
70 ///
71 /// Readable
72 ///
73 ///
74 /// #### `invert-boolean`
75 /// If [`true`], the state of the action will be the negation of the
76 /// property value, provided the property is boolean.
77 ///
78 /// Readable | Writeable | Construct Only
79 ///
80 ///
81 /// #### `name`
82 /// The name of the action. This is mostly meaningful for identifying
83 /// the action once it has been added to a #GActionMap.
84 ///
85 /// Readable | Writeable | Construct Only
86 ///
87 ///
88 /// #### `object`
89 /// The object to wrap a property on.
90 ///
91 /// The object must be a non-[`None`] #GObject with properties.
92 ///
93 /// Writeable | Construct Only
94 ///
95 ///
96 /// #### `parameter-type`
97 /// The type of the parameter that must be given when activating the
98 /// action.
99 ///
100 /// Readable
101 ///
102 ///
103 /// #### `property-name`
104 /// The name of the property to wrap on the object.
105 ///
106 /// The property must exist on the passed-in object and it must be
107 /// readable and writable (and not construct-only).
108 ///
109 /// Writeable | Construct Only
110 ///
111 ///
112 /// #### `state`
113 /// The state of the action, or [`None`] if the action is stateless.
114 ///
115 /// Readable
116 ///
117 ///
118 /// #### `state-type`
119 /// The #GVariantType of the state that the action has, or [`None`] if the
120 /// action is stateless.
121 ///
122 /// Readable
123 /// <details><summary><h4>Action</h4></summary>
124 ///
125 ///
126 /// #### `enabled`
127 /// If @action is currently enabled.
128 ///
129 /// If the action is disabled then calls to [`ActionExt::activate()`][crate::prelude::ActionExt::activate()] and
130 /// [`ActionExt::change_state()`][crate::prelude::ActionExt::change_state()] have no effect.
131 ///
132 /// Readable
133 ///
134 ///
135 /// #### `name`
136 /// The name of the action. This is mostly meaningful for identifying
137 /// the action once it has been added to a [type@Gio.ActionGroup]. It is immutable.
138 ///
139 /// Readable
140 ///
141 ///
142 /// #### `parameter-type`
143 /// The type of the parameter that must be given when activating the
144 /// action. This is immutable, and may be `NULL` if no parameter is needed when
145 /// activating the action.
146 ///
147 /// Readable
148 ///
149 ///
150 /// #### `state`
151 /// The state of the action, or `NULL` if the action is stateless.
152 ///
153 /// Readable
154 ///
155 ///
156 /// #### `state-type`
157 /// The [type@GLib.VariantType] of the state that the action has, or `NULL` if the
158 /// action is stateless. This is immutable.
159 ///
160 /// Readable
161 /// </details>
162 ///
163 /// # Implements
164 ///
165 /// [`trait@glib::ObjectExt`], [`ActionExt`][trait@crate::prelude::ActionExt]
166 #[doc(alias = "GPropertyAction")]
167 pub struct PropertyAction(Object<ffi::GPropertyAction>) @implements Action;
168
169 match fn {
170 type_ => || ffi::g_property_action_get_type(),
171 }
172}
173
174impl PropertyAction {
175 /// Creates a #GAction corresponding to the value of property
176 /// @property_name on @object.
177 ///
178 /// The property must be existent and readable and writable (and not
179 /// construct-only).
180 ///
181 /// This function takes a reference on @object and doesn't release it
182 /// until the action is destroyed.
183 /// ## `name`
184 /// the name of the action to create
185 /// ## `object`
186 /// the object that has the property
187 /// to wrap
188 /// ## `property_name`
189 /// the name of the property
190 ///
191 /// # Returns
192 ///
193 /// a new #GPropertyAction
194 #[doc(alias = "g_property_action_new")]
195 pub fn new(name: &str, object: &impl IsA<glib::Object>, property_name: &str) -> PropertyAction {
196 unsafe {
197 from_glib_full(ffi::g_property_action_new(
198 name.to_glib_none().0,
199 object.as_ref().to_glib_none().0,
200 property_name.to_glib_none().0,
201 ))
202 }
203 }
204
205 /// If [`true`], the state of the action will be the negation of the
206 /// property value, provided the property is boolean.
207 #[doc(alias = "invert-boolean")]
208 pub fn inverts_boolean(&self) -> bool {
209 ObjectExt::property(self, "invert-boolean")
210 }
211}