### Complete SidebarWithContent Example

Source: https://github.com/iced-rs/iced_aw/blob/main/_autodocs/api-reference/sidebar.md

A comprehensive example demonstrating the setup and usage of SidebarWithContent, including defining messages, creating sidebar items, setting up content, and configuring sidebar properties like width and position.

```rust
use iced::{Element, Length};
use iced::widget::{Column, Button, Text, Container};
use iced_aw::{Sidebar, SidebarWithContent};

#[derive(Debug, Clone)]
enum Message {
    ItemSelected(usize),
}

fn view() -> Element<'static, Message> {
    let sidebar_items = Column::new()
        .push(Button::new(Text::new("Home")).on_press(Message::ItemSelected(0)))
        .push(Button::new(Text::new("Settings")).on_press(Message::ItemSelected(1)))
        .push(Button::new(Text::new("Help")).on_press(Message::ItemSelected(2)))
        .spacing(10)
        .padding(10);

    let content = Container::new(
        Text::new("Welcome to the application")
    )
    .width(Length::Fill)
    .height(Length::Fill)
    .center_x()
    .center_y();

    SidebarWithContent::new(sidebar_items, content)
        .sidebar_width(Length::Fixed(200.0))
        .position(iced_aw::sidebar::Position::Left)
        .divider_width(2.0)
        .spacing(10)
        .into()
}
```

--------------------------------

### Running Examples

Source: https://github.com/iced-rs/iced_aw/blob/main/_autodocs/INDEX.md

Examples can be run from the repository using Cargo. Ensure to enable the necessary features for specific examples.

```bash
cargo run --example badge --features badge
cargo run --example tabs --features tabs
```

--------------------------------

### Run Menu Example with Debug Logging

Source: https://github.com/iced-rs/iced_aw/blob/main/src/widget/menu/README.md

Run the specific 'menu' example provided with the iced_aw crate, enabling the 'debug_log' feature and setting the RUST_LOG environment variable for detailed logging.

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

--------------------------------

### Complete Menu Bar Example with Nested Menus and Message Handling

Source: https://github.com/iced-rs/iced_aw/blob/main/_autodocs/api-reference/menu.md

This example demonstrates how to build a fully functional menu bar with nested menus for 'File' and 'Edit' actions. It includes message enums for handling user interactions and uses `Container` for layout.

```rust
use iced::{Element, Length};
use iced::widget::{Button, Text, Container};
use iced_aw::menu::{MenuBar, Item, Menu};

#[derive(Debug, Clone)]
enum Message {
    FileNew,
    FileOpen,
    FileSave,
    EditCut,
    EditCopy,
    EditPaste,
}

fn menu_bar() -> Element<'static, Message> {
    let file_menu = Menu::new(vec![
        Item::new(Button::new(Text::new("New")).on_press(Message::FileNew)),
        Item::new(Button::new(Text::new("Open")).on_press(Message::FileOpen)),
        Item::new(Button::new(Text::new("Save")).on_press(Message::FileSave)),
    ]);

    let edit_menu = Menu::new(vec![
        Item::new(Button::new(Text::new("Cut")).on_press(Message::EditCut)),
        Item::new(Button::new(Text::new("Copy")).on_press(Message::EditCopy)),
        Item::new(Button::new(Text::new("Paste")).on_press(Message::EditPaste)),
    ]);

    let menu = MenuBar::new(vec![
        Item::with_menu(Button::new(Text::new("File")), file_menu),
        Item::with_menu(Button::new(Text::new("Edit")), edit_menu),
    ]);

    Container::new(menu)
        .width(Length::Fill)
        .into()
}
```

--------------------------------

### Complete ColorPicker Example with Overlay Integration

Source: https://github.com/iced-rs/iced_aw/blob/main/_autodocs/api-reference/color-picker.md

A full example demonstrating the integration of the ColorPicker widget within an application, including state management for the picker's visibility and handling color selection and changes.

```rust
use iced::{Element, Color};
use iced::widget::{Button, Text, Container, Row};
use iced_aw::ColorPicker;

#[derive(Debug, Clone)]
enum Message {
    ShowColorPicker,
    HideColorPicker,
    ColorSelected(Color),
    ColorChanging(Color),
}

struct App {
    color: Color,
    picker_open: bool,
}

fn view(&self) -> Element<Message> {
    let button = Button::new(
        Text::new(format!("Pick Color: {:?}", self.color))
    ).on_press(Message::ShowColorPicker);

    Container::new(Row::new().push(button))
        .into()
}

// With picker overlay integration:
fn view_with_picker(&self) -> Element<Message> {
    ColorPicker::new(
        self.picker_open,
        self.color,
        Button::new(Text::new("Open")).on_press(Message::ShowColorPicker),
        Message::HideColorPicker,
        Message::ColorSelected
    )
    .on_color_change(Message::ColorChanging)
    .into()
}
```

--------------------------------

### Simulator API Usage Example

Source: https://github.com/iced-rs/iced_aw/blob/main/tests/README.md

Demonstrates how to use the simulator to interact with a widget, simulate clicks, and process resulting messages.

```rust
let (mut app, _) = App::new(|| Widget::new().into());
let mut ui = simulator(&app);

ui.click("Target")?;

let mut got_message = false;
for message in ui.into_messages() {
    got_message = true;
    app.update(message);
}

assert!(got_message);
Ok(())
```

--------------------------------

### Complete NumberInput Example

Source: https://github.com/iced-rs/iced_aw/blob/main/_autodocs/api-reference/number-input.md

Demonstrates how to create and configure a NumberInput widget with a specific value range, step, padding, size, and submit behavior.

```rust
use iced::{Element, Length};
use iced_aw::NumberInput;

#[derive(Debug, Clone)]
enum Message {
    NumberChanged(i32),
    NumberSubmitted,
}

fn view(value: i32) -> Element<'static, Message> {
    NumberInput::new(
        &value,
        -100..=100,
        Message::NumberChanged
    )
    .step(5)
    .padding(8)
    .size(16)
    .on_submit(Message::NumberSubmitted)
    .width(Length::Fixed(150.0))
    .into()
}
```

--------------------------------

### Badge Widget Example

Source: https://github.com/iced-rs/iced_aw/blob/main/_autodocs/README.md

