Crate muda

Crate muda 

Source
Expand description

muda is a Menu Utilities library for Desktop Applications.

§Platforms supported:

  • Windows
  • macOS
  • Linux (gtk Only)

§Platform-specific notes:

  • On macOS, menus can only be used from the main thread, and most functionality will panic if you try to use it from any other thread.

  • On Windows, accelerators don’t work unless the win32 message loop calls TranslateAcceleratorW. See Menu::init_for_hwnd for more details

§Dependencies (Linux Only)

gtk is used for menus and libxdo is used to make the predfined Copy, Cut, Paste and SelectAll menu items work. Be sure to install following packages before building:

§Arch Linux / Manjaro:
pacman -S gtk3 xdotool
§Debian / Ubuntu:
sudo apt install libgtk-3-dev libxdo-dev

§Example

Create the menu and add your items

let menu = Menu::new();
let menu_item2 = MenuItem::new("Menu item #2", false, None);
let submenu = Submenu::with_items(
    "Submenu Outer",
    true,
    &[
        &MenuItem::new(
            "Menu item #1",
            true,
            Some(Accelerator::new(Some(Modifiers::ALT), Code::KeyD)),
        ),
        &PredefinedMenuItem::separator(),
        &menu_item2,
        &MenuItem::new("Menu item #3", true, None),
        &PredefinedMenuItem::separator(),
        &Submenu::with_items(
            "Submenu Inner",
            true,
            &[
                &MenuItem::new("Submenu item #1", true, None),
                &PredefinedMenuItem::separator(),
                &menu_item2,
            ],
        ).unwrap(),
    ],
);

Then add your root menu to a Window on Windows and Linux or use it as your global app menu on macOS

// --snip--
#[cfg(target_os = "windows")]
unsafe { menu.init_for_hwnd(window_hwnd) };
#[cfg(target_os = "linux")]
menu.init_for_gtk_window(&gtk_window, Some(&vertical_gtk_box));
#[cfg(target_os = "macos")]
menu.init_for_nsapp();

§Context menus (Popup menus)

You can also use a Menu or a Submenu show a context menu.

use muda::ContextMenu;
// --snip--
let position = muda::dpi::PhysicalPosition { x: 100., y: 120. };
#[cfg(target_os = "windows")]
unsafe { menu.show_context_menu_for_hwnd(window_hwnd, Some(position.into())) };
#[cfg(target_os = "linux")]
menu.show_context_menu_for_gtk_window(&gtk_window, Some(position.into()));
#[cfg(target_os = "macos")]
unsafe { menu.show_context_menu_for_nsview(nsview, Some(position.into())) };

§Processing menu events

You can use MenuEvent::receiver to get a reference to the MenuEventReceiver which you can use to listen to events when a menu item is activated

if let Ok(event) = MenuEvent::receiver().try_recv() {
    match event.id {
        id if id == save_item.id() => {
            println!("Save menu item activated");
        },
        _ => {}
    }
}

§Note for winit or tao users:

You should use MenuEvent::set_event_handler and forward the menu events to the event loop by using EventLoopProxy so that the event loop is awakened on each menu event.

enum UserEvent {
  MenuEvent(muda::MenuEvent)
}

let event_loop = EventLoopBuilder::<UserEvent>::with_user_event().build();

let proxy = event_loop.create_proxy();
muda::MenuEvent::set_event_handler(Some(move |event| {
    proxy.send_event(UserEvent::MenuEvent(event));
}));

Re-exports§

pub use about_metadata::AboutMetadata;
pub use crate::about_metadata::AboutMetadataBuilder;
pub use crate::accelerator::AcceleratorParseError;
pub use dpi;

Modules§

about_metadata
Types and functions to create AboutMetadata for the PredefinedMenuItem::about dialog.
accelerator
Accelerators describe keyboard shortcuts for menu items.

Structs§

CheckMenuItem
A check menu item inside a Menu or Submenu and usually contains a text and a check mark or a similar toggle that corresponds to a checked and unchecked states.
CheckMenuItemBuilder
A builder type for CheckMenuItem
Icon
An icon used for the window titlebar, taskbar, etc.
IconMenuItem
An icon menu item inside a Menu or Submenu and usually contains an icon and a text.
IconMenuItemBuilder
A builder type for IconMenuItem
Menu
A root menu that can be added to a Window on Windows and Linux and used as the app global menu on macOS.
MenuEvent
Describes a menu event emitted when a menu item is activated
MenuId
An unique id that is associated with a menu or a menu item.
MenuItem
A menu item inside a Menu or Submenu and contains only text.
MenuItemBuilder
A builder type for MenuItem
PredefinedMenuItem
A predefined (native) menu item which has a predfined behavior by the OS or by this crate.
Submenu
A menu that can be added to a Menu or another Submenu.
SubmenuBuilder
A builder type for Submenu

Enums§

BadIcon
An error produced when using Icon::from_rgba with invalid arguments.
Error
Errors returned by muda.
MenuItemKind
An enumeration of all available menu types, useful to match against the items returned from Menu::items or Submenu::items
NativeIcon
A native Icon to be used for the menu item

Traits§

ContextMenu
A helper trait with methods to help creating a context menu.
IsMenuItem
A trait that defines a generic item in a menu, which may be one of MenuItemKind

Type Aliases§

MenuEventReceiver
A reciever that could be used to listen to menu events.
Result
Convenient type alias of Result type for muda.