iced_aw Documentation

The MenuBar widget manages a tree of menus and items. It acts as the 'root menu' and owns the global state. The hierarchy consists of:

• MenuBar: The entry point widget added to your UI.
• Menu: A container for items, used to build the tree.
• Item: A single entry in a menu. An item can contain a widget and optionally a child Menu.

Note that Item and Menu are helper structures used to build the tree and cannot function independently of a MenuBar.

MenuBar {
    roots: Vec<Item>,
}

Item {
    widget,
    menu: Option<Menu>,
}

Menu {
    items: Vec<Item>,
}

The MenuBar does not have special handling for complex, interactive overlays (like a PickList opened from a menu item). This can lead to:

1. Multiple overlays: If a cursor moves off a nested overlay, the underlying menu may not realize the overlay is gone and remain visible.
2. Stuck menus: If a nested overlay captures events, the MenuBar might receive Cursor::Unavailable and fail to distinguish between a legitimate overlay and the cursor leaving the window, preventing the menu from closing correctly.

Recommendation: If you need nested overlay functionality, replicate it using menus themselves rather than using widgets like PickList inside a menu.

To use iced_aw, add it to your Cargo.toml as a dependency. Because widgets are hidden behind feature gates to allow for cherry-picking, you should either enable specific widget features or use the full feature to enable everything.

Note that iced_aw versions must match your iced version according to the compatibility table.

[dependencies]
iced = "0.14.0"
iced_aw = { version = "0.14.0", features = ["full"] }

To debug MenuBar issues, enable the debug_log feature in your Cargo.toml:

iced_aw = {version = "0.14", features = ["menu", "debug_log"]}

Then, initialize a logger (like env_logger) in your main function:

fn main() {
    env_logger::init();
    // ...
}

Run your application with the RUST_LOG environment variable set to menu=debug:

RUST_LOG=menu=debug cargo run

To run the built-in menu example with debugging enabled:

RUST_LOG=menu=debug cargo run --example menu --features "debug_log"

The iced_aw library provides two ways to implement a sidebar layout:

1. Sidebar: A standalone widget used to display tabs for selecting content. It is typically placed to the side of your main content. You are responsible for managing the logic that determines which content is displayed based on the selected tab.
2. SidebarWithContent: A single, unified widget that contains both the sidebar and the content area. It manages the display of the content automatically based on the selected tab.

The Position enum controls the layout of elements within a tab when using TabLabel::IconText or when a close icon is present:

• Position::Start: The icon (or close icon) is placed at the beginning of the tab.
• Position::End: The icon (or close icon) is placed at the end of the tab.

Use Sidebar::set_position(position) to set the icon/text order and Sidebar::set_close_position(position) to set the close icon's position.

When using TabLabel::IconText, you can control the layout of the icon relative to the text using the Position enum via the .set_position() method.

Available positions:

• Position::Left (Default): Icon is to the left of the text.
• Position::Right: Icon is to the right of the text.
• Position::Top: Icon is above the text.
• Position::Bottom: Icon is below the text.

use iced_aw::Position;

let tab_bar = TabBar::new(Message::TabSelected)
    .push(TabId::One, TabLabel::IconText('⭐', "Star".into()))
    .set_position(Position::Top);

The NumberInput widget enforces constraints based on the provided range:

• Min/Max: The widget tracks the minimum and maximum values. If using an exclusive range like 10..90, the effective maximum is 89 (the last valid step within the range).
• Disabled State: The widget is considered disabled() if the minimum and maximum bounds are equal (e.g., 50..=50), as there is no room for change.
• Button Availability: The increment and decrement buttons automatically enable or disable based on whether the current value can move further within the bounds (can_increase() and can_decrease()).
• Validation: The widget ensures that pasted or typed values are valid within the defined range before updating the internal state.

The TimePicker uses the Time type from iced_aw::core::time.

Common ways to create Time instances:

• Time::now_hm(use_24h: bool): Current hour and minute.
• Time::now_hms(use_24h: bool): Current hour, minute, and second.

Variants of Time:

• Time::Hm { hour, minute, period }: Hour and minute with an AM/PM Period or H24.
• Time::Hms { hour, minute, second, period }: Hour, minute, and second with a Period.