Crate muda

Source

Expand description

muda is a Menu Utilities library for Desktop Applications.

§Platforms supported:

Windows
macOS
Linux/BSD with GTK 3 or GTK 4

§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

§Cargo features

The Win32 and AppKit backends are always enabled on Windows and macOS, respectively.

gtk3: Enables the GTK 3 backend on Linux and BSD platforms. This is enabled by default.
gtk4: Enables the GTK 4 backend on Linux and BSD platforms. Disable default features when enabling this feature because the defaults include gtk3.
snapshot: Enables thread-safe menu snapshot types and methods, switching shared menu state to thread-safe synchronization.

When both gtk3 and gtk4 features are enabled, Muda uses the GTK 4 backend.

§Dependencies (Linux/BSD)

The gtk3 feature uses GTK 3 for menus. The gtk4 feature uses GTK 4 for menus. Be sure to install the packages for the GTK backend you enabled before building:

§Arch Linux / Manjaro:

# GTK 3 backend
pacman -S gtk3

# GTK 4 backend
pacman -S gtk4

§Debian / Ubuntu:

# GTK 3 backend
sudo apt install libgtk-3-dev

# GTK 4 backend
sudo apt install libgtk-4-dev

§FreeBSD:

# GTK 3 backend
pkg install -y rust glib pkgconf gtk3

# GTK 4 backend
pkg install -y rust glib pkgconf gtk4

§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(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, GTK 3, or GTK 4 or use it as your global app menu on macOS

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

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

use muda::ContextMenu;
    target_os = "linux",
    target_os = "dragonfly",
    target_os = "freebsd",
    target_os = "netbsd",
    target_os = "openbsd"
))]
// --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(any(
    target_os = "linux",
    target_os = "dragonfly",
    target_os = "freebsd",
    target_os = "netbsd",
    target_os = "openbsd"
))]
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())) };

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
CheckMenuItemSnapshotsnapshot: A thread-safe read projection and activation callback for a crate::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
IconMenuItemSnapshotsnapshot: A thread-safe read projection and activation callback for an crate::IconMenuItem.
Menu: A root menu that can be added to a window on Windows, GTK 3, or GTK 4 and used as the app global menu on macOS.
MenuChangeEventsnapshot: Notification emitted after a menu or menu item changes.
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
MenuItemSnapshotsnapshot: A thread-safe read projection and activation callback for a crate::MenuItem.
MenuSnapshotHandlesnapshot: A thread-safe handle to a menu tree.
PredefinedMenuItem: A predefined (native) menu item which has a predefined behavior by the OS or by this crate.
PredefinedMenuItemSnapshotsnapshot: A thread-safe handle to a read-only projection of a crate::PredefinedMenuItem.
Submenu: A menu that can be added to a Menu or another Submenu.
SubmenuBuilder: A builder type for Submenu
SubmenuSnapshotsnapshot: A thread-safe handle to a read-only projection of a crate::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 crate::Menu::items or Submenu::items
MenuItemKindSnapshotsnapshot: A thread-safe snapshot handle for any menu item kind.
NativeIcon: A native icon to be used for menu items.
SnapshotIconsnapshot: An icon value that can be read from a menu snapshot on any thread.

Traits§

ContextMenu: A trait that defines the behavior and interface for context menus across different platforms.
IsMenuItem: A trait that defines a generic item in a menu, which may be one of MenuItemKind

Type Aliases§

MenuChangeEventReceiversnapshot: A receiver for process-wide menu change notifications.
MenuEventReceiver: A receiver that could be used to listen to menu events.
Result: Convenient type alias of Result type for muda.

Crate muda

Crate muda Copy item path

§Platforms supported:

§Platform-specific notes:

§Cargo features

§Dependencies (Linux/BSD)

§Arch Linux / Manjaro:

§Debian / Ubuntu:

§FreeBSD:

§Example

§Context menus (Popup menus)

§Processing menu events

§Note for winit or tao users:

Re-exports§

Modules§

Structs§

Enums§

Traits§

Type Aliases§

Crate muda