telar 0.1.2

A modular Rust UI framework with its own template language, reactive signals and a self-contained renderer.
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
86
87
88
89
90
91
92
93
94
95
96
97
98
99

//! Backend-agnostic secondary-surface runtime: routes `open_surface` requests to an installed host; placement/scaffold widgets live in `ui-core`.

use std::cell::RefCell;
use std::rc::Rc;

use ui_core::{LayoutItem, SurfacePlacement};

/// How a hosted surface's content is built — and rebuilt.
///
/// `Fn` rather than `FnOnce` because a surface can outlive the state it was built from: a backend that can
/// remount a live surface (see [`SurfaceControl::rebuild`]) calls this again on the same surface, so the
/// closure has to be able to produce the tree more than once. In practice that means capturing what the
/// content is *about* — an id, an edge — and resolving the rest inside, which is also what makes the rebuild
/// worth doing.
pub type SurfaceContent = Rc<dyn Fn() -> Box<dyn LayoutItem>>;

/// Turns a closure into a [`SurfaceContent`].
pub fn surface_content(build: impl Fn() -> Box<dyn LayoutItem> + 'static) -> SurfaceContent {
    Rc::new(build)
}

pub trait SurfaceControl {
    fn close(&self);
    fn is_closing(&self) -> bool;
    /// Builds the surface's content again, in place — same window, same renderer, same position.
    ///
    /// Defaults to doing nothing, which is the honest answer for a backend that cannot remount a live surface:
    /// the caller's alternative is closing and reopening, and a host that silently did that would replace a
    /// surface the caller asked to keep.
    fn rebuild(&self) {}
}

pub trait SurfaceHost {
    fn open(&self, placement: SurfacePlacement, content: SurfaceContent) -> SurfaceToken;
}

pub struct SurfaceToken {
    control: Box<dyn SurfaceControl>,
}

impl SurfaceToken {
    pub fn new(control: Box<dyn SurfaceControl>) -> Self {
        Self { control }
    }

    pub fn close(&self) {
        self.control.close();
    }

    pub fn is_closing(&self) -> bool {
        self.control.is_closing()
    }

    /// Asks the surface to build its content again without being replaced — how a surface follows something
    /// that changed underneath it (a config file, a theme) while keeping its place, its size and whatever
    /// state its content chose to keep outside the tree.
    pub fn rebuild(&self) {
        self.control.rebuild();
    }
}

impl Drop for SurfaceToken {
    fn drop(&mut self) {
        self.control.close();
    }
}

thread_local! {
    static SURFACE_HOST: RefCell<Option<Box<dyn SurfaceHost>>> = const { RefCell::new(None) };
}

pub fn set_surface_host(host: Box<dyn SurfaceHost>) {
    SURFACE_HOST.with(|h| *h.borrow_mut() = Some(host));
}

pub fn has_surface_host() -> bool {
    SURFACE_HOST.with(|h| h.borrow().is_some())
}

pub fn open_surface(placement: SurfacePlacement, content: SurfaceContent) -> SurfaceToken {
    SURFACE_HOST.with(|h| match h.borrow().as_ref() {
        Some(host) => host.open(placement, content),
        None => {
            tracing::warn!(
                "telar::open_surface: no SurfaceHost installed on this thread; surface ignored"
            );
            SurfaceToken::new(Box::new(NoopControl))
        }
    })
}

struct NoopControl;

impl SurfaceControl for NoopControl {
    fn close(&self) {}
    fn is_closing(&self) -> bool {
        true
    }
}