A simple example demonstrating the creation and basic customization of a Badge widget. This widget is suitable for highlighting status or small pieces of information.

```rust
// Example from documentation
let widget = Badge::new(Text::new("Status"))
    .padding(8)
    .into();
```

--------------------------------

### ColorPicker Constructor Example

Source: https://github.com/iced-rs/iced_aw/blob/main/_autodocs/api-reference/color-picker.md

Demonstrates how to create a ColorPicker instance with an underlay button and message callbacks for cancel and submit actions.

```rust
use iced::{Color, Element};
use iced::widget::{Button, Text};
use iced_aw::ColorPicker;

#[derive(Debug, Clone)]
enum Message {
    OpenColorPicker,
    CancelColorPicker,
    ColorSelected(Color),
}

let picker = ColorPicker::new(
    false,
    Color::WHITE,
    Button::new(Text::new("Pick color")).on_press(Message::OpenColorPicker),
    Message::CancelColorPicker,
    Message::ColorSelected
);
```

--------------------------------

### Example Cargo.toml for Iced and Iced-Aw Dependencies

Source: https://github.com/iced-rs/iced_aw/blob/main/_autodocs/configuration.md

Configure your project's dependencies in Cargo.toml to include Iced and Iced-Aw with desired features. This example shows common features for badge, card, tabs, and more.

```toml
[package]
name = "my-app"
edition = "2021"

[dependencies]
iced = { version = "0.14.0", features = ["tokio", "advanced"] }
iced_aw = { version = "0.14.1", features = [
    "badge",
    "card",
    "tabs",
    "color_picker",
    "date_picker",
    "number_input",
] }

[dev-dependencies]
iced_test = "0.14"
```

--------------------------------

### Test Naming Convention Example

Source: https://github.com/iced-rs/iced_aw/blob/main/tests/README.md

Follow a consistent naming pattern for test functions, starting with the widget name followed by a description of the test.

```rust
fn <widget_name>_<test_description>()
```

--------------------------------

### Complete Badge Example

Source: https://github.com/iced-rs/iced_aw/blob/main/_autodocs/api-reference/badge.md

Demonstrates how to create and configure a Badge widget with text content, padding, dimensions, alignment, and custom styling. This snippet requires the `badge` feature to be enabled.

```rust
use iced::{Element, Alignment};
use iced::widget::Text;
use iced_aw::{Badge, style};

#[derive(Debug, Clone)]
enum Message {
    // Your messages
}

fn view() -> Element<'static, Message> {
    Badge::new(Text::new("Active"))
        .padding(8)
        .width(120)
        .height(40)
        .align_x(Alignment::Center)
        .align_y(Alignment::Center)
        .style(style::badge::primary)
        .into()
}
```

--------------------------------

### Theme Integration Example

Source: https://github.com/iced-rs/iced_aw/blob/main/_autodocs/types.md

Demonstrates how to integrate custom styles with Iced's theme system using the Catalog trait for custom theme implementations.

```rust
use iced::Theme;
use iced_aw::style::badge::Catalog;

// Get default style
let style = Theme::default().style(&default_class, Status::Active);

// Custom theme implementation
impl Catalog for CustomTheme {
    type Class<'a> = StyleFn<'a, Self, Style>;
    
    fn default<'a>() -> Self::Class<'a> {
        Box::new(|_theme, _status| Style::default())
    }
    
    fn style(&self, class: &Self::Class<'_>, status: Status) -> Style {
        class(self, status)
    }
}
```

--------------------------------

### Complete Tabs Widget Example

Source: https://github.com/iced-rs/iced_aw/blob/main/_autodocs/api-reference/tabs.md

Demonstrates how to create and configure a Tabs widget with multiple tabs, custom messages for tab selection and closing, and various styling options.

```rust
use iced::{Element, Length};
use iced_aw::{Tabs, TabLabel};
use iced::widget::Text;

#[derive(Debug, Clone, Copy, Eq, PartialEq)]
enum TabId {
    Home,
    Settings,
    About,
}

#[derive(Debug, Clone)]
enum Message {
    TabSelected(TabId),
    TabClosed(TabId),
}

fn view(active: TabId) -> Element<'static, Message> {
    Tabs::new(Message::TabSelected)
        .push(
            TabId::Home,
            TabLabel::Text("Home".into()),
            Text::new("Welcome to home tab").into()
        )
        .push(
            TabId::Settings,
            TabLabel::Text("Settings".into()),
            Text::new("Configure your settings").into()
        )
        .push(
            TabId::About,
            TabLabel::Text("About".into()),
            Text::new("About this application").into()
        )
        .set_active_tab(&active)
        .close_size(14.0)
        .on_close(Message::TabClosed)
        .tab_bar_position(iced_aw::tabs::TabBarPosition::Top)
        .width(Length::Fill)
        .height(Length::Fill)
        .into()
}
```

--------------------------------

### Date Creation Example

Source: https://github.com/iced-rs/iced_aw/blob/main/_autodocs/INDEX.md

Demonstrates fallible date creation using `NaiveDate::from_ymd_opt` which returns an Option, unlike the panicking `Date::from_ymd`.

```rust
// Date creation (panics on invalid values)
let date = Date::from_ymd(2024, 13, 32); // Panics!

// With chrono conversion (fallible)
let naive_date = NaiveDate::from_ymd_opt(2024, 1, 1);
```

--------------------------------

### SidebarWithContent Example

Source: https://github.com/iced-rs/iced_aw/blob/main/_autodocs/api-reference/sidebar.md

Demonstrates creating a SidebarWithContent widget with a column of buttons for the sidebar and text for the main content. This is a common pattern for application layouts.

```rust
use iced::widget::{Column, Button, Text};
use iced_aw::SidebarWithContent;

let sidebar = Column::new()
    .push(Button::new(Text::new("Option 1")))
    .push(Button::new(Text::new("Option 2")));

let content = Text::new("Main content area");

let layout = SidebarWithContent::new(sidebar, content);
```

--------------------------------

### Example Test File Structure

Source: https://github.com/iced-rs/iced_aw/blob/main/tests/README.md

A typical structure for an integration test file, including necessary imports, message enum, and test helpers.

