// 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::{MenuAttributeIter, MenuLinkIter};
use glib::{
    prelude::*,
    signal::{connect_raw, SignalHandlerId},
    translate::*,
};
use std::{boxed::Box as Box_, fmt, mem::transmute};

glib::wrapper! {
    /// [`MenuModel`][crate::MenuModel] represents the contents of a menu -- an ordered list of
    /// menu items. The items are associated with actions, which can be
    /// activated through them. Items can be grouped in sections, and may
    /// have submenus associated with them. Both items and sections usually
    /// have some representation data, such as labels or icons. The type of
    /// the associated action (ie whether it is stateful, and what kind of
    /// state it has) can influence the representation of the item.
    ///
    /// The conceptual model of menus in [`MenuModel`][crate::MenuModel] is hierarchical:
    /// sections and submenus are again represented by `GMenuModels`.
    /// Menus themselves do not define their own roles. Rather, the role
    /// of a particular [`MenuModel`][crate::MenuModel] is defined by the item that references
    /// it (or, in the case of the 'root' menu, is defined by the context
    /// in which it is used).
    ///
    /// As an example, consider the visible portions of this menu:
    ///
    /// ## An example menu # {`menu`-example}
    ///
    /// ![](menu-example.png)
    ///
    /// There are 8 "menus" visible in the screenshot: one menubar, two
    /// submenus and 5 sections:
    ///
    /// - the toplevel menubar (containing 4 items)
    /// - the View submenu (containing 3 sections)
    /// - the first section of the View submenu (containing 2 items)
    /// - the second section of the View submenu (containing 1 item)
    /// - the final section of the View submenu (containing 1 item)
    /// - the Highlight Mode submenu (containing 2 sections)
    /// - the Sources section (containing 2 items)
    /// - the Markup section (containing 2 items)
    ///
    /// The [example][menu-model] illustrates the conceptual connection between
    /// these 8 menus. Each large block in the figure represents a menu and the
    /// smaller blocks within the large block represent items in that menu. Some
    /// items contain references to other menus.
    ///
    /// ## A menu example # {`menu`-model}
    ///
    /// ![](menu-model.png)
    ///
    /// Notice that the separators visible in the [example][menu-example]
    /// appear nowhere in the [menu model][menu-model]. This is because
    /// separators are not explicitly represented in the menu model. Instead,
    /// a separator is inserted between any two non-empty sections of a menu.
    /// Section items can have labels just like any other item. In that case,
    /// a display system may show a section header instead of a separator.
    ///
    /// The motivation for this abstract model of application controls is
    /// that modern user interfaces tend to make these controls available
    /// outside the application. Examples include global menus, jumplists,
    /// dash boards, etc. To support such uses, it is necessary to 'export'
    /// information about actions and their representation in menus, which
    /// is exactly what the [GActionGroup exporter][gio-GActionGroup-exporter]
    /// and the [GMenuModel exporter][gio-GMenuModel-exporter] do for
    /// [`ActionGroup`][crate::ActionGroup] and [`MenuModel`][crate::MenuModel]. The client-side counterparts to
    /// make use of the exported information are [`DBusActionGroup`][crate::DBusActionGroup] and
    /// [`DBusMenuModel`][crate::DBusMenuModel].
    ///
    /// The API of [`MenuModel`][crate::MenuModel] is very generic, with iterators for the
    /// attributes and links of an item, see [`MenuModelExt::iterate_item_attributes()`][crate::prelude::MenuModelExt::iterate_item_attributes()]
    /// and [`MenuModelExt::iterate_item_links()`][crate::prelude::MenuModelExt::iterate_item_links()]. The 'standard' attributes and
    /// link types have predefined names: [`MENU_ATTRIBUTE_LABEL`][crate::MENU_ATTRIBUTE_LABEL],
    /// [`MENU_ATTRIBUTE_ACTION`][crate::MENU_ATTRIBUTE_ACTION], [`MENU_ATTRIBUTE_TARGET`][crate::MENU_ATTRIBUTE_TARGET], [`MENU_LINK_SECTION`][crate::MENU_LINK_SECTION]
    /// and [`MENU_LINK_SUBMENU`][crate::MENU_LINK_SUBMENU].
    ///
    /// Items in a [`MenuModel`][crate::MenuModel] represent active controls if they refer to
    /// an action that can get activated when the user interacts with the
    /// menu item. The reference to the action is encoded by the string id
    /// in the [`MENU_ATTRIBUTE_ACTION`][crate::MENU_ATTRIBUTE_ACTION] attribute. An action id uniquely
    /// identifies an action in an action group. Which action group(s) provide
    /// actions depends on the context in which the menu model is used.
    /// E.g. when the model is exported as the application menu of a
    /// `GtkApplication`, actions can be application-wide or window-specific
    /// (and thus come from two different action groups). By convention, the
    /// application-wide actions have names that start with "app.", while the
    /// names of window-specific actions start with "win.".
    ///
    /// While a wide variety of stateful actions is possible, the following
    /// is the minimum that is expected to be supported by all users of exported
    /// menu information:
    /// - an action with no parameter type and no state
    /// - an action with no parameter type and boolean state
    /// - an action with string parameter type and string state
    ///
    /// ## Stateless
    ///
    /// A stateless action typically corresponds to an ordinary menu item.
    ///
    /// Selecting such a menu item will activate the action (with no parameter).
    ///
    /// ## Boolean State
    ///
    /// An action with a boolean state will most typically be used with a "toggle"
    /// or "switch" menu item. The state can be set directly, but activating the
    /// action (with no parameter) results in the state being toggled.
    ///
    /// Selecting a toggle menu item will activate the action. The menu item should
    /// be rendered as "checked" when the state is true.
    ///
    /// ## String Parameter and State
    ///
    /// Actions with string parameters and state will most typically be used to
    /// represent an enumerated choice over the items available for a group of
    /// radio menu items. Activating the action with a string parameter is
    /// equivalent to setting that parameter as the state.
    ///
    /// Radio menu items, in addition to being associated with the action, will
    /// have a target value. Selecting that menu item will result in activation
    /// of the action with the target value as the parameter. The menu item should
    /// be rendered as "selected" when the state of the action is equal to the
    /// target value of the menu item.
    ///
    /// This is an Abstract Base Class, you cannot instantiate it.
    ///
    /// ## Signals
    ///
    ///
    /// #### `items-changed`
    ///  Emitted when a change has occurred to the menu.
    ///
    /// The only changes that can occur to a menu is that items are removed
    /// or added. Items may not change (except by being removed and added
    /// back in the same location). This signal is capable of describing
    /// both of those changes (at the same time).
    ///
    /// The signal means that starting at the index `position`, `removed`
    /// items were removed and `added` items were added in their place. If
    /// `removed` is zero then only items were added. If `added` is zero
    /// then only items were removed.
    ///
    /// As an example, if the menu contains items a, b, c, d (in that
    /// order) and the signal (2, 1, 3) occurs then the new composition of
    /// the menu will be a, b, _, _, _, d (with each _ representing some
    /// new item).
    ///
    /// Signal handlers may query the model (particularly the added items)
    /// and expect to see the results of the modification that is being
    /// reported. The signal is emitted after the modification.
    ///
    ///
    ///
    /// # Implements
    ///
    /// [`MenuModelExt`][trait@crate::prelude::MenuModelExt], [`trait@glib::ObjectExt`]
    #[doc(alias = "GMenuModel")]
    pub struct MenuModel(Object<ffi::GMenuModel, ffi::GMenuModelClass>);

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

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

mod sealed {
    pub trait Sealed {}
    impl<T: super::IsA<super::MenuModel>> Sealed for T {}
}

/// Trait containing all [`struct@MenuModel`] methods.
///
/// # Implementors
///
/// [`DBusMenuModel`][struct@crate::DBusMenuModel], [`MenuModel`][struct@crate::MenuModel], [`Menu`][struct@crate::Menu]
pub trait MenuModelExt: IsA<MenuModel> + sealed::Sealed + 'static {
    //#[doc(alias = "g_menu_model_get_item_attribute")]
    //#[doc(alias = "get_item_attribute")]
    //fn is_item_attribute(&self, item_index: i32, attribute: &str, format_string: &str, : /*Unknown conversion*//*Unimplemented*/Basic: VarArgs) -> bool {
    //    unsafe { TODO: call ffi:g_menu_model_get_item_attribute() }
    //}

    /// Queries the item at position `item_index` in `self` for the attribute
    /// specified by `attribute`.
    ///
    /// If `expected_type` is non-[`None`] then it specifies the expected type of
    /// the attribute. If it is [`None`] then any type will be accepted.
    ///
    /// If the attribute exists and matches `expected_type` (or if the
    /// expected type is unspecified) then the value is returned.
    ///
    /// If the attribute does not exist, or does not match the expected type
    /// then [`None`] is returned.
    /// ## `item_index`
    /// the index of the item
    /// ## `attribute`
    /// the attribute to query
    /// ## `expected_type`
    /// the expected type of the attribute, or
    ///  [`None`]
    ///
    /// # Returns
    ///
    /// the value of the attribute
    #[doc(alias = "g_menu_model_get_item_attribute_value")]
    #[doc(alias = "get_item_attribute_value")]
    fn item_attribute_value(
        &self,
        item_index: i32,
        attribute: &str,
        expected_type: Option<&glib::VariantTy>,
    ) -> Option<glib::Variant> {
        unsafe {
            from_glib_full(ffi::g_menu_model_get_item_attribute_value(
                self.as_ref().to_glib_none().0,
                item_index,
                attribute.to_glib_none().0,
                expected_type.to_glib_none().0,
            ))
        }
    }

    /// Queries the item at position `item_index` in `self` for the link
    /// specified by `link`.
    ///
    /// If the link exists, the linked [`MenuModel`][crate::MenuModel] is returned. If the link
    /// does not exist, [`None`] is returned.
    /// ## `item_index`
    /// the index of the item
    /// ## `link`
    /// the link to query
    ///
    /// # Returns
    ///
    /// the linked [`MenuModel`][crate::MenuModel], or [`None`]
    #[doc(alias = "g_menu_model_get_item_link")]
    #[doc(alias = "get_item_link")]
    #[must_use]
    fn item_link(&self, item_index: i32, link: &str) -> Option<MenuModel> {
        unsafe {
            from_glib_full(ffi::g_menu_model_get_item_link(
                self.as_ref().to_glib_none().0,
                item_index,
                link.to_glib_none().0,
            ))
        }
    }

    /// Query the number of items in `self`.
    ///
    /// # Returns
    ///
    /// the number of items
    #[doc(alias = "g_menu_model_get_n_items")]
    #[doc(alias = "get_n_items")]
    fn n_items(&self) -> i32 {
        unsafe { ffi::g_menu_model_get_n_items(self.as_ref().to_glib_none().0) }
    }

    /// Queries if `self` is mutable.
    ///
    /// An immutable [`MenuModel`][crate::MenuModel] will never emit the [`items-changed`][struct@crate::MenuModel#items-changed]
    /// signal. Consumers of the model may make optimisations accordingly.
    ///
    /// # Returns
    ///
    /// [`true`] if the model is mutable (ie: "items-changed" may be
    ///  emitted).
    #[doc(alias = "g_menu_model_is_mutable")]
    fn is_mutable(&self) -> bool {
        unsafe { from_glib(ffi::g_menu_model_is_mutable(self.as_ref().to_glib_none().0)) }
    }

    /// Requests emission of the [`items-changed`][struct@crate::MenuModel#items-changed] signal on `self`.
    ///
    /// This function should never be called except by [`MenuModel`][crate::MenuModel]
    /// subclasses. Any other calls to this function will very likely lead
    /// to a violation of the interface of the model.
    ///
    /// The implementation should update its internal representation of the
    /// menu before emitting the signal. The implementation should further
    /// expect to receive queries about the new state of the menu (and
    /// particularly added menu items) while signal handlers are running.
    ///
    /// The implementation must dispatch this call directly from a mainloop
    /// entry and not in response to calls -- particularly those from the
    /// [`MenuModel`][crate::MenuModel] API. Said another way: the menu must not change while
    /// user code is running without returning to the mainloop.
    /// ## `position`
    /// the position of the change
    /// ## `removed`
    /// the number of items removed
    /// ## `added`
    /// the number of items added
    #[doc(alias = "g_menu_model_items_changed")]
    fn items_changed(&self, position: i32, removed: i32, added: i32) {
        unsafe {
            ffi::g_menu_model_items_changed(
                self.as_ref().to_glib_none().0,
                position,
                removed,
                added,
            );
        }
    }

    /// Creates a [`MenuAttributeIter`][crate::MenuAttributeIter] to iterate over the attributes of
    /// the item at position `item_index` in `self`.
    ///
    /// You must free the iterator with `g_object_unref()` when you are done.
    /// ## `item_index`
    /// the index of the item
    ///
    /// # Returns
    ///
    /// a new [`MenuAttributeIter`][crate::MenuAttributeIter]
    #[doc(alias = "g_menu_model_iterate_item_attributes")]
    fn iterate_item_attributes(&self, item_index: i32) -> MenuAttributeIter {
        unsafe {
            from_glib_full(ffi::g_menu_model_iterate_item_attributes(
                self.as_ref().to_glib_none().0,
                item_index,
            ))
        }
    }

    /// Creates a [`MenuLinkIter`][crate::MenuLinkIter] to iterate over the links of the item at
    /// position `item_index` in `self`.
    ///
    /// You must free the iterator with `g_object_unref()` when you are done.
    /// ## `item_index`
    /// the index of the item
    ///
    /// # Returns
    ///
    /// a new [`MenuLinkIter`][crate::MenuLinkIter]
    #[doc(alias = "g_menu_model_iterate_item_links")]
    fn iterate_item_links(&self, item_index: i32) -> MenuLinkIter {
        unsafe {
            from_glib_full(ffi::g_menu_model_iterate_item_links(
                self.as_ref().to_glib_none().0,
                item_index,
            ))
        }
    }

    /// Emitted when a change has occurred to the menu.
    ///
    /// The only changes that can occur to a menu is that items are removed
    /// or added. Items may not change (except by being removed and added
    /// back in the same location). This signal is capable of describing
    /// both of those changes (at the same time).
    ///
    /// The signal means that starting at the index `position`, `removed`
    /// items were removed and `added` items were added in their place. If
    /// `removed` is zero then only items were added. If `added` is zero
    /// then only items were removed.
    ///
    /// As an example, if the menu contains items a, b, c, d (in that
    /// order) and the signal (2, 1, 3) occurs then the new composition of
    /// the menu will be a, b, _, _, _, d (with each _ representing some
    /// new item).
    ///
    /// Signal handlers may query the model (particularly the added items)
    /// and expect to see the results of the modification that is being
    /// reported. The signal is emitted after the modification.
    /// ## `position`
    /// the position of the change
    /// ## `removed`
    /// the number of items removed
    /// ## `added`
    /// the number of items added
    #[doc(alias = "items-changed")]
    fn connect_items_changed<F: Fn(&Self, i32, i32, i32) + 'static>(
        &self,
        f: F,
    ) -> SignalHandlerId {
        unsafe extern "C" fn items_changed_trampoline<
            P: IsA<MenuModel>,
            F: Fn(&P, i32, i32, i32) + 'static,
        >(
            this: *mut ffi::GMenuModel,
            position: libc::c_int,
            removed: libc::c_int,
            added: libc::c_int,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(
                MenuModel::from_glib_borrow(this).unsafe_cast_ref(),
                position,
                removed,
                added,
            )
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                b"items-changed\0".as_ptr() as *const _,
                Some(transmute::<_, unsafe extern "C" fn()>(
                    items_changed_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }
}

impl<O: IsA<MenuModel>> MenuModelExt for O {}

impl fmt::Display for MenuModel {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        f.write_str("MenuModel")
    }
}