gio/auto/

menu_item.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, Icon, MenuModel};
use glib::{prelude::*, translate::*};

glib::wrapper! {
    /// #GMenuItem is an opaque structure type.  You must access it using the
    /// functions below.
    ///
    /// # Implements
    ///
    /// [`trait@glib::ObjectExt`]
    #[doc(alias = "GMenuItem")]
    pub struct MenuItem(Object<ffi::GMenuItem>);

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

impl MenuItem {
    /// Creates a new #GMenuItem.
    ///
    /// If @label is non-[`None`] it is used to set the "label" attribute of the
    /// new item.
    ///
    /// If @detailed_action is non-[`None`] it is used to set the "action" and
    /// possibly the "target" attribute of the new item.  See
    /// g_menu_item_set_detailed_action() for more information.
    /// ## `label`
    /// the section label, or [`None`]
    /// ## `detailed_action`
    /// the detailed action string, or [`None`]
    ///
    /// # Returns
    ///
    /// a new #GMenuItem
    #[doc(alias = "g_menu_item_new")]
    pub fn new(label: Option<&str>, detailed_action: Option<&str>) -> MenuItem {
        unsafe {
            from_glib_full(ffi::g_menu_item_new(
                label.to_glib_none().0,
                detailed_action.to_glib_none().0,
            ))
        }
    }

    /// Creates a #GMenuItem as an exact copy of an existing menu item in a
    /// #GMenuModel.
    ///
    /// @item_index must be valid (ie: be sure to call
    /// g_menu_model_get_n_items() first).
    /// ## `model`
    /// a #GMenuModel
    /// ## `item_index`
    /// the index of an item in @model
    ///
    /// # Returns
    ///
    /// a new #GMenuItem.
    #[doc(alias = "g_menu_item_new_from_model")]
    #[doc(alias = "new_from_model")]
    pub fn from_model(model: &impl IsA<MenuModel>, item_index: i32) -> MenuItem {
        unsafe {
            from_glib_full(ffi::g_menu_item_new_from_model(
                model.as_ref().to_glib_none().0,
                item_index,
            ))
        }
    }

    /// Creates a new #GMenuItem representing a section.
    ///
    /// This is a convenience API around g_menu_item_new() and
    /// g_menu_item_set_section().
    ///
    /// The effect of having one menu appear as a section of another is
    /// exactly as it sounds: the items from @section become a direct part of
    /// the menu that @menu_item is added to.
    ///
    /// Visual separation is typically displayed between two non-empty
    /// sections.  If @label is non-[`None`] then it will be incorporated into
    /// this visual indication.  This allows for labeled subsections of a
    /// menu.
    ///
    /// As a simple example, consider a typical "Edit" menu from a simple
    /// program.  It probably contains an "Undo" and "Redo" item, followed by
    /// a separator, followed by "Cut", "Copy" and "Paste".
    ///
    /// This would be accomplished by creating three #GMenu instances.  The
    /// first would be populated with the "Undo" and "Redo" items, and the
    /// second with the "Cut", "Copy" and "Paste" items.  The first and
    /// second menus would then be added as submenus of the third.  In XML
    /// format, this would look something like the following:
    ///
    /// ```text
    /// <menu id='edit-menu'>
    ///   <section>
    ///     <item label='Undo'/>
    ///     <item label='Redo'/>
    ///   </section>
    ///   <section>
    ///     <item label='Cut'/>
    ///     <item label='Copy'/>
    ///     <item label='Paste'/>
    ///   </section>
    /// </menu>
    /// ```
    ///
    /// The following example is exactly equivalent.  It is more illustrative
    /// of the exact relationship between the menus and items (keeping in
    /// mind that the 'link' element defines a new menu that is linked to the
    /// containing one).  The style of the second example is more verbose and
    /// difficult to read (and therefore not recommended except for the
    /// purpose of understanding what is really going on).
    ///
    /// ```text
    /// <menu id='edit-menu'>
    ///   <item>
    ///     <link name='section'>
    ///       <item label='Undo'/>
    ///       <item label='Redo'/>
    ///     </link>
    ///   </item>
    ///   <item>
    ///     <link name='section'>
    ///       <item label='Cut'/>
    ///       <item label='Copy'/>
    ///       <item label='Paste'/>
    ///     </link>
    ///   </item>
    /// </menu>
    /// ```
    /// ## `label`
    /// the section label, or [`None`]
    /// ## `section`
    /// a #GMenuModel with the items of the section
    ///
    /// # Returns
    ///
    /// a new #GMenuItem
    #[doc(alias = "g_menu_item_new_section")]
    pub fn new_section(label: Option<&str>, section: &impl IsA<MenuModel>) -> MenuItem {
        unsafe {
            from_glib_full(ffi::g_menu_item_new_section(
                label.to_glib_none().0,
                section.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Creates a new #GMenuItem representing a submenu.
    ///
    /// This is a convenience API around g_menu_item_new() and
    /// g_menu_item_set_submenu().
    /// ## `label`
    /// the section label, or [`None`]
    /// ## `submenu`
    /// a #GMenuModel with the items of the submenu
    ///
    /// # Returns
    ///
    /// a new #GMenuItem
    #[doc(alias = "g_menu_item_new_submenu")]
    pub fn new_submenu(label: Option<&str>, submenu: &impl IsA<MenuModel>) -> MenuItem {
        unsafe {
            from_glib_full(ffi::g_menu_item_new_submenu(
                label.to_glib_none().0,
                submenu.as_ref().to_glib_none().0,
            ))
        }
    }

    //#[doc(alias = "g_menu_item_get_attribute")]
    //#[doc(alias = "get_attribute")]
    //pub fn is_attribute(&self, attribute: &str, format_string: &str, : /*Unknown conversion*//*Unimplemented*/Basic: VarArgs) -> bool {
    //    unsafe { TODO: call ffi:g_menu_item_get_attribute() }
    //}

    /// Queries the named @attribute on @self.
    ///
    /// If @expected_type is specified and the attribute does not have this
    /// type, [`None`] is returned.  [`None`] is also returned if the attribute
    /// simply does not exist.
    /// ## `attribute`
    /// the attribute name to query
    /// ## `expected_type`
    /// the expected type of the attribute
    ///
    /// # Returns
    ///
    /// the attribute value, or [`None`]
    #[doc(alias = "g_menu_item_get_attribute_value")]
    #[doc(alias = "get_attribute_value")]
    pub fn attribute_value(
        &self,
        attribute: &str,
        expected_type: Option<&glib::VariantTy>,
    ) -> Option<glib::Variant> {
        unsafe {
            from_glib_full(ffi::g_menu_item_get_attribute_value(
                self.to_glib_none().0,
                attribute.to_glib_none().0,
                expected_type.to_glib_none().0,
            ))
        }
    }

    /// Queries the named @link on @self.
    /// ## `link`
    /// the link name to query
    ///
    /// # Returns
    ///
    /// the link, or [`None`]
    #[doc(alias = "g_menu_item_get_link")]
    #[doc(alias = "get_link")]
    pub fn link(&self, link: &str) -> Option<MenuModel> {
        unsafe {
            from_glib_full(ffi::g_menu_item_get_link(
                self.to_glib_none().0,
                link.to_glib_none().0,
            ))
        }
    }

    //#[doc(alias = "g_menu_item_set_action_and_target")]
    //pub fn set_action_and_target(&self, action: Option<&str>, format_string: Option<&str>, : /*Unknown conversion*//*Unimplemented*/Basic: VarArgs) {
    //    unsafe { TODO: call ffi:g_menu_item_set_action_and_target() }
    //}

    /// Sets or unsets the "action" and "target" attributes of @self.
    ///
    /// If @action is [`None`] then both the "action" and "target" attributes
    /// are unset (and @target_value is ignored).
    ///
    /// If @action is non-[`None`] then the "action" attribute is set.  The
    /// "target" attribute is then set to the value of @target_value if it is
    /// non-[`None`] or unset otherwise.
    ///
    /// Normal menu items (ie: not submenu, section or other custom item
    /// types) are expected to have the "action" attribute set to identify
    /// the action that they are associated with.  The state type of the
    /// action help to determine the disposition of the menu item.  See
    /// #GAction and #GActionGroup for an overview of actions.
    ///
    /// In general, clicking on the menu item will result in activation of
    /// the named action with the "target" attribute given as the parameter
    /// to the action invocation.  If the "target" attribute is not set then
    /// the action is invoked with no parameter.
    ///
    /// If the action has no state then the menu item is usually drawn as a
    /// plain menu item (ie: with no additional decoration).
    ///
    /// If the action has a boolean state then the menu item is usually drawn
    /// as a toggle menu item (ie: with a checkmark or equivalent
    /// indication).  The item should be marked as 'toggled' or 'checked'
    /// when the boolean state is [`true`].
    ///
    /// If the action has a string state then the menu item is usually drawn
    /// as a radio menu item (ie: with a radio bullet or equivalent
    /// indication).  The item should be marked as 'selected' when the string
    /// state is equal to the value of the @target property.
    ///
    /// See g_menu_item_set_action_and_target() or
    /// g_menu_item_set_detailed_action() for two equivalent calls that are
    /// probably more convenient for most uses.
    /// ## `action`
    /// the name of the action for this item
    /// ## `target_value`
    /// a #GVariant to use as the action target
    #[doc(alias = "g_menu_item_set_action_and_target_value")]
    pub fn set_action_and_target_value(
        &self,
        action: Option<&str>,
        target_value: Option<&glib::Variant>,
    ) {
        unsafe {
            ffi::g_menu_item_set_action_and_target_value(
                self.to_glib_none().0,
                action.to_glib_none().0,
                target_value.to_glib_none().0,
            );
        }
    }

    //#[doc(alias = "g_menu_item_set_attribute")]
    //pub fn set_attribute(&self, attribute: &str, format_string: Option<&str>, : /*Unknown conversion*//*Unimplemented*/Basic: VarArgs) {
    //    unsafe { TODO: call ffi:g_menu_item_set_attribute() }
    //}

    /// Sets or unsets an attribute on @self.
    ///
    /// The attribute to set or unset is specified by @attribute. This
    /// can be one of the standard attribute names [`MENU_ATTRIBUTE_LABEL`][crate::MENU_ATTRIBUTE_LABEL],
    /// [`MENU_ATTRIBUTE_ACTION`][crate::MENU_ATTRIBUTE_ACTION], [`MENU_ATTRIBUTE_TARGET`][crate::MENU_ATTRIBUTE_TARGET], or a custom
    /// attribute name.
    /// Attribute names are restricted to lowercase characters, numbers
    /// and '-'. Furthermore, the names must begin with a lowercase character,
    /// must not end with a '-', and must not contain consecutive dashes.
    ///
    /// must consist only of lowercase
    /// ASCII characters, digits and '-'.
    ///
    /// If @value is non-[`None`] then it is used as the new value for the
    /// attribute.  If @value is [`None`] then the attribute is unset. If
    /// the @value #GVariant is floating, it is consumed.
    ///
    /// See also g_menu_item_set_attribute() for a more convenient way to do
    /// the same.
    /// ## `attribute`
    /// the attribute to set
    /// ## `value`
    /// a #GVariant to use as the value, or [`None`]
    #[doc(alias = "g_menu_item_set_attribute_value")]
    pub fn set_attribute_value(&self, attribute: &str, value: Option<&glib::Variant>) {
        unsafe {
            ffi::g_menu_item_set_attribute_value(
                self.to_glib_none().0,
                attribute.to_glib_none().0,
                value.to_glib_none().0,
            );
        }
    }

    /// Sets the "action" and possibly the "target" attribute of @self.
    ///
    /// The format of @detailed_action is the same format parsed by
    /// g_action_parse_detailed_name().
    ///
    /// See g_menu_item_set_action_and_target() or
    /// g_menu_item_set_action_and_target_value() for more flexible (but
    /// slightly less convenient) alternatives.
    ///
    /// See also g_menu_item_set_action_and_target_value() for a description of
    /// the semantics of the action and target attributes.
    /// ## `detailed_action`
    /// the "detailed" action string
    #[doc(alias = "g_menu_item_set_detailed_action")]
    pub fn set_detailed_action(&self, detailed_action: &str) {
        unsafe {
            ffi::g_menu_item_set_detailed_action(
                self.to_glib_none().0,
                detailed_action.to_glib_none().0,
            );
        }
    }

    /// Sets (or unsets) the icon on @self.
    ///
    /// This call is the same as calling g_icon_serialize() and using the
    /// result as the value to g_menu_item_set_attribute_value() for
    /// [`MENU_ATTRIBUTE_ICON`][crate::MENU_ATTRIBUTE_ICON].
    ///
    /// This API is only intended for use with "noun" menu items; things like
    /// bookmarks or applications in an "Open With" menu.  Don't use it on
    /// menu items corresponding to verbs (eg: stock icons for 'Save' or
    /// 'Quit').
    ///
    /// If @icon is [`None`] then the icon is unset.
    /// ## `icon`
    /// a #GIcon, or [`None`]
    #[doc(alias = "g_menu_item_set_icon")]
    pub fn set_icon(&self, icon: &impl IsA<Icon>) {
        unsafe {
            ffi::g_menu_item_set_icon(self.to_glib_none().0, icon.as_ref().to_glib_none().0);
        }
    }

    /// Sets or unsets the "label" attribute of @self.
    ///
    /// If @label is non-[`None`] it is used as the label for the menu item.  If
    /// it is [`None`] then the label attribute is unset.
    /// ## `label`
    /// the label to set, or [`None`] to unset
    #[doc(alias = "g_menu_item_set_label")]
    pub fn set_label(&self, label: Option<&str>) {
        unsafe {
            ffi::g_menu_item_set_label(self.to_glib_none().0, label.to_glib_none().0);
        }
    }

    /// Creates a link from @self to @model if non-[`None`], or unsets it.
    ///
    /// Links are used to establish a relationship between a particular menu
    /// item and another menu.  For example, [`MENU_LINK_SUBMENU`][crate::MENU_LINK_SUBMENU] is used to
    /// associate a submenu with a particular menu item, and [`MENU_LINK_SECTION`][crate::MENU_LINK_SECTION]
    /// is used to create a section. Other types of link can be used, but there
    /// is no guarantee that clients will be able to make sense of them.
    /// Link types are restricted to lowercase characters, numbers
    /// and '-'. Furthermore, the names must begin with a lowercase character,
    /// must not end with a '-', and must not contain consecutive dashes.
    /// ## `link`
    /// type of link to establish or unset
    /// ## `model`
    /// the #GMenuModel to link to (or [`None`] to unset)
    #[doc(alias = "g_menu_item_set_link")]
    pub fn set_link(&self, link: &str, model: Option<&impl IsA<MenuModel>>) {
        unsafe {
            ffi::g_menu_item_set_link(
                self.to_glib_none().0,
                link.to_glib_none().0,
                model.map(|p| p.as_ref()).to_glib_none().0,
            );
        }
    }

    /// Sets or unsets the "section" link of @self to @section.
    ///
    /// The effect of having one menu appear as a section of another is
    /// exactly as it sounds: the items from @section become a direct part of
    /// the menu that @self is added to.  See g_menu_item_new_section()
    /// for more information about what it means for a menu item to be a
    /// section.
    /// ## `section`
    /// a #GMenuModel, or [`None`]
    #[doc(alias = "g_menu_item_set_section")]
    pub fn set_section(&self, section: Option<&impl IsA<MenuModel>>) {
        unsafe {
            ffi::g_menu_item_set_section(
                self.to_glib_none().0,
                section.map(|p| p.as_ref()).to_glib_none().0,
            );
        }
    }

    /// Sets or unsets the "submenu" link of @self to @submenu.
    ///
    /// If @submenu is non-[`None`], it is linked to.  If it is [`None`] then the
    /// link is unset.
    ///
    /// The effect of having one menu appear as a submenu of another is
    /// exactly as it sounds.
    /// ## `submenu`
    /// a #GMenuModel, or [`None`]
    #[doc(alias = "g_menu_item_set_submenu")]
    pub fn set_submenu(&self, submenu: Option<&impl IsA<MenuModel>>) {
        unsafe {
            ffi::g_menu_item_set_submenu(
                self.to_glib_none().0,
                submenu.map(|p| p.as_ref()).to_glib_none().0,
            );
        }
    }
}