```rust
//! Integration tests for the Widget
//! 
//! Brief description of what these tests cover.

#[macro_use] 
mod common;

use iced::{Element, Length};
use iced_aw::Widget;
use iced_test::{Error, Simulator};

#[derive(Clone, Debug)] 
enum Message {
    Action,
}

test_helpers!(Message);

// ============================================================================ 
// Basic Tests
// ============================================================================ 

#[test] 
fn widget_renders() {
    run_test(|| Widget::new().into());
}

#[test] 
fn widget_with_text() {
    run_test_and_find(|| Widget::new().with_label("Test").into(), "Test");
}

// ============================================================================ 
// Configuration Tests
// ============================================================================ 

#[test] 
fn widget_with_custom_width() {
    run_test(|| Widget::new().width(Length::Fill).into());
}

// ============================================================================ 
// Interaction Tests
// ============================================================================ 

#[test] 
fn widget_click_works() -> Result<(), Error> {
    let (mut app, _) = App::new(|| Widget::new().into());
    let mut ui = simulator(&app);

    ui.click("Target")?;

    let mut got_message = false;
    for message in ui.into_messages() {
        got_message = true;
        app.update(message);
    }

    assert!(got_message);
    Ok(())
}
```

--------------------------------

### Complete Date Picker Example

Source: https://github.com/iced-rs/iced_aw/blob/main/_autodocs/api-reference/date-picker.md

Demonstrates how to integrate the DatePicker widget into an Iced application. It includes setting up messages for showing/hiding the picker and handling date selection, along with the UI structure for a button that triggers the picker.

```rust
use iced::{Element, Length};
use iced::widget::{Button, Text, Row, Column};
use iced_aw::{DatePicker, core::date::Date};

#[derive(Debug, Clone)]
enum Message {
    ShowDatePicker,
    HideDatePicker,
    DateSelected(Date),
}

struct App {
    selected_date: Date,
    picker_open: bool,
}

fn view(&self) -> Element<Message> {
    let button = Button::new(
        Text::new(format!("Date: {}", self.selected_date))
    ).on_press(Message::ShowDatePicker);

    Column::new()
        .push(button)
        .width(Length::Fill)
        .into()
}

// With picker integration:
fn view_with_picker(&self) -> Element<Message> {
    DatePicker::new(
        self.picker_open,
        self.selected_date,
        Button::new(Text::new("Pick date")).on_press(Message::ShowDatePicker),
        Message::HideDatePicker,
        Message::DateSelected
    )
    .font_size(14)
    .into()
}

fn update(&mut self, message: Message) {
    match message {
        Message::ShowDatePicker => self.picker_open = true,
        Message::HideDatePicker => self.picker_open = false,
        Message::DateSelected(date) => {
            self.selected_date = date;
            self.picker_open = false;
        }
    }
}
```

--------------------------------

### Complete Card Widget Example

Source: https://github.com/iced-rs/iced_aw/blob/main/_autodocs/api-reference/card.md

Demonstrates the creation and configuration of a Card widget, including title, body content, a footer button, and various styling properties like close button size and padding.

```rust
use iced::{Element, Length};
use iced::widget::{Text, Column, Button};
use iced_aw::Card;

#[derive(Debug, Clone)]
enum Message {
    CloseCard,
}

fn view() -> Element<'static, Message> {
    Card::new(
        Text::new("Card Title"),
        Text::new("This is the card body content")
    )
    .foot(Button::new(Text::new("OK")).on_press(Message::CloseCard))
    .close_size(16.0)
    .on_close(Message::CloseCard)
    .width(Length::Fixed(300.0))
    .padding_head(15)
    .padding_body(15)
    .padding_foot(15)
    .into()
}
```

--------------------------------

### Basic Integration Test Setup for MyWidget

Source: https://github.com/iced-rs/iced_aw/blob/main/tests/README.md

Sets up a basic integration test for the MyWidget. It uses the test_helpers! macro for message type generation and defines tests for rendering and text display.

```rust
//! Integration tests for the MyWidget widget

#[macro_use] 
mod common;

use iced::Element;
use iced_aw::MyWidget;

#[derive(Clone, Debug)]
enum Message {
    MyAction,
}

// Generate test helpers for your Message type
test_helpers!(Message);

#[test]
fn my_widget_renders() {
    run_test(|| MyWidget::new().into());
}

#[test]
fn my_widget_shows_text() {
    run_test_and_find(|| MyWidget::new().into(), "Expected Text");
}
```

--------------------------------

### Date Manipulation and Formatting

Source: https://github.com/iced-rs/iced_aw/blob/main/_autodocs/api-reference/core-modules.md

Shows how to get today's date, create specific dates, navigate between months, and format dates for display. Requires `chrono` and `iced_aw::core::date`.

```rust
use iced_aw::core::date::{Date, pred_month, succ_month};
use chrono::NaiveDate;

// Get today
let today = Date::today();

// Create specific date
let christmas = Date::from_ymd(2024, 12, 25);

// Navigate months
let naive_date: NaiveDate = today.into();
let next_month = succ_month(naive_date);
let date_next_month: Date = next_month.into();

// Display formatted
println!("{}", today);  // 2024-06-12
```

--------------------------------

### Custom Styling with Predefined Colors

Source: https://github.com/iced-rs/iced_aw/blob/main/_autodocs/api-reference/core-modules.md

Provides an example of creating custom widget styles by leveraging predefined color constants from `iced_aw::style::colors` for backgrounds, text, and borders.

```rust
use iced_aw::style::colors;

fn custom_badge_style(theme: &Theme, status: Status) -> Style {
    Style {
        background: Background::Color(colors::INFO),
        text_color: colors::WHITE,
        border_color: Some(colors::DARK),
        ..Style::default()
    }
}
```

--------------------------------

### Tabs Constructor

Source: https://github.com/iced-rs/iced_aw/blob/main/_autodocs/configuration.md

Example of the basic constructor for the Tabs widget, which requires a callback function to handle tab selection.

```rust
Tabs::new(on_select: impl Fn(TabId) -> Message)
```

--------------------------------

### Create a Badge Widget

Source: https://github.com/iced-rs/iced_aw/blob/main/_autodocs/INDEX.md

Demonstrates how to create and configure a Badge widget with basic properties like padding and size. This snippet shows the typical setup for a widget that displays status information.

