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}