Skip to main content

aylis_core/
question.rs

1//! Eventos que perguntam (item 3 dos ajustes): o `on_close_query` (`CanClose`), o
2//! `before_post` e o `before_delete` (recusar a gravação), o `on_validate` do campo, o
3//! `on_key_down`/`on_key_press` (engolir ou trocar a tecla), o `on_drag_start` e o
4//! `on_drag_over`. Quem dispara pergunta com [`Ui::ask`] e recebe a resposta:
5//!
6//! - um handler em Rust responde na hora, dentro do `fire`: [`Ui::refuse`] recusa (o `Err`
7//!   do handler que devolve `Result`), [`Ui::reply`] grava um campo da resposta
8//!   (`can_close`, `key`, `data`...);
9//! - um handler que não pode responder já (o backend em outra linguagem, um handler do mesmo
10//!   form que espera o que roda terminar) adia com [`Ui::defer_question`] e responde depois
11//!   com [`Ui::answer`]; quem perguntou recebe [`Asked::Deferred`] e diz, com
12//!   [`Ui::on_answer`], o que fazer quando a resposta chegar (fechar o form, gravar o
13//!   registro, entregar a tecla).
14//!
15//! Sem handler, a resposta é aceitar.
16
17use std::collections::HashMap;
18use std::rc::Rc;
19
20use crate::component::ComponentId;
21use crate::event::EventArgs;
22use crate::prop::PropValue;
23use crate::ui::Ui;
24
25/// A resposta a um evento-pergunta.
26#[derive(Clone, Debug, PartialEq)]
27pub enum Answer {
28    /// Aceito, com os campos que o handler respondeu (`can_close`, `key`...).
29    Accepted(Vec<(String, PropValue)>),
30    /// Recusado (a exceção do handler; a mensagem vai para a tela, vazia para recusar calado).
31    Refused(String),
32}
33
34impl Answer {
35    /// O campo respondido (`None` se o handler não mexeu nele).
36    pub fn value(&self, name: &str) -> Option<&PropValue> {
37        match self {
38            Answer::Accepted(values) => values.iter().rev().find(|(n, _)| n == name).map(|(_, v)| v),
39            Answer::Refused(_) => None,
40        }
41    }
42
43    /// O campo booleano respondido, ou `default`.
44    pub fn flag(&self, name: &str, default: bool) -> bool {
45        match self.value(name) {
46            Some(PropValue::Bool(b)) => *b,
47            _ => default,
48        }
49    }
50
51    pub fn is_refused(&self) -> bool {
52        matches!(self, Answer::Refused(_))
53    }
54}
55
56/// O que [`Ui::ask`] devolve.
57#[derive(Clone, Debug, PartialEq)]
58pub enum Asked {
59    /// O handler respondeu na hora (ou não havia handler: aceito, sem campos).
60    Answered(Answer),
61    /// O handler vai responder depois: o número da pergunta, para o [`Ui::on_answer`].
62    Deferred(u64),
63}
64
65/// O que fazer quando a resposta de uma pergunta adiada chegar.
66type Continuation = Box<dyn FnOnce(&mut Ui, Answer)>;
67
68/// Uma pergunta em andamento (a pilha: um handler pode perguntar de novo).
69#[derive(Default)]
70struct Frame {
71    /// O evento que perguntou (o interceptador sabe se a pergunta é a do evento dele).
72    target: Option<(ComponentId, String)>,
73    refused: Option<String>,
74    values: Vec<(String, PropValue)>,
75    deferred: Option<u64>,
76    /// O handler da pergunta já foi despachado (o primeiro `with_form` dela): um `with_form`
77    /// de dentro do handler, adiado por achar o form ocupado, não leva a pergunta junto.
78    claimed: bool,
79}
80
81#[derive(Default)]
82pub(crate) struct Questions {
83    stack: Vec<Frame>,
84    next: u64,
85    /// As adiadas: quem perguntou (o caminho, para o log) e o que fazer na resposta.
86    waiting: HashMap<u64, (ComponentId, String, Option<Continuation>)>,
87    /// As respostas que chegaram antes do `on_answer` (o handler respondeu dentro do próprio
88    /// `fire`, depois de adiar).
89    early: HashMap<u64, Answer>,
90    /// Os forms cujo `on_close_query` espera o backend, e os que a resposta já liberou.
91    pub(crate) closes: Vec<ComponentId>,
92    pub(crate) closing_now: Vec<ComponentId>,
93    pub(crate) unresponsive: Option<Rc<dyn Fn(&mut Ui, ComponentId)>>,
94    pub(crate) terminate: Option<Rc<dyn Fn(&mut Ui)>>,
95}
96
97impl Ui {
98    /// Dispara o evento-pergunta `event` de `id` e devolve a resposta (veja o módulo).
99    pub fn ask(&mut self, id: ComponentId, event: &str, args: &EventArgs) -> Asked {
100        self.questions.stack.push(Frame { target: Some((id, event.to_string())), ..Frame::default() });
101        self.fire(id, event, args);
102        let frame = self.questions.stack.pop().unwrap_or_default();
103        if let Some(token) = frame.deferred {
104            self.questions.waiting.entry(token).or_insert((id, event.to_string(), None));
105            return Asked::Deferred(token);
106        }
107        Asked::Answered(match frame.refused {
108            Some(message) => Answer::Refused(message),
109            None => Answer::Accepted(frame.values),
110        })
111    }
112
113    /// A pergunta em andamento é a do evento `event` de `id` (e ainda não foi adiada).
114    pub(crate) fn question_is_for(&self, id: ComponentId, event: &str) -> bool {
115        self.questions.stack.last().is_some_and(|f| f.deferred.is_none() && f.target.as_ref().is_some_and(|(i, e)| *i == id && e == event))
116    }
117
118    /// O despacho do handler da pergunta em andamento: `true` só na primeira vez (o
119    /// `with_form` que roda o handler dela); as chamadas de dentro do handler recebem `false`.
120    /// Sem isso, o `with_form` que o handler do `on_back` fazia no próprio form (ocupado) era
121    /// adiado levando a pergunta, e a resposta `handled` do handler se perdia (relatado pelo
122    /// RTSPlayer em 14/11: voltar do player trocava a tela e mandava o app para segundo plano).
123    pub(crate) fn claim_question(&mut self) -> bool {
124        match self.questions.stack.last_mut() {
125            Some(f) if f.deferred.is_none() && !f.claimed => {
126                f.claimed = true;
127                true
128            }
129            _ => false,
130        }
131    }
132
133    /// `true` dentro do handler de um evento-pergunta (o receptor remoto manda o evento com o
134    /// número da pergunta e adia).
135    pub fn asking(&self) -> bool {
136        self.questions.stack.last().is_some_and(|f| f.deferred.is_none())
137    }
138
139    /// Dentro de um evento-pergunta: recusa. A
140    /// mensagem vai para a tela; vazia, recusa calado.
141    pub fn refuse(&mut self, message: impl Into<String>) {
142        if let Some(frame) = self.questions.stack.last_mut() {
143            frame.refused = Some(message.into());
144        }
145    }
146
147    /// Dentro de um evento-pergunta: grava um campo da resposta (`can_close`, `key`,
148    /// `key_char`, `data`, `label`, `accept`).
149    pub fn reply(&mut self, name: &str, value: impl Into<PropValue>) {
150        if let Some(frame) = self.questions.stack.last_mut() {
151            frame.values.push((name.to_string(), value.into()));
152        }
153    }
154
155    /// Dentro de um evento-pergunta: a resposta vem depois, por [`answer`](Self::answer) com o
156    /// número devolvido. Fora de uma pergunta, devolve 0 (e o `answer(0, ..)` não faz nada).
157    pub fn defer_question(&mut self) -> u64 {
158        let Some(frame) = self.questions.stack.last_mut() else { return 0 };
159        if let Some(token) = frame.deferred {
160            return token;
161        }
162        self.questions.next += 1;
163        let token = self.questions.next;
164        frame.deferred = Some(token);
165        token
166    }
167
168    /// O que fazer quando a resposta da pergunta adiada `token` chegar (se já chegou, roda
169    /// agora).
170    pub fn on_answer(&mut self, token: u64, f: impl FnOnce(&mut Ui, Answer) + 'static) {
171        if let Some(answer) = self.questions.early.remove(&token) {
172            self.questions.waiting.remove(&token);
173            f(self, answer);
174            return;
175        }
176        if let Some(entry) = self.questions.waiting.get_mut(&token) {
177            entry.2 = Some(Box::new(f));
178        }
179    }
180
181    /// A resposta da pergunta adiada `token` (o backend respondeu). Devolve `false` se não
182    /// havia essa pergunta (já respondida, ou o número é de outra tela).
183    pub fn answer(&mut self, token: u64, answer: Answer) -> bool {
184        let Some((_, _, continuation)) = self.questions.waiting.remove(&token) else {
185            // Adiada e respondida dentro do mesmo `fire` (antes de o `ask` voltar).
186            if token != 0 && token <= self.questions.next && self.questions.stack.iter().any(|f| f.deferred == Some(token)) {
187                self.questions.early.insert(token, answer);
188                return true;
189            }
190            return false;
191        };
192        match continuation {
193            Some(f) => f(self, answer),
194            None => {
195                self.questions.early.insert(token, answer);
196            }
197        }
198        true
199    }
200
201    /// Responde à pergunta adiada `token` rodando `f` como se fosse o handler: o que ele
202    /// recusar ou responder vira a resposta. É como um handler do mesmo form, que esperou o
203    /// outro terminar, responde.
204    pub fn answering(&mut self, token: u64, f: impl FnOnce(&mut Ui)) {
205        self.questions.stack.push(Frame::default());
206        f(self);
207        let frame = self.questions.stack.pop().unwrap_or_default();
208        let answer = match frame.refused {
209            Some(message) => Answer::Refused(message),
210            None => Answer::Accepted(frame.values),
211        };
212        // Adiou de novo (um backend dentro do handler adiado): a resposta é a dele.
213        if let Some(inner) = frame.deferred {
214            self.on_answer(inner, move |ui, a| {
215                ui.answer(token, a);
216            });
217            return;
218        }
219        self.answer(token, answer);
220    }
221
222    /// A tecla Voltar do celular (decidido em 14/11; o RTSPlayer troca de tela por frames e a
223    /// tecla tirava o app da frente): pergunta ao `on_back` do form do topo. Respondido
224    /// `handled` (ou recusado), o app tratou e nada mais acontece; senão, `default` faz o de
225    /// sempre (a plataforma: cancelar o modal, fechar o form aberto, o principal para segundo
226    /// plano). Com o backend em outra linguagem, a resposta chega depois e o `default` espera.
227    pub fn back_pressed(&mut self, default: impl FnOnce(&mut Ui) + 'static) {
228        let Some(form) = self.open_forms().last().copied() else {
229            default(self);
230            return;
231        };
232        let handled = |answer: &Answer| answer.is_refused() || answer.flag("handled", false);
233        match self.ask(form, "on_back", &EventArgs::None) {
234            Asked::Answered(answer) => {
235                if !handled(&answer) {
236                    default(self);
237                }
238            }
239            Asked::Deferred(token) => self.on_answer(token, move |ui, answer| {
240                if !handled(&answer) {
241                    default(ui);
242                }
243            }),
244        }
245    }
246
247    /// As perguntas que esperam resposta (para a tela saber que o backend está devendo).
248    pub fn questions_waiting(&self) -> usize {
249        self.questions.waiting.len()
250    }
251
252    /// Esquece as perguntas de componentes liberados.
253    pub(crate) fn forget_questions(&mut self, doomed: &[ComponentId]) {
254        if !self.questions.waiting.is_empty() {
255            self.questions.waiting.retain(|_, (id, _, _)| !doomed.contains(id));
256        }
257    }
258}
259
260/// Os eventos que perguntam e os campos da resposta de cada um (o catálogo marca, e a IDE
261/// gera o esqueleto com a assinatura certa). Sem campos: só aceitar ou recusar.
262pub const QUESTION_EVENTS: &[(&str, &[&str])] = &[
263    ("on_close_query", &["can_close"]),
264    // A tecla Voltar do celular: `handled` diz que o app tratou (voltou a tela de dentro).
265    ("on_back", &["handled"]),
266    ("before_post", &[]),
267    ("before_delete", &[]),
268    ("on_validate", &[]),
269    ("on_key_down", &["key"]),
270    ("on_key_press", &["key"]),
271    ("on_drag_start", &["data", "label"]),
272    ("on_drag_over", &["accept"]),
273    ("on_apply_updates", &["results"]),
274    ("on_intercept", &["cancel"]),
275    ("before_action", &[]),
276    // O MCP (`aylis_remote::mcp`): a ferramenta responde `result`; o servidor aceita ou recusa
277    // a chamada do agente.
278    ("on_execute", &["result"]),
279    ("on_call", &[]),
280];
281
282/// Os campos da resposta do evento-pergunta `event` (`None` se não é pergunta).
283pub fn question_fields(event: &str) -> Option<&'static [&'static str]> {
284    QUESTION_EVENTS.iter().find(|(e, _)| *e == event).map(|(_, f)| *f)
285}
286
287/// Os eventos que se juntam enquanto o anterior (do mesmo componente) não terminou no backend
288/// (o catálogo marca; veja `aylis_remote::coalesces`). Clique e tecla nunca se juntam.
289pub const COALESCED_EVENTS: &[&str] = &["on_timer", "on_resize", "on_scroll", "on_pointer_move", "on_wheel", "on_progress", "on_frame"];