```rust
use iced::{Element, Length};
use iced::widget::Text;
use iced_aw::Badge;

let badge = Badge::new(Text::new("Status"))
    .padding(8)
    .width(Length::Shrink)
    .height(Length::Shrink)
    .into();
```

--------------------------------

### State Management for Overlay Widgets

Source: https://github.com/iced-rs/iced_aw/blob/main/_autodocs/INDEX.md

Provides an example of managing the state for widgets that use an overlay interface, such as `ColorPicker` or `DatePicker`. It shows how to declare and use a `State` struct to control the overlay's behavior.

```rust
use iced_aw::{ColorPicker, color_picker::State};

struct App {
    color: Color,
    picker_state: State,
}

// Use in overlay method
let picker = ColorPicker::new(...)
    .overlay(&mut self.picker_state, ...);
```

--------------------------------

### Initialize env_logger

Source: https://github.com/iced-rs/iced_aw/blob/main/src/widget/menu/README.md

Initialize the env_logger crate in your application's main function to process log messages. This example shows basic initialization.

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

--------------------------------

### Type Signature Example

Source: https://github.com/iced-rs/iced_aw/blob/main/_autodocs/README.md

Illustrates a typical Rust function signature with generic parameters, bounds, and a closure type. This format is used for API documentation to show full type details.

```rust
pub fn new<
    F,
>(
    value: &T,
    bounds: impl RangeBounds<T>,
    on_change: F,
) -> Self
where
    F: 'a + Fn(T) -> Message,
```

--------------------------------

### Customize Iced_aw Dependencies in Cargo.toml

Source: https://github.com/iced-rs/iced_aw/blob/main/_autodocs/configuration.md

Example of how to specify iced_aw as a dependency in Cargo.toml, enabling only specific features like 'badge', 'card', and 'tabs'.

```toml
[dependencies]
iced_aw = { version = "0.14.1", features = ["badge", "card", "tabs"] }
```

--------------------------------

### Calendar Grid Positioning to Day Calculation

Source: https://github.com/iced-rs/iced_aw/blob/main/_autodocs/api-reference/core-modules.md

Illustrates how to map grid positions (column, row) to specific days within a month, considering the starting day of the week. Useful for building calendar views.

```rust
use iced_aw::core::date::position_to_day;

// Create 7x6 calendar grid
for row in 0..6 {
    for col in 0..7 {
        let (day, location) = position_to_day(col, row, 2024, 6);
        // Render day with location info (previous/same/next month)
    }
}
```

--------------------------------

### Configure Alignment using Iced's Alignment Enum

Source: https://github.com/iced-rs/iced_aw/blob/main/_autodocs/configuration.md

Set alignment for widgets like badges using `iced::Alignment`. Options include Start, Center, and End for positioning.

```rust
use iced::Alignment;

Alignment::Start    // Left or top
Alignment::Center   // Centered
Alignment::End      // Right or bottom
```

--------------------------------

### Incorrect Test Names

Source: https://github.com/iced-rs/iced_aw/blob/main/tests/README.md

Examples of incorrectly named test functions that do not follow the suggested naming convention.

```rust
#[test]
fn renders_with_text() { /* ... */ }  // Missing widget prefix

#[test]
fn can_increment_number() { /* ... */ }  // Missing widget prefix

#[test]
fn displays_time() { /* ... */ }  // Missing widget prefix
```

--------------------------------

### Correct Test Names

Source: https://github.com/iced-rs/iced_aw/blob/main/tests/README.md

Examples of correctly named test functions that adhere to the suggested naming convention.

```rust
#[test]
fn badge_renders_with_text() { /* ... */ }

#[test]
fn number_input_increment_button_click_produces_message() { /* ... */ }

#[test]
fn time_picker_displays_12h_format_correctly() { /* ... */ }
```

--------------------------------

### Get Today's Date

Source: https://github.com/iced-rs/iced_aw/blob/main/_autodocs/api-reference/date-picker.md

Retrieves the current system date. This is useful for initializing the DatePicker with the current day.

```rust
let today = Date::today();
```

--------------------------------

### Create a DatePicker Instance

Source: https://github.com/iced-rs/iced_aw/blob/main/_autodocs/api-reference/date-picker.md

Demonstrates how to create a new DatePicker instance. It wraps a button that opens the picker and defines messages for cancellation and date selection.

```rust
use iced::widget::{Button, Text};
use iced_aw::{DatePicker, core::date::Date};

#[derive(Debug, Clone)]
enum Message {
    OpenDatePicker,
    CancelDatePicker,
    DateSelected(Date),
}

let picker = DatePicker::new(
    false,
    Date::today(),
    Button::new(Text::new("Pick date")).on_press(Message::OpenDatePicker),
    Message::CancelDatePicker,
    Message::DateSelected
);
```

--------------------------------

### Integrating DatePicker Widget

Source: https://github.com/iced-rs/iced_aw/blob/main/_autodocs/api-reference/core-modules.md

Shows how to instantiate and configure the `DatePicker` widget, including setting initial date, providing placeholder widgets, and defining message handlers.

```rust
use iced_aw::{DatePicker, core::date::Date};
use iced::widget::Button;

let current_date = Date::today();

let picker = DatePicker::new(
    false,
    current_date,
    Button::new(Text::new("Pick Date")),
    Message::Cancel,
    Message::DateSelected,
);
```

--------------------------------

### Using Predefined and Custom Colors

Source: https://github.com/iced-rs/iced_aw/blob/main/_autodocs/api-reference/core-modules.md

Demonstrates how to utilize predefined color constants from `iced_aw::style::colors` and create custom `iced::Color` instances.

```rust
use iced_aw::style::colors;
use iced::Color;

// Use predefined colors
let badge_color = colors::SUCCESS;
let error_color = colors::DANGER;

// Custom colors
let custom = Color::from_rgb(0.1, 0.2, 0.3);
```

--------------------------------

### Create a ContextMenu Widget

Source: https://github.com/iced-rs/iced_aw/blob/main/_autodocs/api-reference/other-widgets.md

Creates a ContextMenu that displays a menu when the underlay widget is right-clicked. It requires the underlay widget, the menu content, and a callback for context menu events.

