gio/auto/

action_group.rs

// This file was generated by gir (https://github.com/gtk-rs/gir)
// from gir-files (https://github.com/gtk-rs/gir-files)
// DO NOT EDIT

use crate::ffi;
use glib::{
    object::ObjectType as _,
    prelude::*,
    signal::{connect_raw, SignalHandlerId},
    translate::*,
};
use std::boxed::Box as Box_;

glib::wrapper! {
    /// `GActionGroup` represents a group of actions.
    ///
    /// Actions can be used to expose functionality in a structured way, either
    /// from one part of a program to another, or to the outside world. Action
    /// groups are often used together with a [type@Gio.MenuModel] that provides additional
    /// representation data for displaying the actions to the user, e.g. in a menu.
    ///
    /// The main way to interact with the actions in a `GActionGroup` is to
    /// activate them with [`ActionGroupExt::activate_action()`][crate::prelude::ActionGroupExt::activate_action()]. Activating an
    /// action may require a [type@GLib.Variant] parameter. The required type of the
    /// parameter can be inquired with [`ActionGroupExt::action_parameter_type()`][crate::prelude::ActionGroupExt::action_parameter_type()].
    /// Actions may be disabled, see [`ActionGroupExt::is_action_enabled()`][crate::prelude::ActionGroupExt::is_action_enabled()].
    /// Activating a disabled action has no effect.
    ///
    /// Actions may optionally have a state in the form of a [type@GLib.Variant]. The current
    /// state of an action can be inquired with [`ActionGroupExt::action_state()`][crate::prelude::ActionGroupExt::action_state()].
    /// Activating a stateful action may change its state, but it is also possible to
    /// set the state by calling [`ActionGroupExt::change_action_state()`][crate::prelude::ActionGroupExt::change_action_state()].
    ///
    /// As typical example, consider a text editing application which has an
    /// option to change the current font to ‘bold’. A good way to represent
    /// this would be a stateful action, with a boolean state. Activating the
    /// action would toggle the state.
    ///
    /// Each action in the group has a unique name (which is a string).  All
    /// method calls, except [`ActionGroupExt::list_actions()`][crate::prelude::ActionGroupExt::list_actions()] take the name of
    /// an action as an argument.
    ///
    /// The `GActionGroup` API is meant to be the ‘public’ API to the action
    /// group. The calls here are exactly the interaction that ‘external
    /// forces’ (eg: UI, incoming D-Bus messages, etc.) are supposed to have
    /// with actions. ‘Internal’ APIs (ie: ones meant only to be accessed by
    /// the action group implementation) are found on subclasses. This is
    /// why you will find – for example – [`ActionGroupExt::is_action_enabled()`][crate::prelude::ActionGroupExt::is_action_enabled()]
    /// but not an equivalent `set_action_enabled()` method.
    ///
    /// Signals are emitted on the action group in response to state changes
    /// on individual actions.
    ///
    /// Implementations of `GActionGroup` should provide implementations for
    /// the virtual functions [`ActionGroupExt::list_actions()`][crate::prelude::ActionGroupExt::list_actions()] and
    /// `Gio::ActionGroup::query_action()`. The other virtual functions should
    /// not be implemented — their ‘wrappers’ are actually implemented with
    /// calls to `Gio::ActionGroup::query_action()`.
    ///
    /// ## Signals
    ///
    ///
    /// #### `action-added`
    ///  Signals that a new action was just added to the group.
    ///
    /// This signal is emitted after the action has been added
    /// and is now visible.
    ///
    /// Detailed
    ///
    ///
    /// #### `action-enabled-changed`
    ///  Signals that the enabled status of the named action has changed.
    ///
    /// Detailed
    ///
    ///
    /// #### `action-removed`
    ///  Signals that an action is just about to be removed from the group.
    ///
    /// This signal is emitted before the action is removed, so the action
    /// is still visible and can be queried from the signal handler.
    ///
    /// Detailed
    ///
    ///
    /// #### `action-state-changed`
    ///  Signals that the state of the named action has changed.
    ///
    /// Detailed
    ///
    /// # Implements
    ///
    /// [`ActionGroupExt`][trait@crate::prelude::ActionGroupExt]
    #[doc(alias = "GActionGroup")]
    pub struct ActionGroup(Interface<ffi::GActionGroup, ffi::GActionGroupInterface>);

    match fn {
        type_ => || ffi::g_action_group_get_type(),
    }
}

