ComboBox

A combobox is a drop down list control that allows you to select a variant from a list os strings.

It can be created using ComboBox::new(...) or the combobox! macro.

let c1 = ComboBox::new(Layout::new("..."),combobox::Flags::None);
let c2 = ComboBox::new(Layout::new("..."),combobox::Flags::ShowDescription);
let c3 = combobox!("x:1,y:1,w:20,items=['Red','Greem','Blue']");
let c3 = combobox!("x:1,y:1,w:20,items=['Red','Greem','Blue'],index:2");

A combobox supports all common parameters (as they are described in Instantiate via Macros section). Besides them, the following named parameters are also accepted:

A combobox supports the following initialization flags:

• combobox::Flags::ShowDescription or ShowDescription (for macro initialization) - thils will allow a combobox show the description of each item (if exists) when expanded

Events

To intercept events from a combobox, the following trait has to be implemented to the Window that processes the event loop:

pub trait ComboBoxEvents {
    fn on_selection_changed(&mut self, handle: Handle<ComboBox>) -> EventProcessStatus {
        EventProcessStatus::Ignored
    }
}

Methods

Besides the Common methods for all Controls a combobox also has the following aditional methods:

Remarks: Methods selected_item and seletec_item_mut return an Option over the type combobox::Item that is defined as follows:

pub struct Item { ...}

impl Item {
    pub fn new(value: &str, description: &str) -> Self {...}
    pub fn from_string(value: String, description: String) -> Self {...}
    pub fn set_value(&mut self, value: &str) {...}
    pub fn value(&self) -> &str {...}
    pub fn set_description(&mut self, description: &str) {...}
    pub fn description(&self) -> &str {...}
}

Key association

The following keys are processed by a ComboBox control if it has focus:

Besides this using any one of the following keys: A to Z and/or 0 to 9 will move the selection to the fist variant that starts with that letter (case is ignored). The search starts from the next variant after the current one. This means that if you have multiple variants that starts with letter G, pressing G multiple times will efectively switch between all of the variants that starts with letter G.

When the combobox is expanded the following additional keys can be used:

Example

The following example creates a Window with a ComboBox that was populated with various animals and their speed. Selecting one animal from the list changes the title of the window to the name of that animal.

use appcui::prelude::*;

#[Window(events = ComboBoxEvents)]
struct MyWin {}
impl MyWin {
    fn new() -> Self {
        let mut w = Self {
            base: window!("x:1,y:1,w:34,h:6,caption:Win"),
        };
        w.add(label!("'Select animal',x:1,y:1,w:30"));
        let mut c = ComboBox::new(Layout::new("x:1,y:2,w:30"), combobox::Flags::ShowDescription);
        // data from https://en.wikipedia.org/wiki/Fastest_animals
        c.add_item(combobox::Item::new("Cheetah","(120 km/h)"));
        c.add_item(combobox::Item::new("Swordfish","(97 km/h)"));
        c.add_item(combobox::Item::new("Iguana","(35 km/h)"));
        c.add_item(combobox::Item::new("Gazelle","(81 km/h)"));
        c.add_item(combobox::Item::new("Lion","(80 km/h)"));
        c.add_item(combobox::Item::new("Dog","(60 km/h)"));
        c.add_item(combobox::Item::new("Zebra","(56 km/h)"));
        w.add(c);
        w
    }
}
impl ComboBoxEvents for MyWin {
    fn on_selection_changed(&mut self, handle: Handle<ComboBox>) -> EventProcessStatus {
        let title = if let Some(cb) = self.control_mut(handle) {
            if let Some(item) = cb.selected_item() {
                item.value().to_string()
            } else {
                String::from("[None]")
            }
        } else {
            String::from("?")
        };
        self.set_title(&title);
        EventProcessStatus::Processed
    }
}


fn main() -> Result<(), appcui::system::Error> {
    let mut a = App::new().build()?;
    a.add_window(MyWin::new());
    a.run();
    Ok(())
}