```rust
use iced_aw::{ContextMenu, menu::{Menu, Item}};
use iced::widget::Button;

let menu = Menu::new(vec![
    Item::new(Button::new(Text::new("Copy"))),
    Item::new(Button::new(Text::new("Paste"))),
]);

let context = ContextMenu::new(
    Text::new("Right-click me"),
    menu,
    |_pos| Message::ContextMenuOpened
);
```

--------------------------------

### Tabs::set_active_tab

Source: https://github.com/iced-rs/iced_aw/blob/main/_autodocs/api-reference/tabs.md

Programmatically sets the currently active tab in the Tabs widget. This is useful for controlling the selected tab from outside the widget, for example, in response to application logic.

```APIDOC
## Tabs::set_active_tab

### Description
Sets which tab is currently active/selected. This method allows external control over the active tab.

### Signature
```rust
#[must_use]
pub fn set_active_tab(mut self, id: &TabId) -> Self
```

### Parameters
#### ID
- **id** (`&TabId`) - Required - ID of the tab to activate.

### Returns
- `Self` for method chaining.

### Example
```rust
tabs.set_active_tab(&TabId::Second)
```
```

--------------------------------

### menu_items! Macro Syntax

Source: https://github.com/iced-rs/iced_aw/blob/main/src/widget/menu/README.md

Demonstrates the basic syntax for the `menu_items!` macro, showing how to create menu items from widgets, widgets with submenus, or any expression returning an Item.

```rust
menu_items!(
    (widget),       // creates an Item::new(widget)
    (widget, menu), // creates an Item::with_menu(widget, menu)
    expression,     // any expression that returns an Item
    // ...
)
```

--------------------------------

### Conditionally Enable Widgets with Feature Flags

Source: https://github.com/iced-rs/iced_aw/blob/main/_autodocs/configuration.md

Use conditional compilation with feature flags to include or exclude widgets. This example shows how to create a badge widget only when the 'badge' feature is enabled.

```rust
#[cfg(feature = "badge")]
use iced_aw::Badge;

#[cfg(feature = "badge")]
fn create_badge() -> Element<'static, Message> {
    Badge::new(Text::new("Feature enabled")).into()
}

#[cfg(not(feature = "badge"))]
fn create_badge() -> Element<'static, Message> {
    Text::new("Badge widget not available").into()
}
```

--------------------------------

### Basic Menu Bar Creation with menu_bar! Macro

Source: https://github.com/iced-rs/iced_aw/blob/main/_autodocs/api-reference/menu.md

Use the `menu_bar!` macro to quickly construct a menu bar with top-level items and their associated submenus. This is a concise way to define the structure of your menu bar.

```rust
use iced_aw::menu_bar;

let bar = menu_bar!(
    (Button::new(Text::new("File")), menu!(...))
    (Button::new(Text::new("Edit")), menu!(...))
);
```

--------------------------------

### Date Type and Methods

Source: https://github.com/iced-rs/iced_aw/blob/main/_autodocs/api-reference/date-picker.md

Represents a date with year, month, and day. Provides static methods to create Date instances, including getting the current date and constructing from specific values.

```APIDOC
## `Date` Struct

### Description
Represents a date with year, month, and day components.

### Fields
*   `year` (i32)
*   `month` (u32): 1-12
*   `day` (u32): 1-31

### `today` Method

#### Description
Gets the current date from the system clock.

#### Signature
```rust
pub fn today() -> Self
```

#### Returns
`Date` representing today's date

#### Example
```rust
let today = Date::today();
```

### `from_ymd` Method

#### Description
Creates a date from year, month, and day values.

#### Signature
```rust
pub const fn from_ymd(year: i32, month: u32, day: u32) -> Self
```

#### Parameters
*   `year` (i32): Year (e.g., 2024).
*   `month` (u32): Month (1-12).
*   `day` (u32): Day (1-31).

#### Returns
`Date` instance

#### Panics
If values create an invalid date.

#### Example
```rust
let date = Date::from_ymd(2024, 6, 15);
```
```

--------------------------------

### Create a Quad Widget

Source: https://github.com/iced-rs/iced_aw/blob/main/_autodocs/api-reference/other-widgets.md

Use Quad::new() to create a Quad for drawing rectangles and shapes. Configure its size, color, border, and shadow using available methods.

```rust
use iced_aw::Quad;
use iced_core::Color;

let quad = Quad::new()
    .size(100.0, 10.0)
    .color(Color::BLACK);
```

--------------------------------

### Build a Menu using the menu! macro

Source: https://github.com/iced-rs/iced_aw/blob/main/_autodocs/api-reference/menu.md

A macro for constructing menus with a more concise syntax, reducing boilerplate code for menu creation.

```rust
use iced_aw::menu;

let m = menu!(
    (Button::new(Text::new("File")))
    (Button::new(Text::new("Edit")))
    (Button::new(Text::new("View")))
);
```

--------------------------------

### Documentation Directory Structure

Source: https://github.com/iced-rs/iced_aw/blob/main/_autodocs/MANIFEST.md

Illustrates the hierarchical organization of documentation files within the iced_aw project, including the README, INDEX, API reference, and supporting files.

```text
/output/
├── README.md (Overview & usage guide)
├── INDEX.md (Navigation & feature matrix)
├── types.md (Type definitions)
├── configuration.md (Setup & defaults)
└── api-reference/
    ├── badge.md
    ├── card.md
    ├── color-picker.md
    ├── core-modules.md
    ├── date-picker.md
    ├── menu.md
    ├── number-input.md
    ├── other-widgets.md
    ├── sidebar.md
    ├── tabs.md
    └── (Additional supporting files)

```

--------------------------------

### Badge Constructor

Source: https://github.com/iced-rs/iced_aw/blob/main/_autodocs/api-reference/badge.md

Creates a new Badge with the given content. This is the primary way to initialize a Badge widget.

```rust
use iced::widget::Text;
use iced_aw::Badge;

let badge = Badge::new(Text::new("New"));
```

--------------------------------

### ColorPicker State Initialization

Source: https://github.com/iced-rs/iced_aw/blob/main/_autodocs/api-reference/color-picker.md

Illustrates how to create and manage the internal state for the ColorPicker widget, which is necessary for its overlay functionality.

```rust
use iced_aw::color_picker::State;

let mut picker_state = State::default();
// Pass picker_state to picker.overlay(&mut picker_state, ...)
```

--------------------------------

