diff --git a/src/widget/menu/action.rs b/src/widget/menu/action.rs index 086210ea..94da8639 100644 --- a/src/widget/menu/action.rs +++ b/src/widget/menu/action.rs @@ -1,7 +1,57 @@ use crate::widget::segmented_button::Entity; +/// `MenuAction` is a trait that represents an action in a menu. +/// +/// It is used to define the behavior of menu items when they are activated. +/// Each menu item can have a unique action associated with it. +/// +/// This trait is generic over a type `Message` which is the type of message +/// that will be produced when the action is triggered. +/// +/// # Example +/// +/// ``` +/// use cosmic::widget::menu::action::MenuAction; +/// use cosmic::widget::segmented_button::Entity; +/// +/// #[derive(Clone, Copy, Eq, PartialEq)] +/// enum MyMessage { +/// Open, +/// Save, +/// Quit, +/// } +/// +/// #[derive(Clone, Copy, Eq, PartialEq)] +/// enum MyAction { +/// Open, +/// Save, +/// Quit, +/// } +/// +/// impl MenuAction for MyAction { +/// type Message = MyMessage; +/// +/// fn message(&self, entity: Option) -> Self::Message { +/// match self { +/// MyAction::Open => MyMessage::Open, +/// MyAction::Save => MyMessage::Save, +/// MyAction::Quit => MyMessage::Quit, +/// } +/// } +/// } +/// ``` pub trait MenuAction: Clone + Copy + Eq + PartialEq { + /// The type of message that will be produced when the action is triggered. type Message; + /// Returns a message of type `Self::Message` when the action is triggered. + /// + /// # Arguments + /// + /// * `entity` - An optional `Entity` that may be associated with the action. + /// + /// # Returns + /// + /// * `Self::Message` - The message that is produced when the action is triggered. fn message(&self, entity: Option) -> Self::Message; } diff --git a/src/widget/menu/key_bind.rs b/src/widget/menu/key_bind.rs index 63bfb6b1..4afc7552 100644 --- a/src/widget/menu/key_bind.rs +++ b/src/widget/menu/key_bind.rs @@ -1,6 +1,13 @@ use iced_core::keyboard::{Key, Modifiers}; use std::fmt; +/// Represents the modifier keys on a keyboard. +/// +/// It has four variants: +/// * `Super`: Represents the Super key (also known as the Windows key on Windows, Command key on macOS). +/// * `Ctrl`: Represents the Control key. +/// * `Alt`: Represents the Alt key. +/// * `Shift`: Represents the Shift key. #[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)] pub enum Modifier { Super, @@ -9,13 +16,27 @@ pub enum Modifier { Shift, } +/// Represents a combination of a key and modifiers. +/// It is used to define keyboard shortcuts. #[derive(Clone, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)] pub struct KeyBind { + /// A vector of modifiers for the key binding. pub modifiers: Vec, + /// The key for the key binding. pub key: Key, } impl KeyBind { + /// Checks if the given key and modifiers match the `KeyBind`. + /// + /// # Arguments + /// + /// * `modifiers` - A `Modifiers` instance representing the current active modifiers. + /// * `key` - A reference to the `Key` that is being checked. + /// + /// # Returns + /// + /// * `bool` - `true` if the key and modifiers match the `KeyBind`, `false` otherwise. pub fn matches(&self, modifiers: Modifiers, key: &Key) -> bool { key == &self.key && modifiers.logo() == self.modifiers.contains(&Modifier::Super) diff --git a/src/widget/menu/menu_tree.rs b/src/widget/menu/menu_tree.rs index 595a1235..94cb38a5 100644 --- a/src/widget/menu/menu_tree.rs +++ b/src/widget/menu/menu_tree.rs @@ -137,6 +137,7 @@ where } } +/// This macro creates a button for a MenuTree. macro_rules! menu_button { ($($x:expr),+ $(,)?) => ( widget::button( @@ -154,11 +155,26 @@ macro_rules! menu_button { ); } +/// Represents a menu item that performs an action when selected or a separator between menu items. +/// +/// - `Action` - Represents a menu item that performs an action when selected. +/// - `L` - The label of the menu item. +/// - `A` - The action to perform when the menu item is selected, the action must implement the `MenuAction` trait. +/// - `Separator` - Represents a separator between menu items. pub enum MenuItem>> { + /// Represents a menu item that performs an action when selected. Action(L, A), + /// Represents a separator between menu items. Separator, } +/// Create a root menu item. +/// +/// # Arguments +/// - `label` - The label of the menu item. +/// +/// # Returns +/// - A button for the root menu item. pub fn menu_root<'a, Message, Renderer: renderer::Renderer>( label: impl Into> + 'a, ) -> iced::Element<'a, Message, crate::Theme, Renderer> @@ -172,6 +188,16 @@ where .into() } +/// Create a list of menu items from a vector of `MenuItem`. +/// +/// The `MenuItem` can be either an action or a separator. +/// +/// # Arguments +/// - `key_binds` - A reference to a `HashMap` that maps `KeyBind` to `A`. +/// - `children` - A vector of `MenuItem`. +/// +/// # Returns +/// - A vector of `MenuTree`. pub fn menu_items< 'a, A: MenuAction,