Skip to main content

light_fw_core/
control.rs

1//! Канал команд управления окном.
2//!
3//! Шаблоны превращают `@click="close()"` в вызов `self.close()`. Методы
4//! управления окном объявлены в трейте [`crate::component::Component`] с
5//! реализацией по умолчанию, которая отправляет команду в этот канал.
6//! Оконный бэкенд регистрирует получателя команд ([`set_command_sender`]).
7
8use std::cell::{Cell, RefCell};
9use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
10use std::sync::{Mutex, OnceLock};
11
12/// Непрозрачный идентификатор окна, присваиваемый оконным бэкендом.
13///
14/// Используется, чтобы команда, отправленная из обработчика события, попала в
15/// то окно, где произошло событие. Значение `0` зарезервировано: оно означает
16/// «окно не задано», и [`current_window_token`] возвращает `None`, пока
17/// токеном не установлено ненулевое значение. Оконный бэкенд начинает
18/// нумерацию реальных окон с `1`, поэтому у каждого созданного окна
19/// ненулевой токен.
20pub type WindowToken = u64;
21
22thread_local! {
23    /// Токен окна, событие которого обрабатывается в данный момент.
24    static ACTIVE: Cell<WindowToken> = const { Cell::new(0) };
25}
26
27/// Запоминает окно, событие которого сейчас обрабатывается.
28///
29/// Вызывается оконным бэкендом перед обработкой события окна, чтобы методы
30/// [`crate::vdom::VWindow::close`] и подобные адресовались нужному окну.
31pub fn set_active_window(token: WindowToken) {
32    ACTIVE.with(|active| active.set(token));
33}
34
35/// Токен окна, событие которого обрабатывается в данный момент.
36///
37/// Вне обработки события возвращается `0` («окно не задано»); реальные окна
38/// получают ненулевые токены (см. [`WindowToken`]).
39pub fn active_window() -> WindowToken {
40    ACTIVE.with(Cell::get)
41}
42
43/// Кросспоточный токен «текущего» окна.
44///
45/// Значение `0` означает «окно не задано»: [`current_window_token`]
46/// возвращает `None`, пока ни одно окно не установило ненулевой токен.
47/// Оконный бэкенд начинает нумерацию реальных окон с `1` (см.
48/// [`WindowToken`]).
49static CURRENT_WINDOW: AtomicU64 = AtomicU64::new(0);
50
51/// Запоминает токен «текущего» окна для кросспоточного доступа.
52///
53/// Вызывается оконным бэкендом в [`crate::window::Window::dispatch`] — в
54/// UI-потоке, перед обработкой события окна. Позволяет задачам, запущенным
55/// из обработчика (`post_update_to`), узнать, из какого окна они пришли,
56/// даже из другого потока.
57pub fn set_current_window_token(token: WindowToken) {
58    CURRENT_WINDOW.store(token, Ordering::Relaxed);
59}
60
61/// Токен «текущего» окна для кросспоточного доступа.
62///
63/// В отличие от [`active_window`], этот токен доступен из любого потока
64/// (включая задачи, запущенные из обработчика события), и возвращает
65/// `None`, пока ни одно окно не установило токен. Используется
66/// [`crate::async_runtime::post_update_to`] для адресации обновления к
67/// конкретному окну.
68pub fn current_window_token() -> Option<WindowToken> {
69    let token = CURRENT_WINDOW.load(Ordering::Relaxed);
70    (token != 0).then_some(token)
71}
72
73/// Развёрнуто ли окно в данный момент (обновляет оконный бэкенд).
74static MAXIMIZED: AtomicBool = AtomicBool::new(false);
75
76/// Обновляет состояние развёрнутости окна.
77///
78/// Вызывается оконным бэкендом при каждом изменении состояния окна, чтобы
79/// шаблоны могли реагировать на него (`v-if="is_maximized"`).
80pub fn set_maximized(value: bool) {
81    MAXIMIZED.store(value, Ordering::Relaxed);
82}
83
84/// Развёрнуто ли окно в данный момент.
85pub fn is_maximized() -> bool {
86    MAXIMIZED.load(Ordering::Relaxed)
87}
88
89/// Команда управления окном.
90#[derive(Debug, Clone, PartialEq, Eq)]
91pub enum WindowCommand {
92    /// Закрыть окно.
93    Close,
94    /// Свернуть окно.
95    Minimize,
96    /// Развернуть окно.
97    Maximize,
98    /// Вернуть окно в обычный размер.
99    Restore,
100    /// Переключить развёрнутость окна.
101    ToggleMaximize,
102    /// Показать скрытое окно.
103    Show,
104    /// Скрыть окно.
105    Hide,
106    /// Открыть дочернее модальное окно поверх текущего.
107    OpenModal,
108    /// Открыть ещё одно главное окно приложения.
109    OpenWindow,
110    /// Открыть (или сфокусировать) окно с указанным идентификатором.
111    Open(String),
112    /// Закрыть окно с указанным идентификатором (вместе с потомками).
113    CloseWindow(String),
114    /// Показать окно с указанным идентификатором.
115    ShowWindow(String),
116    /// Скрыть окно с идентификатором.
117    HideWindow(String),
118}
119
120type Sender = Box<dyn FnMut(WindowToken, WindowCommand) + Send + 'static>;
121
122static SENDER: OnceLock<Mutex<Sender>> = OnceLock::new();
123
124/// Регистрирует получателя команд окна.
125///
126/// Вызывается оконным бэкендом при запуске цикла событий; повторная
127/// регистрация игнорируется.
128pub fn set_command_sender(sender: impl FnMut(WindowToken, WindowCommand) + Send + 'static) {
129    let _ = SENDER.set(Mutex::new(Box::new(sender)));
130}
131
132/// Отправляет команду окну, событие которого обрабатывается в данный момент.
133///
134/// Если оконный бэкенд не запущен, команда молча отбрасывается.
135pub fn request(command: WindowCommand) {
136    if let Some(sender) = SENDER.get()
137        && let Ok(mut sender) = sender.lock()
138    {
139        let token = ACTIVE.with(Cell::get);
140        sender(token, command);
141    }
142}
143
144/// Программный запрос клавиатурного фокуса от компонента.
145#[derive(Debug, Clone, PartialEq, Eq)]
146pub enum FocusCommand {
147    /// Установить фокус на узел с указанным ключом.
148    Focus(String),
149    /// Снять фокус с текущего узла.
150    Blur,
151}
152
153thread_local! {
154    /// Ожидающий запрос фокуса (потребляется оконным бэкендом).
155    static FOCUS_COMMAND: RefCell<Option<FocusCommand>> = const { RefCell::new(None) };
156    /// Ключ узла в фокусе, опубликованный оконным бэкендом.
157    static FOCUSED_KEY: RefCell<Option<String>> = const { RefCell::new(None) };
158}
159
160/// Запрашивает клавиатурный фокус на узле с ключом `key`.
161///
162/// Оконный бэкенд применяет запрос при ближайшей перерисовке. Если фокус уже
163/// на этом узле, запрос безвреден.
164pub fn focus(key: impl Into<String>) {
165    FOCUS_COMMAND.with(|slot| *slot.borrow_mut() = Some(FocusCommand::Focus(key.into())));
166}
167
168/// Запрашивает снятие клавиатурного фокуса.
169pub fn blur() {
170    FOCUS_COMMAND.with(|slot| *slot.borrow_mut() = Some(FocusCommand::Blur));
171}
172
173/// Ключ узла, находящегося в клавиатурном фокусе в данный момент.
174///
175/// Значение публикует оконный бэкенд; без запущенного окна возвращается
176/// последнее известное (по умолчанию `None`).
177pub fn focused_key() -> Option<String> {
178    FOCUSED_KEY.with(|key| key.borrow().clone())
179}
180
181/// Извлекает ожидающий запрос фокуса (вызывает оконный бэкенд).
182pub fn take_focus_command() -> Option<FocusCommand> {
183    FOCUS_COMMAND.with(|slot| slot.borrow_mut().take())
184}
185
186/// Публикует ключ узла в фокусе (вызывает оконный бэкенд).
187pub fn set_focused_key(key: Option<String>) {
188    FOCUSED_KEY.with(|slot| *slot.borrow_mut() = key);
189}
190
191#[cfg(test)]
192mod tests {
193    use super::*;
194
195    #[test]
196    fn focus_request_round_trips() {
197        set_focused_key(None);
198        assert_eq!(focused_key(), None);
199        assert_eq!(take_focus_command(), None);
200
201        focus("field");
202        assert_eq!(
203            take_focus_command(),
204            Some(FocusCommand::Focus("field".into()))
205        );
206        assert_eq!(take_focus_command(), None, "запрос потребляется один раз");
207
208        blur();
209        assert_eq!(take_focus_command(), Some(FocusCommand::Blur));
210
211        set_focused_key(Some("field".into()));
212        assert_eq!(focused_key().as_deref(), Some("field"));
213        set_focused_key(None);
214    }
215}