### DatePicker Constructor

Source: https://github.com/iced-rs/iced_aw/blob/main/_autodocs/configuration.md

Demonstrates the constructor for the DatePicker widget, requiring visibility control, the initial date, an underlay, a cancel message, and a submit handler.

```rust
DatePicker::new(
    show_picker: bool,
    date: impl Into<Date>,
    underlay: Element,
    on_cancel: Message,
    on_submit: impl Fn(Date) -> Message
)
```

--------------------------------

### Create a new Sidebar

Source: https://github.com/iced-rs/iced_aw/blob/main/_autodocs/api-reference/sidebar.md

Instantiate a Sidebar widget with the main content element. The sidebar will be empty by default.

```rust
use iced::widget::Text;
use iced_aw::Sidebar;

let sidebar = Sidebar::new(Text::new("Main content"));
```

--------------------------------

### Run Application with Logging

Source: https://github.com/iced-rs/iced_aw/blob/main/src/widget/menu/README.md

Execute your application with the RUST_LOG environment variable set to enable debug logging for the menu module. This command runs the application and outputs logs to the console.

```bash
RUST_LOG=menu=debug cargo run
```

--------------------------------

### Build a list of menu items using the menu_items! macro

Source: https://github.com/iced-rs/iced_aw/blob/main/_autodocs/api-reference/menu.md

A macro for creating a vector of menu items with simplified syntax. Useful for populating menus or menu bars.

```rust
use iced_aw::menu_items;

let items = menu_items!(
    (Button::new(Text::new("Item 1")))
    (Button::new(Text::new("Item 2")))
);
```

--------------------------------

### Create a SelectionList Widget

Source: https://github.com/iced-rs/iced_aw/blob/main/_autodocs/api-reference/other-widgets.md

Creates a SelectionList for displaying and selecting items. It accepts a collection of items (ID and Element pairs), an optional selected item ID, and a callback for selection events.

```rust
use iced_aw::SelectionList;
use iced::widget::Text;

let items = vec![
    (1, Text::new("Item 1").into()),
    (2, Text::new("Item 2").into()),
    (3, Text::new("Item 3").into()),
];

let list = SelectionList::new(items, Some(1), Message::ItemSelected);
```

--------------------------------

### Enable Default Features in Cargo.toml

Source: https://github.com/iced-rs/iced_aw/blob/main/_autodocs/configuration.md

This TOML snippet shows how to set the default features in your Cargo.toml file to include all available widgets from the iced_aw crate.

```toml
[features]
default = ["full"]
```

--------------------------------

### Menu Macros

Source: https://github.com/iced-rs/iced_aw/blob/main/_autodocs/api-reference/menu.md

Helper macros for simplifying the creation of menus and item lists.

```APIDOC
## Helper Macros

### `menu!`

Macro for building menus with minimal syntax:

```rust
use iced_aw::menu;

let m = menu!(
    (Button::new(Text::new("File")))
    (Button::new(Text::new("Edit")))
    (Button::new(Text::new("View")))
);
```

### `menu_items!`

Macro for building item lists:

```rust
use iced_aw::menu_items;

let items = menu_items!(
    (Button::new(Text::new("Item 1")))
    (Button::new(Text::new("Item 2")))
);
```
```

--------------------------------

### Create a DropDown Widget

Source: https://github.com/iced-rs/iced_aw/blob/main/_autodocs/api-reference/other-widgets.md

Creates a DropDown widget for selecting an option from a list. It takes a vector of options, an optional initial selection index, and a callback for selection events.

```rust
use iced_aw::DropDown;

let options = vec!["Option 1", "Option 2", "Option 3"];
let dropdown = DropDown::new(options, Some(0), Message::OptionSelected);
```

--------------------------------

### Create Tabs Widget with Initial Tabs

Source: https://github.com/iced-rs/iced_aw/blob/main/_autodocs/api-reference/tabs.md

Creates a new Tabs widget pre-populated with a collection of tabs. This is useful for initializing the widget with a predefined set of content. Each tab requires a unique ID, a label, and its associated content element.

```rust
pub fn new_with_tabs<F>(
    tabs: impl IntoIterator<Item = (TabId, TabLabel, Element<'a, Message, Theme, Renderer>)>,
    on_select: F,
) -> Self
where
    F: 'static + Fn(TabId) -> Message,

```

```rust
let tabs = Tabs::new_with_tabs(
    vec![
        (TabId::First, TabLabel::Text("Home".into()), Text::new("Home content").into()),
        (TabId::Second, TabLabel::Text("Settings".into()), Text::new("Settings content").into()),
    ],
    Message::TabSelected
);

```

--------------------------------

### Create a SlideBar Widget

Source: https://github.com/iced-rs/iced_aw/blob/main/_autodocs/api-reference/other-widgets.md

Creates a SlideBar for numeric range selection. It requires an initial value, a range (min..=max), and a callback function to handle value changes.

```rust
use iced_aw::SlideBar;

let slider = SlideBar::new(50, 0..=100, Message::ValueChanged);
```

--------------------------------

### NumberInput Constructor

Source: https://github.com/iced-rs/iced_aw/blob/main/_autodocs/configuration.md

Illustrates the basic constructor for the NumberInput widget, which requires a value, bounds, and a change handler.

```rust
NumberInput::new(
    value: &T,
    bounds: impl RangeBounds<T>,
    on_change: impl Fn(T) -> Message
)
```

--------------------------------

### Create a Wrap Layout Widget

Source: https://github.com/iced-rs/iced_aw/blob/main/_autodocs/api-reference/other-widgets.md

Creates a Wrap layout widget that arranges its children. Children are wrapped to the next line if they exceed the available horizontal space. Customize spacing and padding.

```rust
use iced_aw::Wrap;
use iced::widget::Button;

let wrap = Wrap::new()
    .push(Button::new(Text::new("1")))
    .push(Button::new(Text::new("2")))
    .push(Button::new(Text::new("3")))
    .spacing(10);
```

--------------------------------

### ColorPicker Constructor

Source: https://github.com/iced-rs/iced_aw/blob/main/_autodocs/api-reference/color-picker.md

Creates a new ColorPicker instance. It wraps an underlay element and manages an overlay for color selection.

