r3bl_tui 0.7.7

TUI library to build modern apps inspired by React, Elm, with Flexbox, CSS, editor component, emoji support, and more
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85

// Copyright (c) 2022-2025 R3BL LLC. Licensed under Apache License, Version 2.0.

use super::{ComponentRegistryMap, EventPropagation, GlobalData, HasFocus};
use crate::{CommonResult, InputEvent, RenderPipeline};
use std::fmt::Debug;

/// An app is typically a holder for [`crate::ComponentRegistry`].
///
/// It lays out a bunch of [`crate::Component`]s on its [`crate::Surface`] which do all
/// the work of rendering and input event handling.
///
/// There are examples of structs that implement this train in the [examples
/// module](https://github.com/r3bl-org/r3bl-open-core/blob/autocomplete/tui/examples/demo/ex_editor/app.rs).
///
/// Notes:
/// - Async trait docs: <https://doc.rust-lang.org/book/ch10-02-traits.html>
/// - Limitations of linking to examples module: <https://users.rust-lang.org/t/how-to-link-to-examples/67918>
pub trait App {
    /// State.
    type S: Debug + Default + Clone + Sync + Send;
    /// App Signal.
    type AS: Debug + Default + Clone + Sync + Send;

    /// This is called once at the beginning of the app's lifecycle. It is used to
    /// initialize the [`ComponentRegistryMap`] and [`HasFocus`] structs. It is called
    /// before the first render by the [`crate::TerminalWindow::main_event_loop`].
    fn app_init(
        &mut self,
        component_registry_map: &mut ComponentRegistryMap<Self::S, Self::AS>,
        has_focus: &mut HasFocus,
    );

    /// At a high level:
    /// - Use the `input_event` to dispatch an action to the store if needed.
    /// - It returns an [`EventPropagation`].
    ///
    /// More than likely a bunch of other [`crate::Component::handle_event`]s will perform
    /// the actual event handling.
    ///
    /// # Errors
    ///
    /// Returns an error if the input event handling fails.
    fn app_handle_input_event(
        &mut self,
        input_event: InputEvent,
        global_data: &mut GlobalData<Self::S, Self::AS>,
        component_registry_map: &mut ComponentRegistryMap<Self::S, Self::AS>,
        has_focus: &mut HasFocus,
    ) -> CommonResult<EventPropagation>;

    /// At a high level:
    /// - Use the `action` to dispatch an action to the store if needed.
    /// - It returns an [`EventPropagation`].
    ///
    /// More than likely a bunch of other [`crate::Component::handle_event`]s will perform
    /// the actual event handling.
    ///
    /// # Errors
    ///
    /// Returns an error if the signal handling fails.
    fn app_handle_signal(
        &mut self,
        signal: &Self::AS,
        global_data: &mut GlobalData<Self::S, Self::AS>,
        component_registry_map: &mut ComponentRegistryMap<Self::S, Self::AS>,
        has_focus: &mut HasFocus,
    ) -> CommonResult<EventPropagation>;

    /// Use the state to render the output (via crossterm). The state is immutable. If you
    /// want to change it then it should be done in the [`App::app_handle_input_event`]
    /// method.
    ///
    /// More than likely a bunch of other [`crate::Component::render`]s will perform the
    /// actual rendering.
    ///
    /// # Errors
    ///
    /// Returns an error if the rendering operation fails.
    fn app_render(
        &mut self,
        global_data: &mut GlobalData<Self::S, Self::AS>,
        component_registry_map: &mut ComponentRegistryMap<Self::S, Self::AS>,
        has_focus: &mut HasFocus,
    ) -> CommonResult<RenderPipeline>;
}