gio/auto/
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;
6use glib::{
7    prelude::*,
8    signal::{connect_raw, SignalHandlerId},
9    translate::*,
10};
11use std::boxed::Box as Box_;
12
13glib::wrapper! {
14    /// `GAction` represents a single named action.
15    ///
16    /// The main interface to an action is that it can be activated with
17    /// [`ActionExt::activate()`][crate::prelude::ActionExt::activate()]. This results in the 'activate' signal being
18    /// emitted. An activation has a `GVariant` parameter (which may be
19    /// `NULL`). The correct type for the parameter is determined by a static
20    /// parameter type (which is given at construction time).
21    ///
22    /// An action may optionally have a state, in which case the state may be
23    /// set with [`ActionExt::change_state()`][crate::prelude::ActionExt::change_state()]. This call takes a [type@GLib.Variant]. The
24    /// correct type for the state is determined by a static state type
25    /// (which is given at construction time).
26    ///
27    /// The state may have a hint associated with it, specifying its valid
28    /// range.
29    ///
30    /// `GAction` is merely the interface to the concept of an action, as
31    /// described above.  Various implementations of actions exist, including
32    /// [`SimpleAction`][crate::SimpleAction].
33    ///
34    /// In all cases, the implementing class is responsible for storing the
35    /// name of the action, the parameter type, the enabled state, the optional
36    /// state type and the state and emitting the appropriate signals when these
37    /// change. The implementor is responsible for filtering calls to
38    /// [`ActionExt::activate()`][crate::prelude::ActionExt::activate()] and [`ActionExt::change_state()`][crate::prelude::ActionExt::change_state()]
39    /// for type safety and for the state being enabled.
40    ///
41    /// Probably the only useful thing to do with a `GAction` is to put it
42    /// inside of a [`SimpleActionGroup`][crate::SimpleActionGroup].
43    ///
44    /// ## Properties
45    ///
46    ///
47    /// #### `enabled`
48    ///  If @action is currently enabled.
49    ///
50    /// If the action is disabled then calls to [`ActionExt::activate()`][crate::prelude::ActionExt::activate()] and
51    /// [`ActionExt::change_state()`][crate::prelude::ActionExt::change_state()] have no effect.
52    ///
53    /// Readable
54    ///
55    ///
56    /// #### `name`
57    ///  The name of the action.  This is mostly meaningful for identifying
58    /// the action once it has been added to a [type@Gio.ActionGroup]. It is immutable.
59    ///
60    /// Readable
61    ///
62    ///
63    /// #### `parameter-type`
64    ///  The type of the parameter that must be given when activating the
65    /// action. This is immutable, and may be `NULL` if no parameter is needed when
66    /// activating the action.
67    ///
68    /// Readable
69    ///
70    ///
71    /// #### `state`
72    ///  The state of the action, or `NULL` if the action is stateless.
73    ///
74    /// Readable
75    ///
76    ///
77    /// #### `state-type`
78    ///  The [type@GLib.VariantType] of the state that the action has, or `NULL` if the
79    /// action is stateless. This is immutable.
80    ///
81    /// Readable
82    ///
83    /// # Implements
84    ///
85    /// [`ActionExt`][trait@crate::prelude::ActionExt]
86    #[doc(alias = "GAction")]
87    pub struct Action(Interface<ffi::GAction, ffi::GActionInterface>);
88
89    match fn {
90        type_ => || ffi::g_action_get_type(),
91    }
92}
93
94impl Action {
95    pub const NONE: Option<&'static Action> = None;
96
97    /// Checks if @action_name is valid.
98    ///
99    /// @action_name is valid if it consists only of alphanumeric characters,
100    /// plus `-` and `.`.  The empty string is not a valid action name.
101    ///
102    /// It is an error to call this function with a non-UTF-8 @action_name.
103    /// @action_name must not be `NULL`.
104    /// ## `action_name`
105    /// a potential action name
106    ///
107    /// # Returns
108    ///
109    /// `TRUE` if @action_name is valid
110    #[doc(alias = "g_action_name_is_valid")]
111    pub fn name_is_valid(action_name: &str) -> bool {
112        unsafe { from_glib(ffi::g_action_name_is_valid(action_name.to_glib_none().0)) }
113    }
114
115    /// Parses a detailed action name into its separate name and target
116    /// components.
117    ///
118    /// Detailed action names can have three formats.
119    ///
120    /// The first format is used to represent an action name with no target
121    /// value and consists of just an action name containing no whitespace
122    /// nor the characters `:`, `(` or `)`.  For example: `app.action`.
123    ///
124    /// The second format is used to represent an action with a target value
125    /// that is a non-empty string consisting only of alphanumerics, plus `-`
126    /// and `.`.  In that case, the action name and target value are
127    /// separated by a double colon (`::`).  For example:
128    /// `app.action::target`.
129    ///
130    /// The third format is used to represent an action with any type of
131    /// target value, including strings.  The target value follows the action
132    /// name, surrounded in parens.  For example: `app.action(42)`.  The
133    /// target value is parsed using `GLib::Variant::parse()`.  If a tuple-typed
134    /// value is desired, it must be specified in the same way, resulting in
135    /// two sets of parens, for example: `app.action((1,2,3))`.  A string
136    /// target can be specified this way as well: `app.action('target')`.
137    /// For strings, this third format must be used if target value is
138    /// empty or contains characters other than alphanumerics, `-` and `.`.
139    ///
140    /// If this function returns `TRUE`, a non-`NULL` value is guaranteed to be returned
141    /// in @action_name (if a pointer is passed in). A `NULL` value may still be
142    /// returned in @target_value, as the @detailed_name may not contain a target.
143    ///
144    /// If returned, the [type@GLib.Variant] in @target_value is guaranteed to not be floating.
145    /// ## `detailed_name`
146    /// a detailed action name
147    ///
148    /// # Returns
149    ///
150    /// `TRUE` if successful, else `FALSE` with @error set
151    ///
152    /// ## `action_name`
153    /// the action name
154    ///
155    /// ## `target_value`
156    /// the target value,
157    ///   or `NULL` for no target
158    #[doc(alias = "g_action_parse_detailed_name")]
159    pub fn parse_detailed_name(
160        detailed_name: &str,
161    ) -> Result<(glib::GString, Option<glib::Variant>), glib::Error> {
162        unsafe {
163            let mut action_name = std::ptr::null_mut();
164            let mut target_value = std::ptr::null_mut();
165            let mut error = std::ptr::null_mut();
166            let is_ok = ffi::g_action_parse_detailed_name(
167                detailed_name.to_glib_none().0,
168                &mut action_name,
169                &mut target_value,
170                &mut error,
171            );
172            debug_assert_eq!(is_ok == glib::ffi::GFALSE, !error.is_null());
173            if error.is_null() {
174                Ok((from_glib_full(action_name), from_glib_full(target_value)))
175            } else {
176                Err(from_glib_full(error))
177            }
178        }
179    }
180
181    /// Formats a detailed action name from @action_name and @target_value.
182    ///
183    /// It is an error to call this function with an invalid action name.
184    ///
185    /// This function is the opposite of [`parse_detailed_name()`][Self::parse_detailed_name()].
186    /// It will produce a string that can be parsed back to the @action_name
187    /// and @target_value by that function.
188    ///
189    /// See that function for the types of strings that will be printed by
190    /// this function.
191    /// ## `action_name`
192    /// a valid action name
193    /// ## `target_value`
194    /// a [type@GLib.Variant] target value, or `NULL`
195    ///
196    /// # Returns
197    ///
198    /// a detailed format string
199    #[doc(alias = "g_action_print_detailed_name")]
200    pub fn print_detailed_name(
201        action_name: &str,
202        target_value: Option<&glib::Variant>,
203    ) -> glib::GString {
204        unsafe {
205            from_glib_full(ffi::g_action_print_detailed_name(
206                action_name.to_glib_none().0,
207                target_value.to_glib_none().0,
208            ))
209        }
210    }
211}
212
213mod sealed {
214    pub trait Sealed {}
215    impl<T: super::IsA<super::Action>> Sealed for T {}
216}
217
218/// Trait containing all [`struct@Action`] methods.
219///
220/// # Implementors
221///
222/// [`Action`][struct@crate::Action], [`PropertyAction`][struct@crate::PropertyAction], [`SimpleAction`][struct@crate::SimpleAction]
223pub trait ActionExt: IsA<Action> + sealed::Sealed + 'static {
224    /// Activates the action.
225    ///
226    /// @parameter must be the correct type of parameter for the action (ie:
227    /// the parameter type given at construction time).  If the parameter
228    /// type was `NULL` then @parameter must also be `NULL`.
229    ///
230    /// If the @parameter [type@GLib.Variant] is floating, it is consumed.
231    /// ## `parameter`
232    /// the parameter to the activation
233    #[doc(alias = "g_action_activate")]
234    fn activate(&self, parameter: Option<&glib::Variant>) {
235        unsafe {
236            ffi::g_action_activate(self.as_ref().to_glib_none().0, parameter.to_glib_none().0);
237        }
238    }
239
240    /// Request for the state of @self to be changed to @value.
241    ///
242    /// The action must be stateful and @value must be of the correct type.
243    /// See [`state_type()`][Self::state_type()].
244    ///
245    /// This call merely requests a change.  The action may refuse to change
246    /// its state or may change its state to something other than @value.
247    /// See [`state_hint()`][Self::state_hint()].
248    ///
249    /// If the @value [type@GLib.Variant] is floating, it is consumed.
250    /// ## `value`
251    /// the new state
252    #[doc(alias = "g_action_change_state")]
253    fn change_state(&self, value: &glib::Variant) {
254        unsafe {
255            ffi::g_action_change_state(self.as_ref().to_glib_none().0, value.to_glib_none().0);
256        }
257    }
258
259    /// Checks if @self is currently enabled.
260    ///
261    /// An action must be enabled in order to be activated or in order to
262    /// have its state changed from outside callers.
263    ///
264    /// # Returns
265    ///
266    /// whether the action is enabled
267    #[doc(alias = "g_action_get_enabled")]
268    #[doc(alias = "get_enabled")]
269    #[doc(alias = "enabled")]
270    fn is_enabled(&self) -> bool {
271        unsafe { from_glib(ffi::g_action_get_enabled(self.as_ref().to_glib_none().0)) }
272    }
273
274    /// Queries the name of @self.
275    ///
276    /// # Returns
277    ///
278    /// the name of the action
279    #[doc(alias = "g_action_get_name")]
280    #[doc(alias = "get_name")]
281    fn name(&self) -> glib::GString {
282        unsafe { from_glib_none(ffi::g_action_get_name(self.as_ref().to_glib_none().0)) }
283    }
284
285    /// Queries the type of the parameter that must be given when activating
286    /// @self.
287    ///
288    /// When activating the action using [`activate()`][Self::activate()], the
289    /// [type@GLib.Variant] given to that function must be of the type returned by
290    /// this function.
291    ///
292    /// In the case that this function returns `NULL`, you must not give any
293    /// [type@GLib.Variant], but `NULL` instead.
294    ///
295    /// # Returns
296    ///
297    /// the parameter type
298    #[doc(alias = "g_action_get_parameter_type")]
299    #[doc(alias = "get_parameter_type")]
300    #[doc(alias = "parameter-type")]
301    fn parameter_type(&self) -> Option<glib::VariantType> {
302        unsafe {
303            from_glib_none(ffi::g_action_get_parameter_type(
304                self.as_ref().to_glib_none().0,
305            ))
306        }
307    }
308
309    /// Queries the current state of @self.
310    ///
311    /// If the action is not stateful then `NULL` will be returned.  If the
312    /// action is stateful then the type of the return value is the type
313    /// given by [`state_type()`][Self::state_type()].
314    ///
315    /// The return value (if non-`NULL`) should be freed with
316    /// `GLib::Variant::unref()` when it is no longer required.
317    ///
318    /// # Returns
319    ///
320    /// the current state of the action
321    #[doc(alias = "g_action_get_state")]
322    #[doc(alias = "get_state")]
323    fn state(&self) -> Option<glib::Variant> {
324        unsafe { from_glib_full(ffi::g_action_get_state(self.as_ref().to_glib_none().0)) }
325    }
326
327    /// Requests a hint about the valid range of values for the state of
328    /// @self.
329    ///
330    /// If `NULL` is returned it either means that the action is not stateful
331    /// or that there is no hint about the valid range of values for the
332    /// state of the action.
333    ///
334    /// If a [type@GLib.Variant] array is returned then each item in the array is a
335    /// possible value for the state.  If a [type@GLib.Variant] pair (ie: two-tuple) is
336    /// returned then the tuple specifies the inclusive lower and upper bound
337    /// of valid values for the state.
338    ///
339    /// In any case, the information is merely a hint.  It may be possible to
340    /// have a state value outside of the hinted range and setting a value
341    /// within the range may fail.
342    ///
343    /// The return value (if non-`NULL`) should be freed with
344    /// `GLib::Variant::unref()` when it is no longer required.
345    ///
346    /// # Returns
347    ///
348    /// the state range hint
349    #[doc(alias = "g_action_get_state_hint")]
350    #[doc(alias = "get_state_hint")]
351    fn state_hint(&self) -> Option<glib::Variant> {
352        unsafe { from_glib_full(ffi::g_action_get_state_hint(self.as_ref().to_glib_none().0)) }
353    }
354
355    /// Queries the type of the state of @self.
356    ///
357    /// If the action is stateful (e.g. created with
358    /// [`SimpleAction::new_stateful()`][crate::SimpleAction::new_stateful()]) then this function returns the
359    /// [type@GLib.VariantType] of the state.  This is the type of the initial value
360    /// given as the state. All calls to [`change_state()`][Self::change_state()] must give a
361    /// [type@GLib.Variant] of this type and [`state()`][Self::state()] will return a
362    /// [type@GLib.Variant] of the same type.
363    ///
364    /// If the action is not stateful (e.g. created with [`SimpleAction::new()`][crate::SimpleAction::new()])
365    /// then this function will return `NULL`. In that case, [`state()`][Self::state()]
366    /// will return `NULL` and you must not call [`change_state()`][Self::change_state()].
367    ///
368    /// # Returns
369    ///
370    /// the state type, if the action is stateful
371    #[doc(alias = "g_action_get_state_type")]
372    #[doc(alias = "get_state_type")]
373    #[doc(alias = "state-type")]
374    fn state_type(&self) -> Option<glib::VariantType> {
375        unsafe { from_glib_none(ffi::g_action_get_state_type(self.as_ref().to_glib_none().0)) }
376    }
377
378    #[doc(alias = "enabled")]
379    fn connect_enabled_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
380        unsafe extern "C" fn notify_enabled_trampoline<P: IsA<Action>, F: Fn(&P) + 'static>(
381            this: *mut ffi::GAction,
382            _param_spec: glib::ffi::gpointer,
383            f: glib::ffi::gpointer,
384        ) {
385            let f: &F = &*(f as *const F);
386            f(Action::from_glib_borrow(this).unsafe_cast_ref())
387        }
388        unsafe {
389            let f: Box_<F> = Box_::new(f);
390            connect_raw(
391                self.as_ptr() as *mut _,
392                b"notify::enabled\0".as_ptr() as *const _,
393                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
394                    notify_enabled_trampoline::<Self, F> as *const (),
395                )),
396                Box_::into_raw(f),
397            )
398        }
399    }
400
401    #[doc(alias = "name")]
402    fn connect_name_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
403        unsafe extern "C" fn notify_name_trampoline<P: IsA<Action>, F: Fn(&P) + 'static>(
404            this: *mut ffi::GAction,
405            _param_spec: glib::ffi::gpointer,
406            f: glib::ffi::gpointer,
407        ) {
408            let f: &F = &*(f as *const F);
409            f(Action::from_glib_borrow(this).unsafe_cast_ref())
410        }
411        unsafe {
412            let f: Box_<F> = Box_::new(f);
413            connect_raw(
414                self.as_ptr() as *mut _,
415                b"notify::name\0".as_ptr() as *const _,
416                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
417                    notify_name_trampoline::<Self, F> as *const (),
418                )),
419                Box_::into_raw(f),
420            )
421        }
422    }
423
424    #[doc(alias = "parameter-type")]
425    fn connect_parameter_type_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
426        unsafe extern "C" fn notify_parameter_type_trampoline<
427            P: IsA<Action>,
428            F: Fn(&P) + 'static,
429        >(
430            this: *mut ffi::GAction,
431            _param_spec: glib::ffi::gpointer,
432            f: glib::ffi::gpointer,
433        ) {
434            let f: &F = &*(f as *const F);
435            f(Action::from_glib_borrow(this).unsafe_cast_ref())
436        }
437        unsafe {
438            let f: Box_<F> = Box_::new(f);
439            connect_raw(
440                self.as_ptr() as *mut _,
441                b"notify::parameter-type\0".as_ptr() as *const _,
442                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
443                    notify_parameter_type_trampoline::<Self, F> as *const (),
444                )),
445                Box_::into_raw(f),
446            )
447        }
448    }
449
450    #[doc(alias = "state")]
451    fn connect_state_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
452        unsafe extern "C" fn notify_state_trampoline<P: IsA<Action>, F: Fn(&P) + 'static>(
453            this: *mut ffi::GAction,
454            _param_spec: glib::ffi::gpointer,
455            f: glib::ffi::gpointer,
456        ) {
457            let f: &F = &*(f as *const F);
458            f(Action::from_glib_borrow(this).unsafe_cast_ref())
459        }
460        unsafe {
461            let f: Box_<F> = Box_::new(f);
462            connect_raw(
463                self.as_ptr() as *mut _,
464                b"notify::state\0".as_ptr() as *const _,
465                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
466                    notify_state_trampoline::<Self, F> as *const (),
467                )),
468                Box_::into_raw(f),
469            )
470        }
471    }
472
473    #[doc(alias = "state-type")]
474    fn connect_state_type_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
475        unsafe extern "C" fn notify_state_type_trampoline<P: IsA<Action>, F: Fn(&P) + 'static>(
476            this: *mut ffi::GAction,
477            _param_spec: glib::ffi::gpointer,
478            f: glib::ffi::gpointer,
479        ) {
480            let f: &F = &*(f as *const F);
481            f(Action::from_glib_borrow(this).unsafe_cast_ref())
482        }
483        unsafe {
484            let f: Box_<F> = Box_::new(f);
485            connect_raw(
486                self.as_ptr() as *mut _,
487                b"notify::state-type\0".as_ptr() as *const _,
488                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
489                    notify_state_type_trampoline::<Self, F> as *const (),
490                )),
491                Box_::into_raw(f),
492            )
493        }
494    }
495}
496
497impl<O: IsA<Action>> ActionExt for O {}