impl ActionGroup {
    pub const NONE: Option<&'static ActionGroup> = None;
}

/// Trait containing all [`struct@ActionGroup`] methods.
///
/// # Implementors
///
/// [`ActionGroup`][struct@crate::ActionGroup], [`Application`][struct@crate::Application], [`DBusActionGroup`][struct@crate::DBusActionGroup], [`RemoteActionGroup`][struct@crate::RemoteActionGroup], [`SimpleActionGroup`][struct@crate::SimpleActionGroup]
pub trait ActionGroupExt: IsA<ActionGroup> + 'static {
    /// Emits the [`action-added`][struct@crate::ActionGroup#action-added] signal on @self.
    ///
    /// This function should only be called by [type@Gio.ActionGroup] implementations.
    /// ## `action_name`
    /// the name of an action in the group
    #[doc(alias = "g_action_group_action_added")]
    fn action_added(&self, action_name: &str) {
        unsafe {
            ffi::g_action_group_action_added(
                self.as_ref().to_glib_none().0,
                action_name.to_glib_none().0,
            );
        }
    }

    /// Emits the [`action-enabled-changed`][struct@crate::ActionGroup#action-enabled-changed] signal on @self.
    ///
    /// This function should only be called by [type@Gio.ActionGroup] implementations.
    /// ## `action_name`
    /// the name of an action in the group
    /// ## `enabled`
    /// whether the action is now enabled
    #[doc(alias = "g_action_group_action_enabled_changed")]
    fn action_enabled_changed(&self, action_name: &str, enabled: bool) {
        unsafe {
            ffi::g_action_group_action_enabled_changed(
                self.as_ref().to_glib_none().0,
                action_name.to_glib_none().0,
                enabled.into_glib(),
            );
        }
    }

    /// Emits the [`action-removed`][struct@crate::ActionGroup#action-removed] signal on @self.
    ///
    /// This function should only be called by [type@Gio.ActionGroup] implementations.
    /// ## `action_name`
    /// the name of an action in the group
    #[doc(alias = "g_action_group_action_removed")]
    fn action_removed(&self, action_name: &str) {
        unsafe {
            ffi::g_action_group_action_removed(
                self.as_ref().to_glib_none().0,
                action_name.to_glib_none().0,
            );
        }
    }

    /// Emits the [`action-state-changed`][struct@crate::ActionGroup#action-state-changed] signal on @self.
    ///
    /// This function should only be called by [type@Gio.ActionGroup] implementations.
    /// ## `action_name`
    /// the name of an action in the group
    /// ## `state`
    /// the new state of the named action
    #[doc(alias = "g_action_group_action_state_changed")]
    fn action_state_changed(&self, action_name: &str, state: &glib::Variant) {
        unsafe {
            ffi::g_action_group_action_state_changed(
                self.as_ref().to_glib_none().0,
                action_name.to_glib_none().0,
                state.to_glib_none().0,
            );
        }
    }

    /// Activate the named action within @self.
    ///
    /// If the action is expecting a parameter, then the correct type of
    /// parameter must be given as @parameter.  If the action is expecting no
    /// parameters then @parameter must be `NULL`.  See
    /// [`action_parameter_type()`][Self::action_parameter_type()].
    ///
    /// If the [type@Gio.ActionGroup] implementation supports asynchronous remote
    /// activation over D-Bus, this call may return before the relevant
    /// D-Bus traffic has been sent, or any replies have been received. In
    /// order to block on such asynchronous activation calls,
    /// [`DBusConnection::flush()`][crate::DBusConnection::flush()] should be called prior to the code, which
    /// depends on the result of the action activation. Without flushing
    /// the D-Bus connection, there is no guarantee that the action would
    /// have been activated.
    ///
    /// The following code which runs in a remote app instance, shows an
    /// example of a ‘quit’ action being activated on the primary app
    /// instance over D-Bus. Here [`DBusConnection::flush()`][crate::DBusConnection::flush()] is called
    /// before `exit()`. Without `g_dbus_connection_flush()`, the ‘quit’ action
    /// may fail to be activated on the primary instance.
    ///
    /// **⚠️ The following code is in c ⚠️**
    ///
    /// ```c
    /// // call ‘quit’ action on primary instance
    /// g_action_group_activate_action (G_ACTION_GROUP (app), "quit", NULL);
    ///
    /// // make sure the action is activated now
    /// g_dbus_connection_flush (…);
    ///
    /// g_debug ("Application has been terminated. Exiting.");
    ///
    /// exit (0);
    /// ```
    /// ## `action_name`
    /// the name of the action to activate
    /// ## `parameter`
    /// parameters to the activation
    #[doc(alias = "g_action_group_activate_action")]
    fn activate_action(&self, action_name: &str, parameter: Option<&glib::Variant>) {
        unsafe {
            ffi::g_action_group_activate_action(
                self.as_ref().to_glib_none().0,
                action_name.to_glib_none().0,
                parameter.to_glib_none().0,
            );
        }
    }

    /// Request for the state of the named action within @self to be
    /// changed to @value.
    ///
    /// The action must be stateful and @value must be of the correct type.
    /// See [`action_state_type()`][Self::action_state_type()].
    ///
    /// This call merely requests a change.  The action may refuse to change
    /// its state or may change its state to something other than @value.
    /// See [`action_state_hint()`][Self::action_state_hint()].
    ///
    /// If the @value GVariant is floating, it is consumed.
    /// ## `action_name`
    /// the name of the action to request the change on
    /// ## `value`
    /// the new state
    #[doc(alias = "g_action_group_change_action_state")]
    fn change_action_state(&self, action_name: &str, value: &glib::Variant) {
        unsafe {
            ffi::g_action_group_change_action_state(
                self.as_ref().to_glib_none().0,
                action_name.to_glib_none().0,
                value.to_glib_none().0,
            );
        }
    }

    /// Checks if the named action within @self is currently enabled.
    ///
    /// An action must be enabled in order to be activated or in order to
    /// have its state changed from outside callers.
    /// ## `action_name`
    /// the name of the action to query
    ///
    /// # Returns
    ///
    /// whether the action is currently enabled
    #[doc(alias = "g_action_group_get_action_enabled")]
    #[doc(alias = "get_action_enabled")]
    fn is_action_enabled(&self, action_name: &str) -> bool {
        unsafe {
            from_glib(ffi::g_action_group_get_action_enabled(
                self.as_ref().to_glib_none().0,
                action_name.to_glib_none().0,
            ))
        }
    }

    /// Queries the type of the parameter that must be given when activating
    /// the named action within @self.
    ///
    /// When activating the action using [`activate_action()`][Self::activate_action()],
    /// the [type@GLib.Variant] given to that function must be of the type returned
    /// by this function.
    ///
    /// In the case that this function returns `NULL`, you must not give any
    /// [type@GLib.Variant], but `NULL` instead.
    ///
    /// The parameter type of a particular action will never change but it is
    /// possible for an action to be removed and for a new action to be added
    /// with the same name but a different parameter type.
    /// ## `action_name`
    /// the name of the action to query
    ///
    /// # Returns
    ///
    /// the parameter type
    #[doc(alias = "g_action_group_get_action_parameter_type")]
    #[doc(alias = "get_action_parameter_type")]
    fn action_parameter_type(&self, action_name: &str) -> Option<glib::VariantType> {
        unsafe {
            from_glib_none(ffi::g_action_group_get_action_parameter_type(
                self.as_ref().to_glib_none().0,
                action_name.to_glib_none().0,
            ))
        }
    }

    /// Queries the current state of the named action within @self.
    ///
    /// If the action is not stateful then `NULL` will be returned.  If the
    /// action is stateful then the type of the return value is the type
    /// given by [`action_state_type()`][Self::action_state_type()].
    ///
    /// The return value (if non-`NULL`) should be freed with
    /// `GLib::Variant::unref()` when it is no longer required.
    /// ## `action_name`
    /// the name of the action to query
    ///
    /// # Returns
    ///
    /// the current state of the action
    #[doc(alias = "g_action_group_get_action_state")]
    #[doc(alias = "get_action_state")]
    fn action_state(&self, action_name: &str) -> Option<glib::Variant> {
        unsafe {
            from_glib_full(ffi::g_action_group_get_action_state(
                self.as_ref().to_glib_none().0,
                action_name.to_glib_none().0,
            ))
        }
    }

    /// Requests a hint about the valid range of values for the state of the
    /// named action within @self.
    ///
    /// If `NULL` is returned it either means that the action is not stateful
    /// or that there is no hint about the valid range of values for the
    /// state of the action.
    ///
    /// If a [type@GLib.Variant] array is returned then each item in the array is a
    /// possible value for the state.  If a [type@GLib.Variant] pair (ie: two-tuple) is
    /// returned then the tuple specifies the inclusive lower and upper bound
    /// of valid values for the state.
    ///
    /// In any case, the information is merely a hint.  It may be possible to
    /// have a state value outside of the hinted range and setting a value
    /// within the range may fail.
    ///
    /// The return value (if non-`NULL`) should be freed with
    /// `GLib::Variant::unref()` when it is no longer required.
    /// ## `action_name`
    /// the name of the action to query
    ///
    /// # Returns
    ///
    /// the state range hint
    #[doc(alias = "g_action_group_get_action_state_hint")]
    #[doc(alias = "get_action_state_hint")]
    fn action_state_hint(&self, action_name: &str) -> Option<glib::Variant> {
        unsafe {
            from_glib_full(ffi::g_action_group_get_action_state_hint(
                self.as_ref().to_glib_none().0,
                action_name.to_glib_none().0,
            ))
        }
    }

    /// Queries the type of the state of the named action within
    /// @self.
    ///
    /// If the action is stateful then this function returns the
    /// [type@GLib.VariantType] of the state.  All calls to
    /// [`change_action_state()`][Self::change_action_state()] must give a [type@GLib.Variant] of this
    /// type and [`action_state()`][Self::action_state()] will return a [type@GLib.Variant]
    /// of the same type.
    ///
    /// If the action is not stateful then this function will return `NULL`.
    /// In that case, [`action_state()`][Self::action_state()] will return `NULL`
    /// and you must not call [`change_action_state()`][Self::change_action_state()].
    ///
    /// The state type of a particular action will never change but it is
    /// possible for an action to be removed and for a new action to be added
    /// with the same name but a different state type.
    /// ## `action_name`
    /// the name of the action to query
    ///
    /// # Returns
    ///
    /// the state type, if the action is stateful
    #[doc(alias = "g_action_group_get_action_state_type")]
    #[doc(alias = "get_action_state_type")]
    fn action_state_type(&self, action_name: &str) -> Option<glib::VariantType> {
        unsafe {
            from_glib_none(ffi::g_action_group_get_action_state_type(
                self.as_ref().to_glib_none().0,
                action_name.to_glib_none().0,
            ))
        }
    }

    /// Checks if the named action exists within @self.
    /// ## `action_name`
    /// the name of the action to check for
    ///
    /// # Returns
    ///
    /// whether the named action exists
    #[doc(alias = "g_action_group_has_action")]
    fn has_action(&self, action_name: &str) -> bool {
        unsafe {
            from_glib(ffi::g_action_group_has_action(
                self.as_ref().to_glib_none().0,
                action_name.to_glib_none().0,
            ))
        }
    }

    /// Lists the actions contained within @self.
    ///
    /// The caller is responsible for freeing the list with `strfreev()` when
    /// it is no longer required.
    ///
    /// # Returns
    ///
    /// a `NULL`-terminated array
    ///   of the names of the actions in the group
    #[doc(alias = "g_action_group_list_actions")]
    fn list_actions(&self) -> Vec<glib::GString> {
        unsafe {
            FromGlibPtrContainer::from_glib_full(ffi::g_action_group_list_actions(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Signals that a new action was just added to the group.
    ///
    /// This signal is emitted after the action has been added
    /// and is now visible.
    /// ## `action_name`
    /// the name of the action in @action_group
    #[doc(alias = "action-added")]
    fn connect_action_added<F: Fn(&Self, &str) + 'static>(
        &self,
        detail: Option<&str>,
        f: F,
    ) -> SignalHandlerId {
        unsafe extern "C" fn action_added_trampoline<
            P: IsA<ActionGroup>,
            F: Fn(&P, &str) + 'static,
        >(
            this: *mut ffi::GActionGroup,
            action_name: *mut std::ffi::c_char,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(
                ActionGroup::from_glib_borrow(this).unsafe_cast_ref(),
                &glib::GString::from_glib_borrow(action_name),
            )
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            let detailed_signal_name = detail.map(|name| format!("action-added::{name}\0"));
            let signal_name: &[u8] = detailed_signal_name
                .as_ref()
                .map_or(c"action-added".to_bytes(), |n| n.as_bytes());
            connect_raw(
                self.as_ptr() as *mut _,
                signal_name.as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    action_added_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    /// Signals that the enabled status of the named action has changed.
    /// ## `action_name`
    /// the name of the action in @action_group
    /// ## `enabled`
    /// whether the action is enabled
    #[doc(alias = "action-enabled-changed")]
    fn connect_action_enabled_changed<F: Fn(&Self, &str, bool) + 'static>(
        &self,
        detail: Option<&str>,
        f: F,
    ) -> SignalHandlerId {
        unsafe extern "C" fn action_enabled_changed_trampoline<
            P: IsA<ActionGroup>,
            F: Fn(&P, &str, bool) + 'static,
        >(
            this: *mut ffi::GActionGroup,
            action_name: *mut std::ffi::c_char,
            enabled: glib::ffi::gboolean,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(
                ActionGroup::from_glib_borrow(this).unsafe_cast_ref(),
                &glib::GString::from_glib_borrow(action_name),
                from_glib(enabled),
            )
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            let detailed_signal_name =
                detail.map(|name| format!("action-enabled-changed::{name}\0"));
            let signal_name: &[u8] = detailed_signal_name
                .as_ref()
                .map_or(c"action-enabled-changed".to_bytes(), |n| n.as_bytes());
            connect_raw(
                self.as_ptr() as *mut _,
                signal_name.as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    action_enabled_changed_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    /// Signals that an action is just about to be removed from the group.
    ///
    /// This signal is emitted before the action is removed, so the action
    /// is still visible and can be queried from the signal handler.
    /// ## `action_name`
    /// the name of the action in @action_group
    #[doc(alias = "action-removed")]
    fn connect_action_removed<F: Fn(&Self, &str) + 'static>(
        &self,
        detail: Option<&str>,
        f: F,
    ) -> SignalHandlerId {
        unsafe extern "C" fn action_removed_trampoline<
            P: IsA<ActionGroup>,
            F: Fn(&P, &str) + 'static,
        >(
            this: *mut ffi::GActionGroup,
            action_name: *mut std::ffi::c_char,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(
                ActionGroup::from_glib_borrow(this).unsafe_cast_ref(),
                &glib::GString::from_glib_borrow(action_name),
            )
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            let detailed_signal_name = detail.map(|name| format!("action-removed::{name}\0"));
            let signal_name: &[u8] = detailed_signal_name
                .as_ref()
                .map_or(c"action-removed".to_bytes(), |n| n.as_bytes());
            connect_raw(
                self.as_ptr() as *mut _,
                signal_name.as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    action_removed_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    /// Signals that the state of the named action has changed.
    /// ## `action_name`
    /// the name of the action in @action_group
    /// ## `value`
    /// the new value of the state
    #[doc(alias = "action-state-changed")]
    fn connect_action_state_changed<F: Fn(&Self, &str, &glib::Variant) + 'static>(
        &self,
        detail: Option<&str>,
        f: F,
    ) -> SignalHandlerId {
        unsafe extern "C" fn action_state_changed_trampoline<
            P: IsA<ActionGroup>,
            F: Fn(&P, &str, &glib::Variant) + 'static,
        >(
            this: *mut ffi::GActionGroup,
            action_name: *mut std::ffi::c_char,
            value: *mut glib::ffi::GVariant,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(
                ActionGroup::from_glib_borrow(this).unsafe_cast_ref(),
                &glib::GString::from_glib_borrow(action_name),
                &from_glib_borrow(value),
            )
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            let detailed_signal_name = detail.map(|name| format!("action-state-changed::{name}\0"));
            let signal_name: &[u8] = detailed_signal_name
                .as_ref()
                .map_or(c"action-state-changed".to_bytes(), |n| n.as_bytes());
            connect_raw(
                self.as_ptr() as *mut _,
                signal_name.as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    action_state_changed_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }
}

impl<O: IsA<ActionGroup>> ActionGroupExt for O {}