gio/auto/
action_group.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    object::ObjectType as _,
8    prelude::*,
9    signal::{connect_raw, SignalHandlerId},
10    translate::*,
11};
12use std::boxed::Box as Box_;
13
14glib::wrapper! {
15    /// `GActionGroup` represents a group of actions.
16    ///
17    /// Actions can be used to expose functionality in a structured way, either
18    /// from one part of a program to another, or to the outside world. Action
19    /// groups are often used together with a [type@Gio.MenuModel] that provides additional
20    /// representation data for displaying the actions to the user, e.g. in a menu.
21    ///
22    /// The main way to interact with the actions in a `GActionGroup` is to
23    /// activate them with [`ActionGroupExt::activate_action()`][crate::prelude::ActionGroupExt::activate_action()]. Activating an
24    /// action may require a [type@GLib.Variant] parameter. The required type of the
25    /// parameter can be inquired with [`ActionGroupExt::action_parameter_type()`][crate::prelude::ActionGroupExt::action_parameter_type()].
26    /// Actions may be disabled, see [`ActionGroupExt::is_action_enabled()`][crate::prelude::ActionGroupExt::is_action_enabled()].
27    /// Activating a disabled action has no effect.
28    ///
29    /// Actions may optionally have a state in the form of a [type@GLib.Variant]. The current
30    /// state of an action can be inquired with [`ActionGroupExt::action_state()`][crate::prelude::ActionGroupExt::action_state()].
31    /// Activating a stateful action may change its state, but it is also possible to
32    /// set the state by calling [`ActionGroupExt::change_action_state()`][crate::prelude::ActionGroupExt::change_action_state()].
33    ///
34    /// As typical example, consider a text editing application which has an
35    /// option to change the current font to ‘bold’. A good way to represent
36    /// this would be a stateful action, with a boolean state. Activating the
37    /// action would toggle the state.
38    ///
39    /// Each action in the group has a unique name (which is a string).  All
40    /// method calls, except [`ActionGroupExt::list_actions()`][crate::prelude::ActionGroupExt::list_actions()] take the name of
41    /// an action as an argument.
42    ///
43    /// The `GActionGroup` API is meant to be the ‘public’ API to the action
44    /// group. The calls here are exactly the interaction that ‘external
45    /// forces’ (eg: UI, incoming D-Bus messages, etc.) are supposed to have
46    /// with actions. ‘Internal’ APIs (ie: ones meant only to be accessed by
47    /// the action group implementation) are found on subclasses. This is
48    /// why you will find – for example – [`ActionGroupExt::is_action_enabled()`][crate::prelude::ActionGroupExt::is_action_enabled()]
49    /// but not an equivalent `set_action_enabled()` method.
50    ///
51    /// Signals are emitted on the action group in response to state changes
52    /// on individual actions.
53    ///
54    /// Implementations of `GActionGroup` should provide implementations for
55    /// the virtual functions [`ActionGroupExt::list_actions()`][crate::prelude::ActionGroupExt::list_actions()] and
56    /// `Gio::ActionGroup::query_action()`. The other virtual functions should
57    /// not be implemented — their ‘wrappers’ are actually implemented with
58    /// calls to `Gio::ActionGroup::query_action()`.
59    ///
60    /// ## Signals
61    ///
62    ///
63    /// #### `action-added`
64    ///  Signals that a new action was just added to the group.
65    ///
66    /// This signal is emitted after the action has been added
67    /// and is now visible.
68    ///
69    /// Detailed
70    ///
71    ///
72    /// #### `action-enabled-changed`
73    ///  Signals that the enabled status of the named action has changed.
74    ///
75    /// Detailed
76    ///
77    ///
78    /// #### `action-removed`
79    ///  Signals that an action is just about to be removed from the group.
80    ///
81    /// This signal is emitted before the action is removed, so the action
82    /// is still visible and can be queried from the signal handler.
83    ///
84    /// Detailed
85    ///
86    ///
87    /// #### `action-state-changed`
88    ///  Signals that the state of the named action has changed.
89    ///
90    /// Detailed
91    ///
92    /// # Implements
93    ///
94    /// [`ActionGroupExt`][trait@crate::prelude::ActionGroupExt]
95    #[doc(alias = "GActionGroup")]
96    pub struct ActionGroup(Interface<ffi::GActionGroup, ffi::GActionGroupInterface>);
97
98    match fn {
99        type_ => || ffi::g_action_group_get_type(),
100    }
101}
102
103impl ActionGroup {
104    pub const NONE: Option<&'static ActionGroup> = None;
105}
106
107mod sealed {
108    pub trait Sealed {}
109    impl<T: super::IsA<super::ActionGroup>> Sealed for T {}
110}
111
112/// Trait containing all [`struct@ActionGroup`] methods.
113///
114/// # Implementors
115///
116/// [`ActionGroup`][struct@crate::ActionGroup], [`Application`][struct@crate::Application], [`DBusActionGroup`][struct@crate::DBusActionGroup], [`RemoteActionGroup`][struct@crate::RemoteActionGroup], [`SimpleActionGroup`][struct@crate::SimpleActionGroup]
117pub trait ActionGroupExt: IsA<ActionGroup> + sealed::Sealed + 'static {
118    /// Emits the [`action-added`][struct@crate::ActionGroup#action-added] signal on @self.
119    ///
120    /// This function should only be called by [type@Gio.ActionGroup] implementations.
121    /// ## `action_name`
122    /// the name of an action in the group
123    #[doc(alias = "g_action_group_action_added")]
124    fn action_added(&self, action_name: &str) {
125        unsafe {
126            ffi::g_action_group_action_added(
127                self.as_ref().to_glib_none().0,
128                action_name.to_glib_none().0,
129            );
130        }
131    }
132
133    /// Emits the [`action-enabled-changed`][struct@crate::ActionGroup#action-enabled-changed] signal on @self.
134    ///
135    /// This function should only be called by [type@Gio.ActionGroup] implementations.
136    /// ## `action_name`
137    /// the name of an action in the group
138    /// ## `enabled`
139    /// whether the action is now enabled
140    #[doc(alias = "g_action_group_action_enabled_changed")]
141    fn action_enabled_changed(&self, action_name: &str, enabled: bool) {
142        unsafe {
143            ffi::g_action_group_action_enabled_changed(
144                self.as_ref().to_glib_none().0,
145                action_name.to_glib_none().0,
146                enabled.into_glib(),
147            );
148        }
149    }
150
151    /// Emits the [`action-removed`][struct@crate::ActionGroup#action-removed] signal on @self.
152    ///
153    /// This function should only be called by [type@Gio.ActionGroup] implementations.
154    /// ## `action_name`
155    /// the name of an action in the group
156    #[doc(alias = "g_action_group_action_removed")]
157    fn action_removed(&self, action_name: &str) {
158        unsafe {
159            ffi::g_action_group_action_removed(
160                self.as_ref().to_glib_none().0,
161                action_name.to_glib_none().0,
162            );
163        }
164    }
165
166    /// Emits the [`action-state-changed`][struct@crate::ActionGroup#action-state-changed] signal on @self.
167    ///
168    /// This function should only be called by [type@Gio.ActionGroup] implementations.
169    /// ## `action_name`
170    /// the name of an action in the group
171    /// ## `state`
172    /// the new state of the named action
173    #[doc(alias = "g_action_group_action_state_changed")]
174    fn action_state_changed(&self, action_name: &str, state: &glib::Variant) {
175        unsafe {
176            ffi::g_action_group_action_state_changed(
177                self.as_ref().to_glib_none().0,
178                action_name.to_glib_none().0,
179                state.to_glib_none().0,
180            );
181        }
182    }
183
184    /// Activate the named action within @self.
185    ///
186    /// If the action is expecting a parameter, then the correct type of
187    /// parameter must be given as @parameter.  If the action is expecting no
188    /// parameters then @parameter must be `NULL`.  See
189    /// [`action_parameter_type()`][Self::action_parameter_type()].
190    ///
191    /// If the [type@Gio.ActionGroup] implementation supports asynchronous remote
192    /// activation over D-Bus, this call may return before the relevant
193    /// D-Bus traffic has been sent, or any replies have been received. In
194    /// order to block on such asynchronous activation calls,
195    /// [`DBusConnection::flush()`][crate::DBusConnection::flush()] should be called prior to the code, which
196    /// depends on the result of the action activation. Without flushing
197    /// the D-Bus connection, there is no guarantee that the action would
198    /// have been activated.
199    ///
200    /// The following code which runs in a remote app instance, shows an
201    /// example of a ‘quit’ action being activated on the primary app
202    /// instance over D-Bus. Here [`DBusConnection::flush()`][crate::DBusConnection::flush()] is called
203    /// before `exit()`. Without `g_dbus_connection_flush()`, the ‘quit’ action
204    /// may fail to be activated on the primary instance.
205    ///
206    /// **⚠️ The following code is in c ⚠️**
207    ///
208    /// ```c
209    /// // call ‘quit’ action on primary instance
210    /// g_action_group_activate_action (G_ACTION_GROUP (app), "quit", NULL);
211    ///
212    /// // make sure the action is activated now
213    /// g_dbus_connection_flush (…);
214    ///
215    /// g_debug ("Application has been terminated. Exiting.");
216    ///
217    /// exit (0);
218    /// ```
219    /// ## `action_name`
220    /// the name of the action to activate
221    /// ## `parameter`
222    /// parameters to the activation
223    #[doc(alias = "g_action_group_activate_action")]
224    fn activate_action(&self, action_name: &str, parameter: Option<&glib::Variant>) {
225        unsafe {
226            ffi::g_action_group_activate_action(
227                self.as_ref().to_glib_none().0,
228                action_name.to_glib_none().0,
229                parameter.to_glib_none().0,
230            );
231        }
232    }
233
234    /// Request for the state of the named action within @self to be
235    /// changed to @value.
236    ///
237    /// The action must be stateful and @value must be of the correct type.
238    /// See [`action_state_type()`][Self::action_state_type()].
239    ///
240    /// This call merely requests a change.  The action may refuse to change
241    /// its state or may change its state to something other than @value.
242    /// See [`action_state_hint()`][Self::action_state_hint()].
243    ///
244    /// If the @value GVariant is floating, it is consumed.
245    /// ## `action_name`
246    /// the name of the action to request the change on
247    /// ## `value`
248    /// the new state
249    #[doc(alias = "g_action_group_change_action_state")]
250    fn change_action_state(&self, action_name: &str, value: &glib::Variant) {
251        unsafe {
252            ffi::g_action_group_change_action_state(
253                self.as_ref().to_glib_none().0,
254                action_name.to_glib_none().0,
255                value.to_glib_none().0,
256            );
257        }
258    }
259
260    /// Checks if the named action within @self is currently enabled.
261    ///
262    /// An action must be enabled in order to be activated or in order to
263    /// have its state changed from outside callers.
264    /// ## `action_name`
265    /// the name of the action to query
266    ///
267    /// # Returns
268    ///
269    /// whether the action is currently enabled
270    #[doc(alias = "g_action_group_get_action_enabled")]
271    #[doc(alias = "get_action_enabled")]
272    fn is_action_enabled(&self, action_name: &str) -> bool {
273        unsafe {
274            from_glib(ffi::g_action_group_get_action_enabled(
275                self.as_ref().to_glib_none().0,
276                action_name.to_glib_none().0,
277            ))
278        }
279    }
280
281    /// Queries the type of the parameter that must be given when activating
282    /// the named action within @self.
283    ///
284    /// When activating the action using [`activate_action()`][Self::activate_action()],
285    /// the [type@GLib.Variant] given to that function must be of the type returned
286    /// by this function.
287    ///
288    /// In the case that this function returns `NULL`, you must not give any
289    /// [type@GLib.Variant], but `NULL` instead.
290    ///
291    /// The parameter type of a particular action will never change but it is
292    /// possible for an action to be removed and for a new action to be added
293    /// with the same name but a different parameter type.
294    /// ## `action_name`
295    /// the name of the action to query
296    ///
297    /// # Returns
298    ///
299    /// the parameter type
300    #[doc(alias = "g_action_group_get_action_parameter_type")]
301    #[doc(alias = "get_action_parameter_type")]
302    fn action_parameter_type(&self, action_name: &str) -> Option<glib::VariantType> {
303        unsafe {
304            from_glib_none(ffi::g_action_group_get_action_parameter_type(
305                self.as_ref().to_glib_none().0,
306                action_name.to_glib_none().0,
307            ))
308        }
309    }
310
311    /// Queries the current state of the named action within @self.
312    ///
313    /// If the action is not stateful then `NULL` will be returned.  If the
314    /// action is stateful then the type of the return value is the type
315    /// given by [`action_state_type()`][Self::action_state_type()].
316    ///
317    /// The return value (if non-`NULL`) should be freed with
318    /// `GLib::Variant::unref()` when it is no longer required.
319    /// ## `action_name`
320    /// the name of the action to query
321    ///
322    /// # Returns
323    ///
324    /// the current state of the action
325    #[doc(alias = "g_action_group_get_action_state")]
326    #[doc(alias = "get_action_state")]
327    fn action_state(&self, action_name: &str) -> Option<glib::Variant> {
328        unsafe {
329            from_glib_full(ffi::g_action_group_get_action_state(
330                self.as_ref().to_glib_none().0,
331                action_name.to_glib_none().0,
332            ))
333        }
334    }
335
336    /// Requests a hint about the valid range of values for the state of the
337    /// named action within @self.
338    ///
339    /// If `NULL` is returned it either means that the action is not stateful
340    /// or that there is no hint about the valid range of values for the
341    /// state of the action.
342    ///
343    /// If a [type@GLib.Variant] array is returned then each item in the array is a
344    /// possible value for the state.  If a [type@GLib.Variant] pair (ie: two-tuple) is
345    /// returned then the tuple specifies the inclusive lower and upper bound
346    /// of valid values for the state.
347    ///
348    /// In any case, the information is merely a hint.  It may be possible to
349    /// have a state value outside of the hinted range and setting a value
350    /// within the range may fail.
351    ///
352    /// The return value (if non-`NULL`) should be freed with
353    /// `GLib::Variant::unref()` when it is no longer required.
354    /// ## `action_name`
355    /// the name of the action to query
356    ///
357    /// # Returns
358    ///
359    /// the state range hint
360    #[doc(alias = "g_action_group_get_action_state_hint")]
361    #[doc(alias = "get_action_state_hint")]
362    fn action_state_hint(&self, action_name: &str) -> Option<glib::Variant> {
363        unsafe {
364            from_glib_full(ffi::g_action_group_get_action_state_hint(
365                self.as_ref().to_glib_none().0,
366                action_name.to_glib_none().0,
367            ))
368        }
369    }
370
371    /// Queries the type of the state of the named action within
372    /// @self.
373    ///
374    /// If the action is stateful then this function returns the
375    /// [type@GLib.VariantType] of the state.  All calls to
376    /// [`change_action_state()`][Self::change_action_state()] must give a [type@GLib.Variant] of this
377    /// type and [`action_state()`][Self::action_state()] will return a [type@GLib.Variant]
378    /// of the same type.
379    ///
380    /// If the action is not stateful then this function will return `NULL`.
381    /// In that case, [`action_state()`][Self::action_state()] will return `NULL`
382    /// and you must not call [`change_action_state()`][Self::change_action_state()].
383    ///
384    /// The state type of a particular action will never change but it is
385    /// possible for an action to be removed and for a new action to be added
386    /// with the same name but a different state type.
387    /// ## `action_name`
388    /// the name of the action to query
389    ///
390    /// # Returns
391    ///
392    /// the state type, if the action is stateful
393    #[doc(alias = "g_action_group_get_action_state_type")]
394    #[doc(alias = "get_action_state_type")]
395    fn action_state_type(&self, action_name: &str) -> Option<glib::VariantType> {
396        unsafe {
397            from_glib_none(ffi::g_action_group_get_action_state_type(
398                self.as_ref().to_glib_none().0,
399                action_name.to_glib_none().0,
400            ))
401        }
402    }
403
404    /// Checks if the named action exists within @self.
405    /// ## `action_name`
406    /// the name of the action to check for
407    ///
408    /// # Returns
409    ///
410    /// whether the named action exists
411    #[doc(alias = "g_action_group_has_action")]
412    fn has_action(&self, action_name: &str) -> bool {
413        unsafe {
414            from_glib(ffi::g_action_group_has_action(
415                self.as_ref().to_glib_none().0,
416                action_name.to_glib_none().0,
417            ))
418        }
419    }
420
421    /// Lists the actions contained within @self.
422    ///
423    /// The caller is responsible for freeing the list with `strfreev()` when
424    /// it is no longer required.
425    ///
426    /// # Returns
427    ///
428    /// a `NULL`-terminated array
429    ///   of the names of the actions in the group
430    #[doc(alias = "g_action_group_list_actions")]
431    fn list_actions(&self) -> Vec<glib::GString> {
432        unsafe {
433            FromGlibPtrContainer::from_glib_full(ffi::g_action_group_list_actions(
434                self.as_ref().to_glib_none().0,
435            ))
436        }
437    }
438
439    /// Signals that a new action was just added to the group.
440    ///
441    /// This signal is emitted after the action has been added
442    /// and is now visible.
443    /// ## `action_name`
444    /// the name of the action in @action_group
445    #[doc(alias = "action-added")]
446    fn connect_action_added<F: Fn(&Self, &str) + 'static>(
447        &self,
448        detail: Option<&str>,
449        f: F,
450    ) -> SignalHandlerId {
451        unsafe extern "C" fn action_added_trampoline<
452            P: IsA<ActionGroup>,
453            F: Fn(&P, &str) + 'static,
454        >(
455            this: *mut ffi::GActionGroup,
456            action_name: *mut std::ffi::c_char,
457            f: glib::ffi::gpointer,
458        ) {
459            let f: &F = &*(f as *const F);
460            f(
461                ActionGroup::from_glib_borrow(this).unsafe_cast_ref(),
462                &glib::GString::from_glib_borrow(action_name),
463            )
464        }
465        unsafe {
466            let f: Box_<F> = Box_::new(f);
467            let detailed_signal_name = detail.map(|name| format!("action-added::{name}\0"));
468            let signal_name: &[u8] = detailed_signal_name
469                .as_ref()
470                .map_or(&b"action-added\0"[..], |n| n.as_bytes());
471            connect_raw(
472                self.as_ptr() as *mut _,
473                signal_name.as_ptr() as *const _,
474                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
475                    action_added_trampoline::<Self, F> as *const (),
476                )),
477                Box_::into_raw(f),
478            )
479        }
480    }
481
482    /// Signals that the enabled status of the named action has changed.
483    /// ## `action_name`
484    /// the name of the action in @action_group
485    /// ## `enabled`
486    /// whether the action is enabled
487    #[doc(alias = "action-enabled-changed")]
488    fn connect_action_enabled_changed<F: Fn(&Self, &str, bool) + 'static>(
489        &self,
490        detail: Option<&str>,
491        f: F,
492    ) -> SignalHandlerId {
493        unsafe extern "C" fn action_enabled_changed_trampoline<
494            P: IsA<ActionGroup>,
495            F: Fn(&P, &str, bool) + 'static,
496        >(
497            this: *mut ffi::GActionGroup,
498            action_name: *mut std::ffi::c_char,
499            enabled: glib::ffi::gboolean,
500            f: glib::ffi::gpointer,
501        ) {
502            let f: &F = &*(f as *const F);
503            f(
504                ActionGroup::from_glib_borrow(this).unsafe_cast_ref(),
505                &glib::GString::from_glib_borrow(action_name),
506                from_glib(enabled),
507            )
508        }
509        unsafe {
510            let f: Box_<F> = Box_::new(f);
511            let detailed_signal_name =
512                detail.map(|name| format!("action-enabled-changed::{name}\0"));
513            let signal_name: &[u8] = detailed_signal_name
514                .as_ref()
515                .map_or(&b"action-enabled-changed\0"[..], |n| n.as_bytes());
516            connect_raw(
517                self.as_ptr() as *mut _,
518                signal_name.as_ptr() as *const _,
519                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
520                    action_enabled_changed_trampoline::<Self, F> as *const (),
521                )),
522                Box_::into_raw(f),
523            )
524        }
525    }
526
527    /// Signals that an action is just about to be removed from the group.
528    ///
529    /// This signal is emitted before the action is removed, so the action
530    /// is still visible and can be queried from the signal handler.
531    /// ## `action_name`
532    /// the name of the action in @action_group
533    #[doc(alias = "action-removed")]
534    fn connect_action_removed<F: Fn(&Self, &str) + 'static>(
535        &self,
536        detail: Option<&str>,
537        f: F,
538    ) -> SignalHandlerId {
539        unsafe extern "C" fn action_removed_trampoline<
540            P: IsA<ActionGroup>,
541            F: Fn(&P, &str) + 'static,
542        >(
543            this: *mut ffi::GActionGroup,
544            action_name: *mut std::ffi::c_char,
545            f: glib::ffi::gpointer,
546        ) {
547            let f: &F = &*(f as *const F);
548            f(
549                ActionGroup::from_glib_borrow(this).unsafe_cast_ref(),
550                &glib::GString::from_glib_borrow(action_name),
551            )
552        }
553        unsafe {
554            let f: Box_<F> = Box_::new(f);
555            let detailed_signal_name = detail.map(|name| format!("action-removed::{name}\0"));
556            let signal_name: &[u8] = detailed_signal_name
557                .as_ref()
558                .map_or(&b"action-removed\0"[..], |n| n.as_bytes());
559            connect_raw(
560                self.as_ptr() as *mut _,
561                signal_name.as_ptr() as *const _,
562                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
563                    action_removed_trampoline::<Self, F> as *const (),
564                )),
565                Box_::into_raw(f),
566            )
567        }
568    }
569
570    /// Signals that the state of the named action has changed.
571    /// ## `action_name`
572    /// the name of the action in @action_group
573    /// ## `value`
574    /// the new value of the state
575    #[doc(alias = "action-state-changed")]
576    fn connect_action_state_changed<F: Fn(&Self, &str, &glib::Variant) + 'static>(
577        &self,
578        detail: Option<&str>,
579        f: F,
580    ) -> SignalHandlerId {
581        unsafe extern "C" fn action_state_changed_trampoline<
582            P: IsA<ActionGroup>,
583            F: Fn(&P, &str, &glib::Variant) + 'static,
584        >(
585            this: *mut ffi::GActionGroup,
586            action_name: *mut std::ffi::c_char,
587            value: *mut glib::ffi::GVariant,
588            f: glib::ffi::gpointer,
589        ) {
590            let f: &F = &*(f as *const F);
591            f(
592                ActionGroup::from_glib_borrow(this).unsafe_cast_ref(),
593                &glib::GString::from_glib_borrow(action_name),
594                &from_glib_borrow(value),
595            )
596        }
597        unsafe {
598            let f: Box_<F> = Box_::new(f);
599            let detailed_signal_name = detail.map(|name| format!("action-state-changed::{name}\0"));
600            let signal_name: &[u8] = detailed_signal_name
601                .as_ref()
602                .map_or(&b"action-state-changed\0"[..], |n| n.as_bytes());
603            connect_raw(
604                self.as_ptr() as *mut _,
605                signal_name.as_ptr() as *const _,
606                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
607                    action_state_changed_trampoline::<Self, F> as *const (),
608                )),
609                Box_::into_raw(f),
610            )
611        }
612    }
613}
614
615impl<O: IsA<ActionGroup>> ActionGroupExt for O {}