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}