```APIDOC
## `ColorPicker::new`

### Description
Creates a new `ColorPicker` wrapping around the given underlay element.

### Signature
```rust
pub fn new<U, F>(
    show_picker: bool,
    color: Color,
    underlay: U,
    on_cancel: Message,
    on_submit: F,
) -> Self
where
    U: Into<Element<'a, Message, Theme, Renderer>>,
    F: 'static + Fn(Color) -> Message,
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters Table
| Parameter | Type | Description |
|-----------|------|-------------|
| show_picker | `bool` | Whether to show the overlay initially |
| color | `Color` | Initial color to display |
| underlay | `U: Into<Element>` | The element displayed when picker is hidden (e.g., Button) |
| on_cancel | `Message` | Message to send when cancel button is pressed |
| on_submit | `F: Fn(Color) -> Message` | Function called when color is confirmed |

### Returns
`ColorPicker` instance

### Example
```rust
use iced::{Color, Element};
use iced::widget::{Button, Text};
use iced_aw::ColorPicker;

#[derive(Debug, Clone)]
enum Message {
    OpenColorPicker,
    CancelColorPicker,
    ColorSelected(Color),
}

let picker = ColorPicker::new(
    false,
    Color::WHITE,
    Button::new(Text::new("Pick color")).on_press(Message::OpenColorPicker),
    Message::CancelColorPicker,
    Message::ColorSelected
);
```
```

--------------------------------

### Create a Basic Card

Source: https://github.com/iced-rs/iced_aw/blob/main/_autodocs/api-reference/card.md

Creates a new Card with a title and body. This is the fundamental way to instantiate a Card widget.

```rust
use iced::widget::Text;
use iced_aw::Card;

let card = Card::new(
    Text::new("Title"),
    Text::new("Card content")
);
```

--------------------------------

### menu_items! Macro with Helper Function

Source: https://github.com/iced-rs/iced_aw/blob/main/src/widget/menu/README.md

Illustrates how to use a helper function or closure with the `menu_items!` macro to create custom menu items with additional settings.

```rust
let hold_item = |widget| Item::new(widget).close_on_click(false);

menu_items!(
    hold_item(widget), 
    // this is treated as an expression 
    // and creates an Item::new(widget).close_on_click(false)
    // ...
)
```

--------------------------------

### Badge Constructor

Source: https://github.com/iced-rs/iced_aw/blob/main/_autodocs/api-reference/badge.md

Creates a new Badge widget with the provided content. Default styling and dimensions are applied, which can be further customized using other methods.

```APIDOC
## Badge::new

### Description
Creates a new `Badge` with the given content element.

### Signature
```rust
pub fn new<T>(content: T) -> Self
where
    T: Into<Element<'a, Message, Theme, Renderer>>,
```

### Parameters
#### Path Parameters
- **content** (T: Into<Element>): The content element to display in the badge.

### Returns
`Badge` instance with default styling.

### Default Values
- padding: 7 units
- width: `Length::Shrink`
- height: `Length::Shrink`
- horizontal_alignment: `Alignment::Center`
- vertical_alignment: `Alignment::Center`
- status: `None`

### Example
```rust
use iced::widget::Text;
use iced_aw::Badge;

let badge = Badge::new(Text::new("New"));
```
```

--------------------------------

### Combine Sidebar with other Widgets

Source: https://github.com/iced-rs/iced_aw/blob/main/_autodocs/api-reference/other-widgets.md

Demonstrates how to integrate the Sidebar widget with other elements like Buttons, Rows, and Containers to create complex layouts.

```rust
use iced::{Element, Length};
use iced::widget::{Column, Row, Container, Button, Text};
use iced_aw::Sidebar;

fn layout() -> Element<'static, Message> {
    let sidebar_content = Column::new()
        .push(Button::new(...))
        .spacing(10)
        .padding(10);

    let main_content = Container::new(
        Text::new("Main")
    )
    .width(Length::Fill)
    .height(Length::Fill);

    Sidebar::new(main_content)
        .push(sidebar_content)
        .into()
}
```

--------------------------------

### Common Iced AW Imports

Source: https://github.com/iced-rs/iced_aw/blob/main/_autodocs/types.md

Lists common import paths for using Iced AW widgets and utilities, including Date, Style, and TabBar components.

```rust
use iced_aw::core::date::Date;
use iced_aw::style::{Status, StyleFn};
use iced_aw::widget::tab_bar::{TabLabel, Position};
use iced_aw::tabs::TabBarPosition;
```

--------------------------------

### DatePicker Constructor

Source: https://github.com/iced-rs/iced_aw/blob/main/_autodocs/api-reference/date-picker.md

Creates a new DatePicker instance. It wraps an underlay element and displays a calendar picker overlay when activated. You can configure initial visibility, date, cancel/submit messages, and styling.

```APIDOC
## `new` Constructor

### Description
Creates a new `DatePicker` wrapping around the given underlay element.

### Signature
```rust
pub fn new<U, F>(
    show_picker: bool,
    date: impl Into<Date>,
    underlay: U,
    on_cancel: Message,
    on_submit: F,
) -> Self
where
    U: Into<Element<'a, Message, Theme, Renderer>>,
    F: 'static + Fn(Date) -> Message,
```

### Parameters

*   `show_picker` (bool): Whether to display the overlay initially.
*   `date` (impl Into<Date>): Initial date to display.
*   `underlay` (U: Into<Element>): Element displayed when picker is hidden (typically a button).
*   `on_cancel` (Message): Message to send when cancel button is pressed.
*   `on_submit` (F: Fn(Date) -> Message): Function called when date is confirmed.

### Returns
`DatePicker` instance

### Example
```rust
use iced::widget::{Button, Text};
use iced_aw::{DatePicker, core::date::Date};

#[derive(Debug, Clone)]
enum Message {
    OpenDatePicker,
    CancelDatePicker,
    DateSelected(Date),
}

let picker = DatePicker::new(
    false,
    Date::today(),
    Button::new(Text::new("Pick date")).on_press(Message::OpenDatePicker),
    Message::CancelDatePicker,
    Message::DateSelected
);
```
```

--------------------------------

### Create a TypedInput Widget

Source: https://github.com/iced-rs/iced_aw/blob/main/_autodocs/api-reference/other-widgets.md

Instantiate TypedInput with a placeholder, current value, and a callback for when the value changes. The value type must implement Display and FromStr.

```rust
use iced_aw::TypedInput;

