gio/auto/

property_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, Action};
use glib::{prelude::*, translate::*};

glib::wrapper! {
    /// A `GPropertyAction` is a way to get a [`Action`][crate::Action] with a state value
    /// reflecting and controlling the value of a [`glib::Object`][crate::glib::Object] property.
    ///
    /// The state of the action will correspond to the value of the property.
    /// Changing it will change the property (assuming the requested value
    /// matches the requirements as specified in the [type@GObject.ParamSpec]).
    ///
    /// Only the most common types are presently supported.  Booleans are
    /// mapped to booleans, strings to strings, signed/unsigned integers to
    /// int32/uint32 and floats and doubles to doubles.
    ///
    /// If the property is an enum then the state will be string-typed and
    /// conversion will automatically be performed between the enum value and
    /// ‘nick’ string as per the [type@GObject.EnumValue] table.
    ///
    /// Flags types are not currently supported.
    ///
    /// Properties of object types, boxed types and pointer types are not
    /// supported and probably never will be.
    ///
    /// Properties of [type@GLib.Variant] types are not currently supported.
    ///
    /// If the property is boolean-valued then the action will have a `NULL`
    /// parameter type, and activating the action (with no parameter) will
    /// toggle the value of the property.
    ///
    /// In all other cases, the parameter type will correspond to the type of
    /// the property.
    ///
    /// The general idea here is to reduce the number of locations where a
    /// particular piece of state is kept (and therefore has to be synchronised
    /// between). `GPropertyAction` does not have a separate state that is kept
    /// in sync with the property value — its state is the property value.
    ///
    /// For example, it might be useful to create a [`Action`][crate::Action] corresponding
    /// to the `visible-child-name` property of a [`GtkStack`](https://docs.gtk.org/gtk4/class.Stack.html)
    /// so that the current page can be switched from a menu.  The active radio
    /// indication in the menu is then directly determined from the active page of
    /// the `GtkStack`.
    ///
    /// An anti-example would be binding the `active-id` property on a
    /// [`GtkComboBox`](https://docs.gtk.org/gtk4/class.ComboBox.html). This is
    /// because the state of the combo box itself is probably uninteresting and is
    /// actually being used to control something else.
    ///
    /// Another anti-example would be to bind to the `visible-child-name`
    /// property of a [`GtkStack`](https://docs.gtk.org/gtk4/class.Stack.html) if
    /// this value is actually stored in [`Settings`][crate::Settings].  In that case, the
    /// real source of the value is* [`Settings`][crate::Settings].  If you want
    /// a [`Action`][crate::Action] to control a setting stored in [`Settings`][crate::Settings],
    /// see [`SettingsExt::create_action()`][crate::prelude::SettingsExt::create_action()] instead, and possibly combine its
    /// use with [`SettingsExtManual::bind()`][crate::prelude::SettingsExtManual::bind()].
    ///
    /// ## Properties
    ///
    ///
    /// #### `enabled`
    ///  If @action is currently enabled.
    ///
    /// If the action is disabled then calls to g_action_activate() and
    /// g_action_change_state() have no effect.
    ///
    /// Readable
    ///
    ///
    /// #### `invert-boolean`
    ///  If [`true`], the state of the action will be the negation of the
    /// property value, provided the property is boolean.
    ///
    /// Readable | Writeable | Construct Only
    ///
    ///
    /// #### `name`
    ///  The name of the action.  This is mostly meaningful for identifying
    /// the action once it has been added to a #GActionMap.
    ///
    /// Readable | Writeable | Construct Only
    ///
    ///
    /// #### `object`
    ///  The object to wrap a property on.
    ///
    /// The object must be a non-[`None`] #GObject with properties.
    ///
    /// Writeable | Construct Only
    ///
    ///
    /// #### `parameter-type`
    ///  The type of the parameter that must be given when activating the
    /// action.
    ///
    /// Readable
    ///
    ///
    /// #### `property-name`
    ///  The name of the property to wrap on the object.
    ///
    /// The property must exist on the passed-in object and it must be
    /// readable and writable (and not construct-only).
    ///
    /// Writeable | Construct Only
    ///
    ///
    /// #### `state`
    ///  The state of the action, or [`None`] if the action is stateless.
    ///
    /// Readable
    ///
    ///
    /// #### `state-type`
    ///  The #GVariantType of the state that the action has, or [`None`] if the
    /// action is stateless.
    ///
    /// Readable
    /// <details><summary><h4>Action</h4></summary>
    ///
    ///
    /// #### `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
    /// </details>
    ///
    /// # Implements
    ///
    /// [`trait@glib::ObjectExt`], [`ActionExt`][trait@crate::prelude::ActionExt]
    #[doc(alias = "GPropertyAction")]
    pub struct PropertyAction(Object<ffi::GPropertyAction>) @implements Action;

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

impl PropertyAction {
    /// Creates a #GAction corresponding to the value of property
    /// @property_name on @object.
    ///
    /// The property must be existent and readable and writable (and not
    /// construct-only).
    ///
    /// This function takes a reference on @object and doesn't release it
    /// until the action is destroyed.
    /// ## `name`
    /// the name of the action to create
    /// ## `object`
    /// the object that has the property
    ///   to wrap
    /// ## `property_name`
    /// the name of the property
    ///
    /// # Returns
    ///
    /// a new #GPropertyAction
    #[doc(alias = "g_property_action_new")]
    pub fn new(name: &str, object: &impl IsA<glib::Object>, property_name: &str) -> PropertyAction {
        unsafe {
            from_glib_full(ffi::g_property_action_new(
                name.to_glib_none().0,
                object.as_ref().to_glib_none().0,
                property_name.to_glib_none().0,
            ))
        }
    }

    /// If [`true`], the state of the action will be the negation of the
    /// property value, provided the property is boolean.
    #[doc(alias = "invert-boolean")]
    pub fn inverts_boolean(&self) -> bool {
        ObjectExt::property(self, "invert-boolean")
    }
}