Tutorial Scheduler Programmatic Widgets

Creating widgets programmatically

The static parts of your UI are created from the .ez files. In some cases however you need to create widgets dynamically. Maybe you are retrieving records from a database and need to display them. They will be retrieved at runtime and so cannot be known in advance (and even if they could, it would be too much work to put them all in the .ez files). In cases like this you could create widgets from code.

Creating a widget from code is a 3-step process:

1. Call 'prepare_create_widget' to get the new widget object and widget state(s);
2. Optionally modify the widget states;
3. Call 'create_widget' to create the widgets.

Once you've called the scheduler.create_widget method (example below), the widgets will be added to the UI on the next frame.

You can spawn any kind of layout or widget from code, including templates. In fact, creating widgets from templates is usually the best way to do it. Let's use the SQL record example we used above: we will create a layout template that can display an SQL record. Then we'll iterate over SQL records from code and create widgets for them. We'll also create a UI that can display multiple sql record widgets. First the .ez file:

- Layout:
    mode: box
    orientation: vertical
    border: true
    - Label:
        text: Retrieved SQL records:
        auto_scale: true, true
        halign: center
        padding_bottom: 1
    // This is the layout we will spawn widgets inside of
    - Layout:
        id: sql_records_layout
        mode: box
        orientation: vertical
        scroll_y: true

// This is the template we will spawn from code
- <SqlRecord@Layout>:
    mode: box
    orientation: horizontal
    auto_scale_height: true
    - Label:
        id: record_id
        auto_scale_height: true
        size_hint_x: 1
    - Label:
        id: record_name
        auto_scale_height: true
        size_hint_x: 1
    - Label:
        id: record_date
        auto_scale_height: true
        size_hint_x: 1

We now have a main UI that can hold our records. We also have a Layout template that can be spawned to display a record. Let's now go to the code:

fn main() {
    use ez_term::*;
    use std::collections::HashMap;

    let (root_widget, mut state_tree, mut scheduler) = load_ui();

    // Let's create some mock SQL records to spawn widgets from
    let mut sql_records = Vec::new();
    for x in 1..=100 {
        let mut sql_record = HashMap::new();
        sql_record.insert("id", format!("{}", x));
        sql_record.insert("name", format!("Record {}", x));
        sql_record.insert("date", format!("{}-{}-2022", (x / 31) + 1, x % 31 + 1));
        sql_records.push(sql_record);
    }

    // Now we'll iterate over the records and spawn a template for each one
    let template_name = "SqlRecord";
    let parent_id = "sql_records_layout";
    for (i, sql_record) in sql_records.iter().enumerate() {

        let new_id = format!("record_{}", i);

        let (new_widget, mut new_states) =
                scheduler.prepare_create_widget(template_name, &new_id, parent_id, &mut state_tree);

        // We will modify the widget state of each label to reflect the SQL record
        new_states.get_mut("record_id").as_label_mut().set_text(sql_record.get("id").unwrap().to_string());
        new_states.get_mut("record_name").as_label_mut().set_text(sql_record.get("name").unwrap().to_string());
        new_states.get_mut("record_date").as_label_mut().set_text(sql_record.get("date").unwrap().to_string());

        scheduler.create_widget(new_widget, new_states, &mut state_tree);

    }
    run(root_widget, state_tree, scheduler);
}

We saw the process in action above: get the new widget object and states, alter the states, then create the widget. When calling 'prepare_create_widget' we need a template or widget name (like 'Layout', 'Label' or 'MyTemplate'), an ID (the new widget will receive this ID) and a parent ID (the new widget will be added to this parent layout). In return we get the new widget object and a state tree which contains the state(s) of the new widget. This gives you a change to programmatically alter the states before the widget is created (in our example, loading the SQL results into the labels). We then use the widget object and widget states to actually create the widget.

Removing widgets programmatically

It's also possible to remove widgets from code. Simply use the 'remove_widget' method of the scheduler and the path or ID of the widget you wish to remove. If you use an ID, it must be globally unique:

scheduler.remove_widget("/root/layout/widget");

The widget will be removed on the next frame after you call remove_widget. If you remove a layout, all children will also be removed. You cannot remove the root layout.

Continue

The general tutorial continues with: Updating widgets.