Module zng::toggle

source ·
Expand description

Toggle button widget and styles for check box, combo box, radio button and switch button.

The Toggle! widget has three states, Some(true), Some(false) and None. How the widget toggles between this values is defined by what property is used to bind the state.

The checked property binds to a bool variable and toggles between true and false only. The example below makes use of the property.

use zng::prelude::*;

let checked = var(false);
Toggle! {
    child = Text!(checked.map(|b| formatx!("checked = {b}")));
    checked;
}

The checked_opt and tristate properties can be used to toggle between Some(true) and Some(false) and accept the None value, or with tristate enabled to include None in the toggle cycle. Note that even if tristate is not enabled the variable can be set to None from another source and the widget will display the None appearance.

use zng::prelude::*;

let checked = var(Some(false));
Toggle! {
    child = Text!(checked.map(|b| formatx!("checked = {b:?}")));
    tristate = true;
    checked_opt = checked;
}

The selector and value properties can be used to have the toggle insert and remove a value from a contextual selection of values. The example below declares a stack with 10 toggle buttons each representing a value, the stack is also setup as a selector context for these toggle buttons, when each toggle button is clicked it replaces the selected value.

Note that the toggle does not know what the selection actually is, the Selector type abstracts over multiple selection kinds, including custom implementations of SelectorImpl.

use zng::prelude::*;

let selected_item = var(1_i32);
Stack! {
    toggle::selector = toggle::Selector::single(selected_item.clone());

    spacing = 5;
    children = (1..=10_i32).map(|i| {
        Toggle! {
            child = Text!("Item {i}");
            value::<i32> = i;
        }
        .boxed()
    }).collect::<Vec<_>>();
}

Regardless of how the checked state of a toggle is defined the IS_CHECKED_VAR variable and is_checked property can be used to track the checked state of the widget. The example below defines a toggle that changes background color to green when it is in the Some(true) state.

Toggle! {
    checked = var(false);
    // checked_opt = var(Some(false));
    // value<i32> = 42;

    widget::background_color = colors::RED;
    when *#is_checked {
        widget::background_color = colors::GREEN;
    }
}

§Styles

Toggle is a versatile widget, it can be styled to represent check boxes, switches, radio buttons and combo boxes.

§Check & Switch

The CheckStyle! changes the toggle into a check box. The SwitchStyle! changes the toggle into an on/off switch.

use zng::prelude::*;

Toggle! {
    child = Text!(toggle::IS_CHECKED_VAR.map(|&s| match s {
        Some(true) => Txt::from("checked text"),
        Some(false) => Txt::from("unchecked text"),
        None => Txt::from(""),
    }));
    checked = var(false);
    style_fn = toggle::SwitchStyle!();
}

The example above declares a toggle switch that changes the text depending on the state.

§Radio

The RadioStyle! can be used in value toggle areas. The example below declares a stack that is a selector context and sets the toggle style for all toggle buttons inside.

let selected_item = var(1_i32);
Stack! {
    toggle::style_fn = style_fn!(|_| toggle::RadioStyle!());
    toggle::selector = toggle::Selector::single(selected_item.clone());
    // ..
}

§Combo

The ComboStyle! together with the checked_popup property can be used to declare a combo box, that is a toggle for a drop down that contains another toggle selector context that selects a value.

Note that the checked_popup setups the checked state, you cannot set one of the other checked properties in the same widget.

The example below declares a combo box with a TextInput! content, users can type a custom option or open the popup and pick an option. Note that the ComboStyle! also restyles Toggle! inside the popup to look like a menu item.

use zng::prelude::*;

let txt = var(Txt::from_static("Combo"));
let options = ["Combo", "Congo", "Pombo"];
Toggle! {
    child = TextInput! {
        txt = txt.clone();
        gesture::on_click = hn!(|a: &gesture::ClickArgs| a.propagation().stop());
    };
    style_fn = toggle::ComboStyle!();

    checked_popup = wgt_fn!(|_| popup::Popup! {
        id = "popup";
        child = Stack! {
            toggle::selector = toggle::Selector::single(txt.clone());
            direction = StackDirection::top_to_bottom();
            children = options.into_iter().map(|o| Toggle! {
                child = Text!(o);
                value::<Txt> = o;
            })
            .collect::<UiVec>();
        };
    })
}

§Full API

See zng_wgt_toggle for the full widget API.

Modules§

  • cmd
    Toggle commands.

Structs§

Enums§

Statics§

Traits§

Functions§

  • check_spacing
    P Spacing between the checkmark and the content.
  • combo_spacing
    P Spacing between the arrow symbol and the content.
  • deselect_on_deinit
    P If value is deselected when the widget that has the value is deinited and the value was selected.
  • deselect_on_new
    P If value deselects the previously selected value when the variable changes.
  • is_checked
    P If the toggle is checked from any of the three primary properties.
  • radio_spacing
    P Spacing between the radio and the content.
  • scroll_on_select
    P If the scrolls into view when the value selected.
  • select_on_init
    P If value is selected when the widget that has the value is inited.
  • select_on_new
    P If value selects the new value when the variable changes and the previous value was selected.
  • selector
    P Sets the contextual selector that all inner widgets will target from the value property.
  • style_fn
    P Extends or replaces the widget style.
  • switch_spacing
    P Spacing between the switch and the content.
  • tristate
    P Enables None as an input value.