Tutorial Scheduler Modals

A modal is a layout that is shown in front of the main UI; one of its main use cases is creating popups. A modal is always created from a Layout template created in an .ez file. In other words, you first define what the modal looks like in the .ez file, and then you spawn it from code.

You can spawn a popup anytime you have access to the scheduler (i.e. when initializing the UI, from a callback, or from a scheduled task). Only one modal can exist at any time; if a modal is opened when another one already exists, the existing one is dismissed first. The ID of a modal will always be 'modal'. The full path of a modal will always be '/root/modal'. Any widgets defined inside of the template layout will have their own IDs, e.g. '/root/modal/my_popup_label'.

The modal is spawned in the root layout, so size hints and position hints will size and position the modal relative to the root layout. Modals can be dismissed from the scheduler. If you want a button in your modal that dismisses it, you need to bind a callback to the button in the modal that calls the dismiss_modal method of the scheduler. Modals can be dragged across the screen by the user (as long as they click on an empty part of the modal); if you want to disable this behavior set 'can_drag' to false in the layout template used to spawn the modal. Lastly, when a modal is open only widgets in the modal can be selected or clicked; events do not reach the main UI when a modal is open.

Let's look at an example. We want to create a popup that appears when we click a button. The popup should be half the size of the terminal and appear in the center. It should have some text and a dismiss button that allows the user to close the popup.

First, we define the layout template in an .ez file; we will use this to spawn the popup later. We'll also create a button in the main UI, which will spawn the popup:

- Layout:
    mode: float
    - Button:
        id: create_button
        text: Create popup
        auto_scale: true, true
        pos_hint: center, middle

- <MyPopup@Layout>:
    mode: box
    orientation: vertical
    size_hint: 0.5, 0.5
    pos_hint: center, middle
    border: true
    - Label:
        text: This is my popup!
        size_hint_y: none
        height: parent.height - parent.dismiss_button.height
        auto_scale_width: true
        halign: center
    - Button:
        id: dismiss_button
        text: Close popup
        auto_scale_height: true

We now have a template we can use to spawn the popup. Note that you can only use Layout templates to spawn modals, widget templates won't work. Now we'll write callbacks to create and dismiss the popup:

use ez_term::*;
let (root_widget, mut state_tree, mut scheduler) = load_ui();

let create_popup_callback = |context: Context| {

    let dismiss_popup_callback = |context: Context| {
        context.scheduler.dismiss_modal(context.state_tree);
        true
    };

    context.scheduler.open_modal("MyPopup", context.state_tree);
    let callback_config = CallbackConfig::from_on_press(Box::new(dismiss_popup_callback));
    context.scheduler.update_callback_config("dismiss_button", callback_config);
    true
};

let callback_config = CallbackConfig::from_on_press(Box::new(create_popup_callback));
scheduler.update_callback_config("create_button", callback_config);

run(root_widget, state_tree, scheduler);

Now when the create button is pressed, the popup will open. When the dismiss button is pressed from the modal, it will close again. Note that we referred to the template name when opening the popup; this is separate from any ID, it comes from the line: "- MyPopup@Layout:". Note also that we bind the dismiss callback to the modal button from inside of the callback where we spawn the modal. We cannot bind the dismiss callback when initializing the UI, because the modal does not exist at that time. It only exists after the "open_modal" method of the scheduler is called.

Continue

The general tutorial continues with: Managing widgets programmatically.