Tutorial Callback Structure

Basics

Callbacks can be created from a closure or from a function. We will see examples of both below.

All callbacks take a "context: Context" parameter. The Context object contains the StateTree object (context.state_tree) and the Scheduler object (context.scheduler). We can use these to manage the UI. The Context also contains the path of the widget for which the callback was called (context.widget_path). Some callbacks have more parameters: for example, mouse callbacks have a mouse_pos parameter, but we will discuss these separately for each callback when relevant.

Finally: each callback returns a bool. The bool indicates whether the event should be consumed. If the event is not consumed, the widget is allowed to execute its default behavior if it has any. For example, the checkbox widget has default "on_press" behavior: when pressed, it will toggle on/off. If you bind a custom "on_press" callback for a checkbox, you control whether the default behavior will be executed by returning 'false' (event not consumed, default is allowed to run) or 'true' (event consumed, default not allowed to run). This gives you the option to overwrite default widget behavior, or supplement it. If you want to know if returning true for a widget callback would overwrite default behavior, see the Reference section entry for that widget and check the callback chapter.

For mouse callbacks (such as on_left_click, on_hover, etc.), it is also important to think about whether you want to consume the event. A mouse click will always hit multiple widgets; if you click a button, you also click the layout that contains the button, the layout that contains the layout, etc. If a widget callback returns true, all the other widgets will not receive the event. The root layout is the first to receive an event, and the widget the last (i.e. events move along the widget path). For performance reasons you should return true for mouse callbacks with no default behavior, unless you have a reason not to do so.

Now we'll look at the skeleton of callbacks; note that we will see the context parameter and the bool return value which we discussed.

Callbacks from closure

use ez_term::*;

let my_callback = |context: Context| {
    true
};

Callbacks from function

use ez_term::*;

fn my_callback(context: Context) -> bool {
    true
};

Now that we know what a callback should look like, let's see how to bind callbacks.

Continue

The general tutorial continues with: Callback Configs.