gio/auto/

action.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::{
    prelude::*,
    signal::{connect_raw, SignalHandlerId},
    translate::*,
};
use std::boxed::Box as Box_;

glib::wrapper! {
    /// `GAction` represents a single named action.
    ///
    /// The main interface to an action is that it can be activated with
    /// [`ActionExt::activate()`][crate::prelude::ActionExt::activate()]. This results in the 'activate' signal being
    /// emitted. An activation has a `GVariant` parameter (which may be
    /// `NULL`). The correct type for the parameter is determined by a static
    /// parameter type (which is given at construction time).
    ///
    /// An action may optionally have a state, in which case the state may be
    /// set with [`ActionExt::change_state()`][crate::prelude::ActionExt::change_state()]. This call takes a [type@GLib.Variant]. The
    /// correct type for the state is determined by a static state type
    /// (which is given at construction time).
    ///
    /// The state may have a hint associated with it, specifying its valid
    /// range.
    ///
    /// `GAction` is merely the interface to the concept of an action, as
    /// described above.  Various implementations of actions exist, including
    /// [`SimpleAction`][crate::SimpleAction].
    ///
    /// In all cases, the implementing class is responsible for storing the
    /// name of the action, the parameter type, the enabled state, the optional
    /// state type and the state and emitting the appropriate signals when these
    /// change. The implementor is responsible for filtering calls to
    /// [`ActionExt::activate()`][crate::prelude::ActionExt::activate()] and [`ActionExt::change_state()`][crate::prelude::ActionExt::change_state()]
    /// for type safety and for the state being enabled.
    ///
    /// Probably the only useful thing to do with a `GAction` is to put it
    /// inside of a [`SimpleActionGroup`][crate::SimpleActionGroup].
    ///
    /// ## Properties
    ///
    ///
    /// #### `enabled`
    ///  If @action is currently enabled.
    ///
    /// If the action is disabled then calls to [`ActionExt::activate()`][crate::prelude::ActionExt::activate()] and
    /// [`ActionExt::change_state()`][crate::prelude::ActionExt::change_state()] have no effect.
    ///
    /// Readable
    ///
    ///
    /// #### `name`
    ///  The name of the action.  This is mostly meaningful for identifying
    /// the action once it has been added to a [type@Gio.ActionGroup]. It is immutable.
    ///
    /// Readable
    ///
    ///
    /// #### `parameter-type`
    ///  The type of the parameter that must be given when activating the
    /// action. This is immutable, and may be `NULL` if no parameter is needed when
    /// activating the action.
    ///
    /// Readable
    ///
    ///
    /// #### `state`
    ///  The state of the action, or `NULL` if the action is stateless.
    ///
    /// Readable
    ///
    ///
    /// #### `state-type`
    ///  The [type@GLib.VariantType] of the state that the action has, or `NULL` if the
    /// action is stateless. This is immutable.
    ///
    /// Readable
    ///
    /// # Implements
    ///
    /// [`ActionExt`][trait@crate::prelude::ActionExt]
    #[doc(alias = "GAction")]
    pub struct Action(Interface<ffi::GAction, ffi::GActionInterface>);

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

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

    /// Checks if @action_name is valid.
    ///
    /// @action_name is valid if it consists only of alphanumeric characters,
    /// plus `-` and `.`.  The empty string is not a valid action name.
    ///
    /// It is an error to call this function with a non-UTF-8 @action_name.
    /// @action_name must not be `NULL`.
    /// ## `action_name`
    /// a potential action name
    ///
    /// # Returns
    ///
    /// `TRUE` if @action_name is valid
    #[doc(alias = "g_action_name_is_valid")]
    pub fn name_is_valid(action_name: &str) -> bool {
        unsafe { from_glib(ffi::g_action_name_is_valid(action_name.to_glib_none().0)) }
    }

    /// Parses a detailed action name into its separate name and target
    /// components.
    ///
    /// Detailed action names can have three formats.
    ///
    /// The first format is used to represent an action name with no target
    /// value and consists of just an action name containing no whitespace
    /// nor the characters `:`, `(` or `)`.  For example: `app.action`.
    ///
    /// The second format is used to represent an action with a target value
    /// that is a non-empty string consisting only of alphanumerics, plus `-`
    /// and `.`.  In that case, the action name and target value are
    /// separated by a double colon (`::`).  For example:
    /// `app.action::target`.
    ///
    /// The third format is used to represent an action with any type of
    /// target value, including strings.  The target value follows the action
    /// name, surrounded in parens.  For example: `app.action(42)`.  The
    /// target value is parsed using `GLib::Variant::parse()`.  If a tuple-typed
    /// value is desired, it must be specified in the same way, resulting in
    /// two sets of parens, for example: `app.action((1,2,3))`.  A string
    /// target can be specified this way as well: `app.action('target')`.
    /// For strings, this third format must be used if target value is
    /// empty or contains characters other than alphanumerics, `-` and `.`.
    ///
    /// If this function returns `TRUE`, a non-`NULL` value is guaranteed to be returned
    /// in @action_name (if a pointer is passed in). A `NULL` value may still be
    /// returned in @target_value, as the @detailed_name may not contain a target.
    ///
    /// If returned, the [type@GLib.Variant] in @target_value is guaranteed to not be floating.
    /// ## `detailed_name`
    /// a detailed action name
    ///
    /// # Returns
    ///
    /// `TRUE` if successful, else `FALSE` with @error set
    ///
    /// ## `action_name`
    /// the action name
    ///
    /// ## `target_value`
    /// the target value,
    ///   or `NULL` for no target
    #[doc(alias = "g_action_parse_detailed_name")]
    pub fn parse_detailed_name(
        detailed_name: &str,
    ) -> Result<(glib::GString, Option<glib::Variant>), glib::Error> {
        unsafe {
            let mut action_name = std::ptr::null_mut();
            let mut target_value = std::ptr::null_mut();
            let mut error = std::ptr::null_mut();
            let is_ok = ffi::g_action_parse_detailed_name(
                detailed_name.to_glib_none().0,
                &mut action_name,
                &mut target_value,
                &mut error,
            );
            debug_assert_eq!(is_ok == glib::ffi::GFALSE, !error.is_null());
            if error.is_null() {
                Ok((from_glib_full(action_name), from_glib_full(target_value)))
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Formats a detailed action name from @action_name and @target_value.
    ///
    /// It is an error to call this function with an invalid action name.
    ///
    /// This function is the opposite of [`parse_detailed_name()`][Self::parse_detailed_name()].
    /// It will produce a string that can be parsed back to the @action_name
    /// and @target_value by that function.
    ///
    /// See that function for the types of strings that will be printed by
    /// this function.
    /// ## `action_name`
    /// a valid action name
    /// ## `target_value`
    /// a [type@GLib.Variant] target value, or `NULL`
    ///
    /// # Returns
    ///
    /// a detailed format string
    #[doc(alias = "g_action_print_detailed_name")]
    pub fn print_detailed_name(
        action_name: &str,
        target_value: Option<&glib::Variant>,
    ) -> glib::GString {
        unsafe {
            from_glib_full(ffi::g_action_print_detailed_name(
                action_name.to_glib_none().0,
                target_value.to_glib_none().0,
            ))
        }
    }
}

/// Trait containing all [`struct@Action`] methods.
///
/// # Implementors
///
/// [`Action`][struct@crate::Action], [`PropertyAction`][struct@crate::PropertyAction], [`SimpleAction`][struct@crate::SimpleAction]
pub trait ActionExt: IsA<Action> + 'static {
    /// Activates the action.
    ///
    /// @parameter must be the correct type of parameter for the action (ie:
    /// the parameter type given at construction time).  If the parameter
    /// type was `NULL` then @parameter must also be `NULL`.
    ///
    /// If the @parameter [type@GLib.Variant] is floating, it is consumed.
    /// ## `parameter`
    /// the parameter to the activation
    #[doc(alias = "g_action_activate")]
    fn activate(&self, parameter: Option<&glib::Variant>) {
        unsafe {
            ffi::g_action_activate(self.as_ref().to_glib_none().0, parameter.to_glib_none().0);
        }
    }

    /// Request for the state of @self to be changed to @value.
    ///
    /// The action must be stateful and @value must be of the correct type.
    /// See [`state_type()`][Self::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 [`state_hint()`][Self::state_hint()].
    ///
    /// If the @value [type@GLib.Variant] is floating, it is consumed.
    /// ## `value`
    /// the new state
    #[doc(alias = "g_action_change_state")]
    fn change_state(&self, value: &glib::Variant) {
        unsafe {
            ffi::g_action_change_state(self.as_ref().to_glib_none().0, value.to_glib_none().0);
        }
    }

    /// Checks if @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.
    ///
    /// # Returns
    ///
    /// whether the action is enabled
    #[doc(alias = "g_action_get_enabled")]
    #[doc(alias = "get_enabled")]
    #[doc(alias = "enabled")]
    fn is_enabled(&self) -> bool {
        unsafe { from_glib(ffi::g_action_get_enabled(self.as_ref().to_glib_none().0)) }
    }

    /// Queries the name of @self.
    ///
    /// # Returns
    ///
    /// the name of the action
    #[doc(alias = "g_action_get_name")]
    #[doc(alias = "get_name")]
    fn name(&self) -> glib::GString {
        unsafe { from_glib_none(ffi::g_action_get_name(self.as_ref().to_glib_none().0)) }
    }

    /// Queries the type of the parameter that must be given when activating
    /// @self.
    ///
    /// When activating the action using [`activate()`][Self::activate()], 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.
    ///
    /// # Returns
    ///
    /// the parameter type
    #[doc(alias = "g_action_get_parameter_type")]
    #[doc(alias = "get_parameter_type")]
    #[doc(alias = "parameter-type")]
    fn parameter_type(&self) -> Option<glib::VariantType> {
        unsafe {
            from_glib_none(ffi::g_action_get_parameter_type(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Queries the current state of @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 [`state_type()`][Self::state_type()].
    ///
    /// The return value (if non-`NULL`) should be freed with
    /// `GLib::Variant::unref()` when it is no longer required.
    ///
    /// # Returns
    ///
    /// the current state of the action
    #[doc(alias = "g_action_get_state")]
    #[doc(alias = "get_state")]
    fn state(&self) -> Option<glib::Variant> {
        unsafe { from_glib_full(ffi::g_action_get_state(self.as_ref().to_glib_none().0)) }
    }

    /// Requests a hint about the valid range of values for the state of
    /// @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.
    ///
    /// # Returns
    ///
    /// the state range hint
    #[doc(alias = "g_action_get_state_hint")]
    #[doc(alias = "get_state_hint")]
    fn state_hint(&self) -> Option<glib::Variant> {
        unsafe { from_glib_full(ffi::g_action_get_state_hint(self.as_ref().to_glib_none().0)) }
    }

    /// Queries the type of the state of @self.
    ///
    /// If the action is stateful (e.g. created with
    /// [`SimpleAction::new_stateful()`][crate::SimpleAction::new_stateful()]) then this function returns the
    /// [type@GLib.VariantType] of the state.  This is the type of the initial value
    /// given as the state. All calls to [`change_state()`][Self::change_state()] must give a
    /// [type@GLib.Variant] of this type and [`state()`][Self::state()] will return a
    /// [type@GLib.Variant] of the same type.
    ///
    /// If the action is not stateful (e.g. created with [`SimpleAction::new()`][crate::SimpleAction::new()])
    /// then this function will return `NULL`. In that case, [`state()`][Self::state()]
    /// will return `NULL` and you must not call [`change_state()`][Self::change_state()].
    ///
    /// # Returns
    ///
    /// the state type, if the action is stateful
    #[doc(alias = "g_action_get_state_type")]
    #[doc(alias = "get_state_type")]
    #[doc(alias = "state-type")]
    fn state_type(&self) -> Option<glib::VariantType> {
        unsafe { from_glib_none(ffi::g_action_get_state_type(self.as_ref().to_glib_none().0)) }
    }

    #[doc(alias = "enabled")]
    fn connect_enabled_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn notify_enabled_trampoline<P: IsA<Action>, F: Fn(&P) + 'static>(
            this: *mut ffi::GAction,
            _param_spec: glib::ffi::gpointer,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(Action::from_glib_borrow(this).unsafe_cast_ref())
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                b"notify::enabled\0".as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    notify_enabled_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    #[doc(alias = "name")]
    fn connect_name_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn notify_name_trampoline<P: IsA<Action>, F: Fn(&P) + 'static>(
            this: *mut ffi::GAction,
            _param_spec: glib::ffi::gpointer,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(Action::from_glib_borrow(this).unsafe_cast_ref())
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                b"notify::name\0".as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    notify_name_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    #[doc(alias = "parameter-type")]
    fn connect_parameter_type_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn notify_parameter_type_trampoline<
            P: IsA<Action>,
            F: Fn(&P) + 'static,
        >(
            this: *mut ffi::GAction,
            _param_spec: glib::ffi::gpointer,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(Action::from_glib_borrow(this).unsafe_cast_ref())
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                b"notify::parameter-type\0".as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    notify_parameter_type_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    #[doc(alias = "state")]
    fn connect_state_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn notify_state_trampoline<P: IsA<Action>, F: Fn(&P) + 'static>(
            this: *mut ffi::GAction,
            _param_spec: glib::ffi::gpointer,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(Action::from_glib_borrow(this).unsafe_cast_ref())
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                b"notify::state\0".as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    notify_state_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    #[doc(alias = "state-type")]
    fn connect_state_type_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn notify_state_type_trampoline<P: IsA<Action>, F: Fn(&P) + 'static>(
            this: *mut ffi::GAction,
            _param_spec: glib::ffi::gpointer,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(Action::from_glib_borrow(this).unsafe_cast_ref())
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                b"notify::state-type\0".as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    notify_state_type_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }
}

impl<O: IsA<Action>> ActionExt for O {}