let input = TypedInput::new("Enter number", &42, Message::NumberChanged);
```

--------------------------------

### Create a Spinner Widget

Source: https://github.com/iced-rs/iced_aw/blob/main/_autodocs/api-reference/other-widgets.md

Creates a new Spinner widget with default animation. Customize its appearance using methods like .radius(), .width(), and .speed().

```rust
use iced_aw::Spinner;

let spinner = Spinner::new()
    .radius(25.0)
    .width(3.0);
```

--------------------------------

### Helper Function for Conditional Element Creation

Source: https://github.com/iced-rs/iced_aw/blob/main/_autodocs/api-reference/core-modules.md

Demonstrates using helper functions for creating elements conditionally. Requires importing helpers from `iced_aw::helpers`.

```rust
// Create elements more ergonomically
use iced_aw::helpers::*

// Conditional element creation
let content = if show_details {
    element(details_widget)
} else {
    element(summary_widget)
};
```

--------------------------------

### Create a new Menu

Source: https://github.com/iced-rs/iced_aw/blob/main/_autodocs/api-reference/menu.md

Creates a new Menu with a vector of Item elements. Default values are applied for width, height, padding, spacing, and offset.

```rust
use iced_aw::menu::Menu;

let menu = Menu::new(vec![
    Item::new(Button::new(Text::new("File"))),
    Item::new(Button::new(Text::new("Edit"))),
]);
```

--------------------------------

### Conditional Widget Compilation with Feature Gates

Source: https://github.com/iced-rs/iced_aw/blob/main/_autodocs/INDEX.md

Illustrates how to use feature gates (`cfg`) to conditionally compile code, specifically for including or excluding widgets like `Badge` based on build features. This allows for modularity and reduced build sizes.

```rust
#[cfg(feature = "badge")]
use iced_aw::Badge;

#[cfg(feature = "badge")]
fn create_badge() { ... }

#[cfg(not(feature = "badge"))]
fn create_badge() { 
    // Fallback implementation
}
```

--------------------------------

### Add iced_aw Dependency

Source: https://github.com/iced-rs/iced_aw/blob/main/README.md

Include `iced_aw` as a dependency in your `Cargo.toml` file. Enable the `full` feature to include all widgets, or specify individual features as needed.

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

--------------------------------

### Create a LabeledFrame Widget

Source: https://github.com/iced-rs/iced_aw/blob/main/_autodocs/api-reference/other-widgets.md

Use LabeledFrame::new() to create a frame with a title and content. Customize padding, spacing, width, height, and label font size.

```rust
use iced_aw::LabeledFrame;
use iced::widget::{Column, Text};

let frame = LabeledFrame::new(
    "Settings",
    Column::new().push(Text::new("Setting 1"))
)
.padding(10);
```

--------------------------------

### Create SidebarWithContent

Source: https://github.com/iced-rs/iced_aw/blob/main/_autodocs/api-reference/sidebar.md

Creates a new SidebarWithContent with separate sidebar and content elements. Use this to build layouts with a persistent sidebar navigation.

```rust
pub fn new(
    sidebar: impl Into<Element<'a, Message, Theme, Renderer>>,
    content: impl Into<Element<'a, Message, Theme, Renderer>>,
) -> Self
```

--------------------------------

### Menu Close-on-Click Configuration

Source: https://github.com/iced-rs/iced_aw/blob/main/src/widget/menu/README.md

Defines the data structures for configuring close-on-click behavior in menus, showing inheritance from global settings to menu items.

```rust
GlobalParameters {
    close_on_item_click: bool,
    close_on_background_click: bool,
    // ...
}

MenuBar {
    close_on_item_click: Option<bool>,
    close_on_background_click: Option<bool>,
    global_parameters: GlobalParameters,
    // ...
}

Menu {
    close_on_item_click: Option<bool>,
    close_on_background_click: Option<bool>,
    // ...
}

Item {
    close_on_click: Option<bool>,
    // ...
}
```

--------------------------------

### Cargo Configuration for Iced Widgets

Source: https://github.com/iced-rs/iced_aw/blob/main/_autodocs/README.md

Enable specific iced_aw widgets by listing them in the features section of your Cargo.toml file. This allows for a more optimized build by only including necessary components.

```toml
[dependencies]
iced_aw = { version = "0.14.1", features = [
    "badge",
    "card",
    "tabs",
    "date_picker",
] }
```

--------------------------------

### Card Constructor

Source: https://github.com/iced-rs/iced_aw/blob/main/_autodocs/configuration.md

Illustrates the constructor for the Card widget, which requires a head and a body element.

```rust
Card::new(
    head: impl Into<Element>,
    body: impl Into<Element>
)
```

--------------------------------

### ColorPicker on_color_change Method

Source: https://github.com/iced-rs/iced_aw/blob/main/_autodocs/api-reference/color-picker.md

Shows how to attach a callback function to the ColorPicker that is invoked whenever the color changes during selection.

```rust
picker.on_color_change(Message::ColorChanging)
```

--------------------------------

### Configuring Menus to Close Only on Click

Source: https://github.com/iced-rs/iced_aw/blob/main/src/widget/menu/README.md

Sets up a menu bar to close only when an item is clicked or the background is clicked, by extending safe bounds to infinity. This ensures menus do not close automatically when the cursor leaves their bounds.

```rust
let mb = menu_bar!(
    ...
)
.close_on_item_click_global(true)
.close_on_background_click_global(true)
.safe_bounds_margin(f32::MAX);
```

--------------------------------

### Create Date from Year, Month, Day

Source: https://github.com/iced-rs/iced_aw/blob/main/_autodocs/api-reference/date-picker.md

Constructs a Date object from specific year, month, and day values. Panics if the provided values do not form a valid date.

```rust
let date = Date::from_ymd(2024, 6, 15);
```

--------------------------------

### Include iced_aw Features in Cargo.toml

Source: https://github.com/iced-rs/iced_aw/blob/main/_autodocs/INDEX.md

Specify the desired features for the iced_aw crate in your Cargo.toml file to include only the necessary widgets.

```toml
iced_aw = { version = "0.14.1", features = ["badge", "card", "tabs"] }
```