Skip to main content

aylis_core/
component.rs

1//! O modelo de componentes: [`Component`] e [`ControlBase`] (os dados
2//! comuns de todo controle visual).
3
4use std::any::Any;
5use std::fmt;
6
7use crate::align::{Align, Anchors, SelfAlign};
8use crate::canvas::Canvas;
9use crate::error::{Error, Result};
10use crate::event::{EventArgs, EventCtx, KeyEvent, PointerEvent, WheelEvent};
11use crate::geometry::{Bounds, PointF, RectF, SizeF};
12use crate::paint::PaintCtx;
13use crate::platform::CursorShape;
14use crate::prop::{PropInfo, PropKind, PropValue};
15
16/// Identificador de um componente dentro do [`Ui`](crate::Ui).
17///
18/// É "geracional": depois que o componente é liberado, o id antigo nunca mais aponta
19/// para nada (as consultas devolvem `None` em vez de acessar memória inválida).
20#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
21pub struct ComponentId {
22    pub(crate) index: u32,
23    pub(crate) generation: u32,
24}
25
26impl ComponentId {
27    /// Número estável para identificar o componente fora do Rust (C ABI, protocolo).
28    pub fn to_u64(self) -> u64 {
29        (self.generation as u64) << 32 | self.index as u64
30    }
31
32    /// O inverso de [`to_u64`](Self::to_u64). O `Ui` recusa ids de componentes liberados.
33    pub fn from_u64(value: u64) -> Self {
34        Self { index: value as u32, generation: (value >> 32) as u32 }
35    }
36}
37
38impl fmt::Display for ComponentId {
39    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
40        write!(f, "#{}v{}", self.index, self.generation)
41    }
42}
43
44/// Estado visual de um controle, usado pelo tema e pela pintura.
45#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
46pub struct ControlState {
47    pub hover: bool,
48    pub pressed: bool,
49    pub focused: bool,
50    pub checked: bool,
51    /// Calculado na pintura: o controle ou algum ancestral está com `enabled = false`.
52    pub disabled: bool,
53}
54
55/// Componente: a base de tudo que vive no [`Ui`](crate::Ui), visual ou não.
56///
57/// Todos os métodos, exceto [`class_name`](Component::class_name), têm implementação
58/// padrão — sobrescreva só o que precisar.
59///
60/// ## Controle visual
61/// Um componente é um **controle** quando devolve um [`ControlBase`] em
62/// [`control`](Component::control) / [`control_mut`](Component::control_mut).
63///
64/// ## "Herança" por composição
65/// Para criar um componente a partir de outro, guarde o componente base num campo e
66/// devolva-o em [`inner`](Component::inner) / [`inner_mut`](Component::inner_mut).
67/// Tudo que você não sobrescrever (pintura, eventos, propriedades, `ControlBase`) é
68/// repassado automaticamente para ele. Para chamar o comportamento original dentro de
69/// um método sobrescrito (o `inherited`), chame o método no campo:
70///
71/// ```ignore
72/// struct GlowButton { base: Button }
73///
74/// impl Component for GlowButton {
75///     fn class_name(&self) -> &'static str { "GlowButton" }
76///     fn inner(&self) -> Option<&dyn Component> { Some(&self.base) }
77///     fn inner_mut(&mut self) -> Option<&mut dyn Component> { Some(&mut self.base) }
78///
79///     fn paint(&self, canvas: &mut dyn Canvas, ctx: &PaintCtx) {
80///         self.base.paint(canvas, ctx); // inherited Paint
81///         // ...desenho extra
82///     }
83/// }
84/// ```
85pub trait Component: Any {
86    /// Nome da classe ("Button", "ClientDataSet"...). É o nome usado no registro de
87    /// classes, nos arquivos de layout e nos estilos do tema.
88    fn class_name(&self) -> &'static str;
89
90    /// O componente "pai" na composição, se houver (o equivalente ao ancestral).
91    fn inner(&self) -> Option<&dyn Component> {
92        None
93    }
94
95    fn inner_mut(&mut self) -> Option<&mut dyn Component> {
96        None
97    }
98
99    /// Cadeia de classes, da mais derivada para a base. Usada pelo tema: um
100    /// `GlowButton` sem estilo próprio usa o estilo de `Button`.
101    fn class_chain(&self, out: &mut Vec<&'static str>) {
102        out.push(self.class_name());
103        if let Some(inner) = self.inner() {
104            inner.class_chain(out);
105        }
106    }
107
108    /// Dados de controle visual. Componentes não visuais devolvem `None`.
109    fn control(&self) -> Option<&ControlBase> {
110        self.inner().and_then(|i| i.control())
111    }
112
113    fn control_mut(&mut self) -> Option<&mut ControlBase> {
114        self.inner_mut().and_then(|i| i.control_mut())
115    }
116
117    /// Propriedades publicadas **desta camada**. As do componente base (`inner`) e as do
118    /// [`ControlBase`] são incluídas automaticamente pelo `Ui`.
119    fn props(&self) -> &'static [PropInfo] {
120        &[]
121    }
122
123    /// O evento padrão: o duplo clique no designer cria o handler dele e abre o código.
124    /// `None`: a IDE escolhe pelo nome (o `on_change` da classe, o
125    /// `on_timer`... ou o `on_click`).
126    fn default_event(&self) -> Option<&'static str> {
127        self.inner().and_then(|c| c.default_event())
128    }
129
130    /// Lê uma propriedade desta camada; `None` se não for dela.
131    fn get_prop(&self, _name: &str) -> Option<PropValue> {
132        None
133    }
134
135    /// Grava uma propriedade desta camada. Devolva [`Error::UnknownProperty`] se não for
136    /// dela (o `Ui` então tenta a camada base).
137    fn set_prop(&mut self, name: &str, _value: PropValue) -> Result<()> {
138        Err(Error::UnknownProperty(name.to_string()))
139    }
140
141    /// Avisa que um componente foi liberado (como `Notification(AComponent, opRemove)`).
142    /// Quem guarda referências para outros componentes deve limpá-las aqui.
143    fn notification(&mut self, freed: ComponentId) {
144        if let Some(inner) = self.inner_mut() {
145            inner.notification(freed);
146        }
147    }
148
149    /// Pinta o controle. O canvas já está na origem do controle; `ctx.rect` é a área dele.
150    fn paint(&self, canvas: &mut dyn Canvas, ctx: &PaintCtx<'_>) {
151        if let Some(inner) = self.inner() {
152            inner.paint(canvas, ctx);
153        }
154    }
155
156    /// O controle não tem fundo (um texto, uma caixa de seleção, um medidor): com o `fill`
157    /// próprio, o `Ui` pinta o fundo dele inteiro. Os que têm
158    /// fundo usam o `fill` no desenho deles.
159    fn transparent_background(&self) -> bool {
160        self.inner().is_some_and(|i| i.transparent_background())
161    }
162
163    /// O `paint` deste estilo cobre o retângulo inteiro do controle com cor opaca (um painel
164    /// de fundo sólido sem cantos arredondados, um form). Com `true`, o que fica inteiro atrás
165    /// dele (um irmão pintado antes) não é pintado: um medidor animando embaixo de uma tela que
166    /// o cobre não pede quadros. Na dúvida, `false` (o padrão): só se perde a economia.
167    fn opaque(&self, style: &crate::theme::ResolvedStyle) -> bool {
168        self.inner().is_some_and(|i| i.opaque(style))
169    }
170
171    /// Pinta por cima dos filhos (bordas, anel de foco...).
172    fn paint_after(&self, canvas: &mut dyn Canvas, ctx: &PaintCtx<'_>) {
173        if let Some(inner) = self.inner() {
174            inner.paint_after(canvas, ctx);
175        }
176    }
177
178    /// A pintura (`paint` e `paint_after`) só lê: sem efeito colateral (nada de evento, de
179    /// cache que avança, de quadro de vídeo consumido) e o mesmo desenho para o mesmo estado,
180    /// estilo e propriedades. Com `true`, o `Ui` pode ensaiar o desenho fora do quadro e não
181    /// repintar o controle quando ele não mudou (o fundo de um contêiner quando o mouse entra
182    /// nele). Os contêineres simples dizem `true`; o padrão é `false`, mesmo com `inner`
183    /// (quem herda de um contêiner e pinta por cima precisa dizer de novo).
184    fn paint_is_pure(&self) -> bool {
185        false
186    }
187
188    /// Um componente provedor (item 25): o que ele oferece aos componentes que o apontam pela
189    /// propriedade `provider` (veja [`crate::providers`]). O padrão: nada.
190    fn provided(&self) -> Option<crate::providers::Provided<'_>> {
191        None
192    }
193
194    /// O tamanho real (`bounds`) mudou depois de um layout (como o `Resize`).
195    fn resized(&mut self, ctx: &mut EventCtx<'_>) {
196        if let Some(inner) = self.inner_mut() {
197            inner.resized(ctx);
198        }
199    }
200
201    /// Clique (como `Click`). O padrão dispara o evento `on_click`.
202    fn click(&mut self, ctx: &mut EventCtx<'_>) {
203        match self.inner_mut() {
204            Some(inner) => inner.click(ctx),
205            None => ctx.fire("on_click", EventArgs::None),
206        }
207    }
208
209    fn pointer_down(&mut self, ctx: &mut EventCtx<'_>, event: &PointerEvent) {
210        if let Some(inner) = self.inner_mut() {
211            inner.pointer_down(ctx, event);
212        }
213    }
214
215    fn pointer_up(&mut self, ctx: &mut EventCtx<'_>, event: &PointerEvent) {
216        if let Some(inner) = self.inner_mut() {
217            inner.pointer_up(ctx, event);
218        }
219    }
220
221    fn pointer_move(&mut self, ctx: &mut EventCtx<'_>, event: &PointerEvent) {
222        if let Some(inner) = self.inner_mut() {
223            inner.pointer_move(ctx, event);
224        }
225    }
226
227    fn pointer_enter(&mut self, ctx: &mut EventCtx<'_>) {
228        if let Some(inner) = self.inner_mut() {
229            inner.pointer_enter(ctx);
230        }
231    }
232
233    fn pointer_leave(&mut self, ctx: &mut EventCtx<'_>) {
234        if let Some(inner) = self.inner_mut() {
235            inner.pointer_leave(ctx);
236        }
237    }
238
239    fn wheel(&mut self, ctx: &mut EventCtx<'_>, event: &WheelEvent) {
240        if let Some(inner) = self.inner_mut() {
241            inner.wheel(ctx, event);
242        }
243    }
244
245    /// Pinça/giro de dois dedos. Marque como tratado (`ctx.set_handled()`) para não subir
246    /// para os pais.
247    fn gesture(&mut self, ctx: &mut EventCtx<'_>, event: &crate::event::GestureEvent) {
248        if let Some(inner) = self.inner_mut() {
249            inner.gesture(ctx, event);
250        }
251    }
252
253    /// Um deslizar do dedo (o `Carousel` troca de item, o `TabControl` de página). Marque
254    /// como tratado (`ctx.set_handled()`) para não subir para os pais.
255    fn swipe(&mut self, ctx: &mut EventCtx<'_>, event: &crate::event::SwipeEvent) {
256        if let Some(inner) = self.inner_mut() {
257            inner.swipe(ctx, event);
258        }
259    }
260
261    /// O dedo que arrastava (rolando) saiu da tela: quem segue o arrasto por dentro (a linha da
262    /// lista deslizada para mostrar as ações) fecha ou fica aberto. Vai ao controle tocado e a
263    /// todos os pais.
264    fn touch_end(&mut self, ctx: &mut EventCtx<'_>) {
265        if let Some(inner) = self.inner_mut() {
266            inner.touch_end(ctx);
267        }
268    }
269
270    /// Um deslizar que começou na borda do form (`event.start` nas coordenadas do form) e que
271    /// ninguém tratou: a `NavigationDrawer` abre. `true` se tratou.
272    fn edge_swipe(&mut self, ctx: &mut EventCtx<'_>, event: &crate::event::SwipeEvent) -> bool {
273        match self.inner_mut() {
274            Some(inner) => inner.edge_swipe(ctx, event),
275            None => false,
276        }
277    }
278
279    fn key_down(&mut self, ctx: &mut EventCtx<'_>, event: &KeyEvent) {
280        if let Some(inner) = self.inner_mut() {
281            inner.key_down(ctx, event);
282        }
283    }
284
285    fn key_up(&mut self, ctx: &mut EventCtx<'_>, event: &KeyEvent) {
286        if let Some(inner) = self.inner_mut() {
287            inner.key_up(ctx, event);
288        }
289    }
290
291    /// Tecla de atalho que ninguém tratou (como o atalho de um item de menu): o `Ui`
292    /// oferece a todos os componentes do form. Marque como tratado
293    /// ([`EventCtx::set_handled`]) se for sua.
294    fn shortcut(&mut self, ctx: &mut EventCtx<'_>, event: &KeyEvent) {
295        if let Some(inner) = self.inner_mut() {
296            inner.shortcut(ctx, event);
297        }
298    }
299
300    /// Os ganchos raros (barra de tarefas, bandeja, vista nativa, conector, arquivos soltos),
301    /// se este componente usa: devolva `Some(self)` e implemente [`PlatformHooks`].
302    fn platform_hooks(&self) -> Option<&dyn PlatformHooks> {
303        self.inner().and_then(|i| i.platform_hooks())
304    }
305
306    fn platform_hooks_mut(&mut self) -> Option<&mut dyn PlatformHooks> {
307        self.inner_mut().and_then(|i| i.platform_hooks_mut())
308    }
309
310    /// Os ganchos do designer (pontos que se arrastam dentro do controle), se este
311    /// componente usa: devolva `Some(self)` e implemente [`DesignHooks`].
312    fn design_hooks(&self) -> Option<&dyn DesignHooks> {
313        self.inner().and_then(|i| i.design_hooks())
314    }
315
316    fn design_hooks_mut(&mut self) -> Option<&mut dyn DesignHooks> {
317        self.inner_mut().and_then(|i| i.design_hooks_mut())
318    }
319
320    /// O ponto (coordenadas do controle, já sem a rotação) acerta o controle? Padrão: o
321    /// retângulo inteiro. As formas (círculo, estrela, linha...) respondem só na figura.
322    fn contains_point(&self, local: PointF, size: SizeF) -> bool {
323        self.inner().map_or(true, |i| i.contains_point(local, size))
324    }
325
326    /// Quanto o controle recebe o mouse além do próprio retângulo (as alças de uma moldura
327    /// desenhadas do lado de fora). Fora do retângulo, quem decide é o
328    /// [`contains_point`](Component::contains_point) (que recebe o ponto fora dele). Padrão: 0.
329    fn hit_slop(&self) -> f32 {
330        self.inner().map_or(0.0, |i| i.hit_slop())
331    }
332
333    /// Em que eixos o conteúdo rola (horizontal, vertical): o [`Ui::reveal`](crate::Ui::reveal)
334    /// rola estes contêineres para mostrar um controle de dentro (o campo sob o teclado).
335    fn scroll_axes(&self) -> (bool, bool) {
336        self.inner().map_or((false, false), |i| i.scroll_axes())
337    }
338
339    /// O componente edita texto. No celular, quando ele tem o foco a plataforma abre o
340    /// teclado virtual.
341    /// O que vai num arrasto que começa neste controle sem `drag_data` nem handler: as listas
342    /// e as grades mandam o item (o texto, a chave do registro) e o rótulo. `None`: nada.
343    fn drag_item(&self, _ui: &crate::Ui) -> Option<(String, String)> {
344        None
345    }
346
347    /// O que acompanha o cursor num arrasto, quando este componente é o `drag_image` de um
348    /// controle (o `DragImage`); `source` é o controle arrastado. `None`: nada.
349    fn drag_visual(&self, _ui: &crate::Ui, _source: ComponentId) -> Option<crate::DragVisual> {
350        None
351    }
352
353    /// O próprio componente recebe este arrasto (sem `accepts_drops` nem eventos): as abas
354    /// que passam de uma faixa para outra. Vale também quando ele é a origem (a aba que volta
355    /// para a faixa de onde saiu). Com `true`, recebe [`drop_hover`](Self::drop_hover),
356    /// [`drop_leave`](Self::drop_leave) e [`drop_receive`](Self::drop_receive).
357    fn drop_accepts(&self, _ui: &crate::Ui, _id: ComponentId, _data: &str) -> bool {
358        false
359    }
360
361    /// O arrasto aceito por [`drop_accepts`](Self::drop_accepts) está sobre o componente, no
362    /// ponto `position` (coordenadas dele); chamado a cada movimento.
363    fn drop_hover(&mut self, _ctx: &mut EventCtx<'_>, _data: &str, _position: PointF) {}
364
365    /// O arrasto saiu de cima do componente (ou foi cancelado).
366    fn drop_leave(&mut self, _ctx: &mut EventCtx<'_>) {}
367
368    /// Soltou o arrasto aceito sobre o componente, em `position` (coordenadas dele).
369    fn drop_receive(&mut self, _ctx: &mut EventCtx<'_>, _data: &str, _position: PointF) {}
370
371    /// O arrasto que começou neste componente acabou (`on_drag_end` também dispara).
372    fn drag_ended(&mut self, _ctx: &mut EventCtx<'_>, _data: &str, _end: crate::DragEnd) {}
373
374    fn accepts_text(&self) -> bool {
375        self.inner().is_some_and(|i| i.accepts_text())
376    }
377
378    /// O controle usa a tecla (o Enter de um Memo, as setas de uma lista): ela não vira o
379    /// Tab do form (`tab_keys`).
380    fn captures_key(&self, event: &KeyEvent) -> bool {
381        self.inner().is_some_and(|i| i.captures_key(event))
382    }
383
384    /// A legenda com o `&` da letra do atalho (`"&Salvar"`: Alt+S), para os controles que
385    /// aceitam (botões, caixas de marcar, rótulos, grupos).
386    fn mnemonic_text(&self) -> Option<&str> {
387        self.inner().and_then(|i| i.mnemonic_text())
388    }
389
390    /// No Alt+letra, o foco vai para o primeiro filho (um grupo) em vez de clicar.
391    fn mnemonic_focuses_child(&self) -> bool {
392        self.inner().is_some_and(|i| i.mnemonic_focuses_child())
393    }
394
395    /// Texto digitado (já com acentos e IME resolvidos pela plataforma).
396    fn text_input(&mut self, ctx: &mut EventCtx<'_>, text: &str) {
397        if let Some(inner) = self.inner_mut() {
398            inner.text_input(ctx, text);
399        }
400    }
401
402    fn focus_enter(&mut self, ctx: &mut EventCtx<'_>) {
403        if let Some(inner) = self.inner_mut() {
404            inner.focus_enter(ctx);
405        }
406    }
407
408    fn focus_exit(&mut self, ctx: &mut EventCtx<'_>) {
409        if let Some(inner) = self.inner_mut() {
410            inner.focus_exit(ctx);
411        }
412    }
413
414    /// Uma propriedade publicada mudou por nome ([`Ui::set_prop`](crate::Ui::set_prop): JSON,
415    /// Object Inspector, protocolo). É o lugar dos efeitos colaterais da mudança: aqui
416    /// o componente tem o `Ui` (por exemplo, o TabControl mostra a aba nova).
417    fn property_changed(&mut self, ctx: &mut EventCtx<'_>, name: &str) {
418        if let Some(inner) = self.inner_mut() {
419            inner.property_changed(ctx, name);
420        }
421    }
422
423    /// A marca do controle agora (`checked`), lida pelo núcleo na pintura: o tema reflete a
424    /// marca mesmo quando o campo muda direto, sem o `set_prop` (C02 do Tabernáculo).
425    fn checked_state(&self) -> Option<bool> {
426        self.inner().and_then(|i| i.checked_state())
427    }
428
429    /// Os argumentos do `on_change` quando a propriedade de valor `name` muda pelo código
430    /// ([`Ui::set_prop`](crate::Ui::set_prop): o acesso tipado, o protocolo);
431    /// `value` é o valor novo. O padrão é `EventArgs::Value(value)`: o controle que dispara
432    /// outro argumento quando o usuário muda (o texto do item, numa ComboBox) devolve o mesmo
433    /// aqui, e `None` não dispara. Quais propriedades contam: [`is_value_property`].
434
435    fn change_args(&self, name: &str, value: &PropValue) -> Option<EventArgs> {
436        match self.inner() {
437            Some(inner) => inner.change_args(name, value),
438            None => Some(EventArgs::Value(value.clone())),
439        }
440    }
441
442    /// A propriedade `name` só muda a pintura (o valor de um medidor, o giro de um 3D): o
443    /// `set_prop` dela repinta sem refazer o layout da tela. As do controle (cores, opacidade,
444    /// giro, deslocamento, cursor, dica) o `Ui` já conhece; aqui vão as do componente. Na
445    /// dúvida, `false` (refazer o layout nunca está errado, só custa).
446    fn paint_only_property(&self, name: &str) -> bool {
447        self.inner().is_some_and(|inner| inner.paint_only_property(name))
448    }
449
450    /// Intervalo do timer deste componente, em segundos (`None` = parado). O `Ui` dispara
451    /// `on_timer` a cada intervalo; ver [`Ui::sync_timer`](crate::Ui::sync_timer).
452    fn timer_interval(&self) -> Option<f64> {
453        self.inner().and_then(|i| i.timer_interval())
454    }
455
456    /// Quanto o timer pode atrasar ([`TimerPrecision`](crate::TimerPrecision)).
457    fn timer_precision(&self) -> crate::TimerPrecision {
458        self.inner().map(|i| i.timer_precision()).unwrap_or_default()
459    }
460
461    /// O timer conta numa thread própria (não espera o laço da tela, que pode estar
462    /// ocupado); o `on_timer` chega à tela pelo [`Poster`](crate::Poster).
463    fn timer_background(&self) -> bool {
464        self.inner().is_some_and(|i| i.timer_background())
465    }
466
467    /// Quanto o disparo que vem a seguir atrasou, em segundos (antes de [`timer`](Component::timer)).
468    fn timer_late(&mut self, late: f64) {
469        if let Some(inner) = self.inner_mut() {
470            inner.timer_late(late);
471        }
472    }
473
474    /// Um quadro vai ser pintado (pedido com [`Ui::request_frames`](crate::Ui::request_frames)):
475    /// chamado antes da pintura, com o tempo do quadro em `ctx.ui.time()`, para um movimento
476    /// que acompanha o monitor (a rolagem com deslize). Devolve se quer o próximo quadro.
477    fn frame(&mut self, ctx: &mut EventCtx<'_>) -> bool {
478        self.inner_mut().is_some_and(|inner| inner.frame(ctx))
479    }
480
481    /// O timer venceu (ver [`timer_interval`](Component::timer_interval)). O padrão dispara o
482    /// evento `on_timer`.
483    fn timer(&mut self, ctx: &mut EventCtx<'_>) {
484        match self.inner_mut() {
485            Some(inner) => inner.timer(ctx),
486            None => ctx.fire("on_timer", EventArgs::None),
487        }
488    }
489
490    /// Organiza os filhos com `align = None` (grade, fluxo...): recebe a área livre (já
491    /// sem o padding e sem o que os filhos encaixados ocuparam) e o tamanho pedido e as
492    /// margens de cada filho; devolve o retângulo de cada um, na mesma ordem. `None` (o
493    /// padrão) = posição livre.
494    fn arrange(&self, area: RectF, children: &[ArrangeItem]) -> Option<Vec<RectF>> {
495        self.inner().and_then(|i| i.arrange(area, children))
496    }
497
498    /// A linha de base do texto do controle, em pixels do topo dele, na altura `height` (para
499    /// o `FlowLayout` com `baseline` alinhar os textos de uma fileira; L12 do Tabernáculo).
500    /// `None` (o padrão): o controle não tem texto, e fica pelo fundo.
501    fn baseline(&self, ui: &crate::Ui, id: ComponentId, height: f32) -> Option<f32> {
502        self.inner().and_then(|i| i.baseline(ui, id, height))
503    }
504
505    /// O vão entre os filhos encaixados (Top, Left...), em pixels: o `gap` do `Layout` e do
506    /// `Panel` (o `gap` do CSS; L05 do Tabernáculo). Padrão: 0.
507    fn dock_gap(&self) -> f32 {
508        self.inner().map_or(0.0, |i| i.dock_gap())
509    }
510
511    /// A altura que o conteúdo pede na largura `width` (o texto de um Label quebrado nela),
512    /// para o `auto_size`. `None` (o padrão): o controle não mede o conteúdo (um contêiner
513    /// com `auto_size` fica da altura dos filhos encaixados em cima e embaixo).
514    fn auto_height(&self, ui: &crate::Ui, id: ComponentId, width: f32) -> Option<f32> {
515        self.inner().and_then(|i| i.auto_height(ui, id, width))
516    }
517
518    /// A largura que o conteúdo pede (o texto de um Label sem quebra), para o `auto_size` de
519    /// quem não é esticado na largura (`align` left, right ou none). `None` (o padrão): a
520    /// largura fica a pedida.
521    fn auto_width(&self, ui: &crate::Ui, id: ComponentId) -> Option<f32> {
522        self.inner().and_then(|i| i.auto_width(ui, id))
523    }
524
525    /// Uma camada aberta por outro (a lista de um ComboBox, as sugestões de um campo), posta
526    /// direto no form: o mouse apertado fora dela e fora de quem a abriu ([`dies_with`]) a
527    /// libera, mesmo que o clique caia onde não recebe foco (o fundo da tela, um rótulo). O
528    /// dono fica sabendo pelo [`notification`](Component::notification). Padrão: `false`.
529    ///
530    /// [`dies_with`]: Component::dies_with
531    fn closes_on_outside_press(&self) -> bool {
532        false
533    }
534
535    /// O clique fora fechou a camada ([`closes_on_outside_press`]): `true` se ela mesma se
536    /// escondeu e deve continuar existindo (o `Popover`, desenhado no form com os filhos);
537    /// `false` (o padrão), o núcleo a libera.
538    ///
539    /// [`closes_on_outside_press`]: Component::closes_on_outside_press
540    fn dismissed(&mut self, ctx: &mut EventCtx<'_>) -> bool {
541        let _ = ctx;
542        false
543    }
544
545    /// Este componente só vive enquanto `dies_with` existir: liberar aquele libera este
546    /// também. É o que a lista aberta de um ComboBox (uma camada sobre o form) usa: se o
547    /// ComboBox some (a tela foi refeita), a lista não fica órfã na tela.
548    fn dies_with(&self) -> Option<ComponentId> {
549        self.inner().and_then(|i| i.dies_with())
550    }
551
552    /// Os itens que o controle desenha sozinho (abas, linhas, itens de menu, células), para
553    /// leitores de tela, automação e testes ([`crate::automation`]). `id` é este controle.
554    fn access_items(&self, ui: &crate::Ui, id: ComponentId) -> Vec<crate::automation::AccessItem> {
555        self.inner().map_or_else(Vec::new, |i| i.access_items(ui, id))
556    }
557
558    /// Clica ou seleciona o item `index` de [`access_items`](Self::access_items). Devolve
559    /// `false` se não fez nada.
560    fn access_action(&mut self, ctx: &mut EventCtx<'_>, index: usize, action: crate::automation::ItemAction) -> bool {
561        self.inner_mut().is_some_and(|i| i.access_action(ctx, index, action))
562    }
563
564    /// Prende o controle a um irmão (mesmo pai): devolve o alvo e o ponto dele onde o
565    /// centro deste controle fica (`0..1` na largura e na altura: `(1, 0)` é o canto de
566    /// cima à direita). É o que deixa um `Badge` no canto de um botão.
567    fn attach(&self) -> Option<(ComponentId, f32, f32)> {
568        self.inner().and_then(|i| i.attach())
569    }
570
571    /// Dados extras de um evento que está sendo entregue (chave e texto), para quem recebe
572    /// os eventos fora do Rust: o protocolo os manda no `info` do evento (o `on_message` do
573    /// WebView manda a URL de quem mandou).
574    fn event_info(&self, event: &str) -> Vec<(&'static str, String)> {
575        self.inner().map(|i| i.event_info(event)).unwrap_or_default()
576    }
577
578    /// Mensagem enviada por outro componente com [`Ui::send_message`](crate::Ui::send_message).
579    /// O tipo da mensagem é livre: cada camada
580    /// (por exemplo a de dados) define as suas e o componente faz `downcast_ref`.
581    fn message(&mut self, ctx: &mut EventCtx<'_>, message: &dyn Any) {
582        if let Some(inner) = self.inner_mut() {
583            inner.message(ctx, message);
584        }
585    }
586
587    /// Os métodos que [`invoke`](Component::invoke) atende, com os tipos (o catálogo do
588    /// acesso tipado nas linguagens: `frmPaint.pcDesenho.Undo`).
589    fn methods(&self) -> &'static [MethodInfo] {
590        &[]
591    }
592
593    /// Um método pelo nome ([`Ui::invoke`](crate::Ui::invoke), o comando `invoke` do
594    /// protocolo): o que não é propriedade, como `undo`, `clear` ou `save`. Funciona igual
595    /// em Rust e nas outras linguagens (pelo protocolo). Devolve o resultado ou o erro.
596    fn invoke(&mut self, ctx: &mut EventCtx<'_>, method: &str, args: &[PropValue]) -> std::result::Result<PropValue, String> {
597        let class = self.class_name();
598        match self.inner_mut() {
599            Some(inner) => inner.invoke(ctx, method, args),
600            None => Err(format!("{class} não tem o método '{method}'")),
601        }
602    }
603
604}
605
606/// Os ganchos que só uns poucos componentes usam: fora do [`Component`], para a lista de
607/// métodos de um controle comum ficar curta. O componente que usa devolve `Some(self)` em
608/// [`Component::platform_hooks`] e [`Component::platform_hooks_mut`].
609pub trait PlatformHooks {
610    /// O que este componente quer no botão da barra de tarefas (o `Taskbar`).
611    fn taskbar(&self) -> Option<crate::taskbar::TaskbarSpec> {
612        None
613    }
614
615    /// Ícone na bandeja do sistema que este componente quer mostrar (o `TrayIcon`).
616    fn tray(&self) -> Option<crate::tray::TraySpec> {
617        None
618    }
619
620    /// Vista nativa que a plataforma põe por cima do controle (um navegador embutido...).
621    /// O controle continua sendo pintado por baixo (o que aparece onde a plataforma não
622    /// tem a vista, como no designer).
623    fn native_view(&self) -> Option<NativeView> {
624        None
625    }
626
627    /// Comandos pendentes para a vista nativa (a plataforma pega e executa).
628    fn take_native_commands(&self) -> Vec<NativeCommand> {
629        Vec::new()
630    }
631
632    /// Um conector (cano, fio) preso a dois irmãos: os pontos de ligação deles (`0..1` na
633    /// largura e na altura). O layout põe o conector em volta do caminho entre os dois; ele
634    /// segue os componentes quando eles mudam de lugar.
635    fn connection(&self) -> Option<Connection> {
636        None
637    }
638
639    /// Arquivos soltos sobre o controle (arrastados do sistema). Devolve `true` se aceitou
640    /// (senão eles vão para o pai).
641    fn files_dropped(&mut self, _ctx: &mut EventCtx<'_>, _paths: &[String]) -> bool {
642        false
643    }
644
645    /// Arquivos do sistema passando por cima (`Some`, com os caminhos) ou saindo, soltos ou
646    /// cancelados (`None`). Devolve `true` se o controle os receberia.
647    fn files_hovering(&mut self, _ctx: &mut EventCtx<'_>, _paths: Option<&[String]>) -> bool {
648        false
649    }
650}
651
652/// Os ganchos do designer: pontos que se arrastam dentro do controle (o separador das
653/// colunas de uma grade). O componente que usa devolve `Some(self)` em
654/// [`Component::design_hooks`] e [`Component::design_hooks_mut`].
655pub trait DesignHooks {
656    /// Um ponto que se arrasta dentro do controle, em coordenadas do controle. Devolve o
657    /// índice do ponto.
658    fn design_grip(&self, _local: PointF) -> Option<usize> {
659        None
660    }
661
662    /// O ponto `grip` foi arrastado `delta` desde o começo (`begin` no primeiro movimento).
663    /// Devolve a propriedade a gravar (o designer grava, com o desfazer): o componente
664    /// (`None` = este), o nome e o valor.
665    fn design_drag(&mut self, _grip: usize, _delta: PointF, _begin: bool) -> Option<(Option<ComponentId>, &'static str, PropValue)> {
666        None
667    }
668}
669
670/// Um filho para [`Component::arrange`]: o tamanho pedido e as margens.
671#[derive(Clone, Copy, Debug, PartialEq)]
672pub struct ArrangeItem {
673    pub id: ComponentId,
674    pub size: SizeF,
675    /// Já com a escala de espaços da vista ativa.
676    pub margins: Bounds,
677    /// Quantas colunas o filho pede numa grade ([`ControlBase::column_span`]).
678    pub span: u32,
679    /// Quantas linhas ([`ControlBase::row_span`]).
680    pub row_span: u32,
681    /// O lugar fixo na grade ([`ControlBase::grid_cell`]).
682    pub cell: Option<(u32, u32)>,
683    /// A parte do espaço livre da linha que ele toma ([`ControlBase::grow`]).
684    pub grow: f32,
685    /// A linha de base do texto dele, do topo ([`Component::baseline`]); posta pelo layout.
686    pub baseline: Option<f32>,
687    /// A escala de espaços da vista ativa do form: o contêiner multiplica os espaços dele
688    /// (`gap`) por ela.
689    pub spacing: f32,
690}
691
692impl ArrangeItem {
693    /// O item de um controle.
694    pub fn of(id: ComponentId, cb: &ControlBase) -> Self {
695        ArrangeItem {
696            id,
697            size: SizeF::new(cb.width(), cb.height()),
698            margins: cb.margins(),
699            span: cb.column_span(),
700            row_span: cb.row_span(),
701            cell: cb.grid_cell(),
702            grow: cb.grow(),
703            baseline: None,
704            spacing: cb.spacing_scale(),
705        }
706    }
707}
708
709/// Uma vista nativa pedida por um componente ([`Component::native_view`]).
710#[derive(Clone, Debug, PartialEq)]
711pub enum NativeView {
712    /// Navegador embutido: abre `url` ou, sem ela, mostra `html`. Quando `generation`
713    /// muda, a plataforma carrega de novo. `navigation`: os endereços (origens ou prefixos)
714    /// para onde a página pode navegar (vazia, todos); `sandbox`: o atributo do `<iframe>`
715    /// no navegador.
716    ///
717    /// O ambiente do navegador (só ao criar a vista; o relatório do Tabernáculo, W07):
718    /// `background` é a cor antes da primeira pintura da página; `data_dir`, a pasta de dados
719    /// (vazia: a do sistema); `browser_args`, os argumentos do navegador do sistema (o WebView2).
720    Web { url: String, html: String, generation: u64, navigation: Vec<String>, sandbox: String, background: Option<crate::Color>, data_dir: String, browser_args: String },
721}
722
723/// Mensagem de uma página do navegador embutido para o app: o texto e a URL de quem mandou.
724/// A plataforma entrega ao componente com [`Ui::send_message`](crate::Ui::send_message); ele
725/// decide se a origem vale e dispara o `on_message`.
726#[derive(Clone, Debug, PartialEq)]
727pub struct WebMessage {
728    pub text: String,
729    pub url: String,
730}
731
732/// A navegação do navegador embutido para `url` é permitida pela lista (o
733/// `allowed_navigation` do WebView)? O conteúdo interno (`about:`, `data:`) sempre. Um item só
734/// com a origem (`https://site.com`) libera o site inteiro; com caminho, só o que começa por ele.
735pub fn navigation_allowed(allowed: &[String], url: &str) -> bool {
736    allowed.is_empty()
737        || url.starts_with("about:")
738        || url.starts_with("data:")
739        || allowed.iter().any(|a| {
740            let a = a.trim_end_matches('/');
741            url == a || url.starts_with(&format!("{a}/")) || url.starts_with(&format!("{a}?")) || (a.matches('/').count() <= 2 && url_origin(url) == url_origin(a))
742        })
743}
744
745/// A origem (`https://site.com:8080`) de um endereço, para comparar com uma lista.
746pub fn url_origin(url: &str) -> String {
747    let Some((scheme, rest)) = url.split_once("://") else { return url.to_string() };
748    let host = rest.split(['/', '?', '#']).next().unwrap_or_default();
749    format!("{}://{}", scheme.to_ascii_lowercase(), host.to_ascii_lowercase())
750}
751
752/// Um método de [`Component::invoke`]: o nome, o tipo de cada argumento e o do resultado
753/// (`None`: não devolve nada que interesse).
754#[derive(Clone, Copy, Debug, PartialEq)]
755pub struct MethodInfo {
756    pub name: &'static str,
757    pub args: &'static [PropKind],
758    pub returns: Option<PropKind>,
759    /// O nome de cada argumento (`path`), que o acesso tipado gerado usa nas assinaturas;
760    /// vazio: sem nome (o gerado numera, `a1`, `a2`).
761    pub params: &'static [&'static str],
762}
763
764impl MethodInfo {
765    pub const fn new(name: &'static str, args: &'static [PropKind], returns: Option<PropKind>) -> Self {
766        Self { name, args, returns, params: &[] }
767    }
768
769    /// Os nomes dos argumentos, na ordem de `args`:
770    /// `MethodInfo::new("save_to", &[PropKind::String], None).params(&["path"])`.
771    pub const fn params(self, names: &'static [&'static str]) -> Self {
772        Self { params: names, ..self }
773    }
774}
775
776/// Comando para uma vista nativa.
777#[derive(Clone, Debug, PartialEq)]
778pub enum NativeCommand {
779    /// Roda JavaScript na página.
780    Eval(String),
781    Back,
782    Forward,
783    Reload,
784}
785
786/// Uma vista nativa a mostrar: o controle, onde (relativo ao form) e o que é.
787#[derive(Clone, Debug, PartialEq)]
788pub struct NativeViewSlot {
789    pub id: ComponentId,
790    pub rect: crate::RectF,
791    /// A parte que aparece (os pais que recortam, como uma caixa rolada, cortam o resto),
792    /// nas mesmas coordenadas de `rect`; `None`: inteira.
793    pub clip: Option<crate::RectF>,
794    pub visible: bool,
795    pub view: NativeView,
796    pub commands: Vec<NativeCommand>,
797}
798
799/// Todas as propriedades publicadas de um componente: as da classe, as das camadas de
800/// composição e as do [`ControlBase`] (sem `name` nem os eventos ligados no `Ui`).
801///
802/// Trabalha direto no componente, sem precisar do [`Ui`](crate::Ui): serve, por exemplo,
803/// para ler os valores padrão de uma instância nova da classe.
804pub fn prop_infos_of(component: &dyn Component) -> Vec<PropInfo> {
805    let mut out: Vec<PropInfo> = Vec::new();
806    // Os nomes já vistos num conjunto: procurar na lista a cada propriedade era quadrático
807    // (~90 por controle), e isso roda para cada componente no índice de referências.
808    let mut seen = std::collections::HashSet::new();
809    let mut push = |info: &PropInfo| {
810        if seen.insert(info.name) {
811            out.push(*info);
812        }
813    };
814    let mut layer = Some(component);
815    while let Some(l) = layer {
816        l.props().iter().for_each(&mut push);
817        layer = l.inner();
818    }
819    if component.control().is_some() {
820        ControlBase::PROPS.iter().for_each(&mut push);
821    }
822    out
823}
824
825/// A descrição de uma propriedade pelo nome, na mesma ordem de [`prop_infos_of`] (a camada
826/// de fora vence), sem montar a lista inteira: todo `get_prop`/`set_prop` passa por aqui.
827pub fn prop_info_of(component: &dyn Component, name: &str) -> Option<PropInfo> {
828    let mut layer = Some(component);
829    while let Some(l) = layer {
830        if let Some(info) = l.props().iter().find(|p| p.name == name) {
831            return Some(*info);
832        }
833        layer = l.inner();
834    }
835    if component.control().is_some() {
836        return ControlBase::PROPS.iter().find(|p| p.name == name).copied();
837    }
838    None
839}
840
841/// Lê uma propriedade (que não seja evento) direto no componente, procurando em todas as
842/// camadas e no [`ControlBase`].
843/// As propriedades que são "o valor" de um controle (o que o usuário muda e o `on_change`
844/// avisa), quando publicadas em `Data` (ou `Runtime`, como o `value` da ComboBox).
845pub const VALUE_PROPERTIES: [&str; 19] = [
846    "text", "checked", "value", "item_index", "selected", "date", "end_date", "time", "color", "files", "html", "index", "page", "hotkey",
847    "angle", "pressed", "position", "low", "high",
848];
849
850/// Mudar a propriedade pelo código dispara o `on_change` do controle (se ele tiver um):
851/// as de [`VALUE_PROPERTIES`] (fora das de aparência, como o `text` de um
852/// CheckBox, que é a legenda), a aba escolhida e o aberto/fechado.
853pub fn is_value_property(info: &PropInfo) -> bool {
854    match info.name {
855        "tab_index" | "expanded" => true,
856        name => matches!(info.category, "Data" | "Runtime") && VALUE_PROPERTIES.contains(&name),
857    }
858}
859
860pub fn read_prop(component: &dyn Component, name: &str) -> Option<PropValue> {
861    let mut layer = Some(component);
862    while let Some(l) = layer {
863        if let Some(v) = l.get_prop(name) {
864            return Some(v);
865        }
866        layer = l.inner();
867    }
868    component.control().and_then(|cb| cb.get_prop(name))
869}
870
871/// Referência guardada pelas âncoras: tamanho do pai e retângulo do controle no momento
872/// em que a posição foi definida.
873#[derive(Clone, Copy, Debug, PartialEq)]
874pub(crate) struct AnchorRef {
875    pub(crate) parent: SizeF,
876    pub(crate) rect: RectF,
877}
878
879/// Dados comuns de todo controle visual.
880///
881/// `left`, `top`, `width` e `height` são os valores **pedidos**. A posição e o tamanho
882/// **reais**, calculados pelo layout (Align/Anchors), ficam em [`bounds`](Self::bounds).
883#[derive(Clone, Debug)]
884pub struct ControlBase {
885    /// Posição a partir do canto do pai; só vale com `align: none`.
886    left: f32,
887    /// Posição a partir do topo do pai; só vale com `align: none`.
888    top: f32,
889    /// Largura pedida; o `align` pode esticar (top, bottom, client).
890    width: f32,
891    /// Altura pedida; o `align` pode esticar (left, right, client).
892    height: f32,
893    /// Espaço por fora, até os vizinhos e a borda do pai: número, `[h, v]` ou `[esquerda, cima, direita, baixo]`.
894    margins: Bounds,
895    /// Espaço por dentro, até os filhos: número, `[h, v]` ou `[esquerda, cima, direita, baixo]`.
896    padding: Bounds,
897    /// Encaixe no pai: `top`/`bottom` esticam na largura, `left`/`right` na altura, `client` ocupa o resto; `none` usa `left`/`top`.
898    align: Align,
899    /// Com `align: none`, os lados que acompanham o pai quando ele muda de tamanho: `left,right` estica na largura, só `right` anda junto com a borda direita.
900    anchors: Anchors,
901    /// Aparece; escondido não ocupa lugar no layout.
902    visible: bool,
903    /// Aceita clique e teclado; desligado aparece apagado, e os filhos também.
904    enabled: bool,
905    /// Recebe o mouse; desligado, o clique passa para o que está embaixo.
906    hit_test: bool,
907    /// Corta o desenho dos filhos na borda dele.
908    clip_children: bool,
909    /// Pinta com o estado do pai (`hover`, `pressed`, `checked`): o rótulo da linha marcada
910    /// fica com a cor de marcado do tema sem trocar o estilo filho a filho (C25 do Tabernáculo).
911    inherit_state: bool,
912    /// Os textos dele passam pela tradução do app (o padrão). Desligado, ficam como estão e
913    /// não entram na lista do que traduzir: um nome próprio, um código, um valor de exemplo
914    /// (G19 do Tabernáculo).
915    translatable: bool,
916    /// A roda do mouse em cima dele fica com ele (não rola os contêineres de fora), mesmo
917    /// sem ele rolar: uma prévia que dá zoom com a roda, um mapa, um gráfico.
918    captures_wheel: bool,
919    /// Pode receber o foco do teclado (clique ou Tab).
920    can_focus: bool,
921    /// Pode ser arrastado (o `drag` diz o que vai junto).
922    draggable: bool,
923    /// Aceita o que é solto em cima dele (`on_drop`).
924    accepts_drops: bool,
925    /// O arrasto declarado (sem handler): o que vai (`"cliente:123"`, o tipo antes do primeiro
926    /// `:`) e o rótulo que acompanha o mouse; os tipos que este destino aceita (`"cliente;produto"`).
927    drag: Option<Box<DragDecl>>,
928    /// Entra na ordem do Tab.
929    tab_stop: bool,
930    /// No toque, arrastar rola o contêiner de fora em vez de ir para o controle.
931    pan_on_touch: bool,
932    /// Menu de contexto: abre no clique direito.
933    pub(crate) popup_menu: Option<ComponentId>,
934    /// O cursor do mouse em cima dele.
935    cursor: CursorShape,
936    /// Transparência de 0 (invisível) a 1, com os filhos; continua no layout e clicável.
937    opacity: f32,
938    /// Como o controle (com os filhos) se junta ao que está por baixo (o `mix-blend-mode`
939    /// do CSS): `difference` com branco é o negativo, como a marca d'água sobre um vídeo.
940    blend_mode: crate::BlendMode,
941    /// Giro em graus, em torno do centro.
942    rotation: f32,
943    /// A escala do controle e de tudo dentro dele (1 = normal): ele ocupa o
944    /// mesmo retângulo no pai, e o desenho dele e o layout dos filhos acontecem num espaço do
945    /// tamanho do retângulo dividido pela escala, ampliado na pintura. O clique, o foco e a
946    /// área a repintar acompanham ([`ControlBase::inner_size`]).
947    scale: f32,
948    /// Deslocamento só do desenho (não muda o layout): animações e transições.
949    translate: PointF,
950    /// O desenho dele e dos filhos guardado numa imagem, refeita só quando algo lá dentro
951    /// muda: um painel pesado que desliza ou some aos poucos.
952    cache_layer: bool,
953    /// Proporção fixa (largura ÷ altura; 0 = livre), como o `VResponsive` do Vuetify.
954    aspect_ratio: f32,
955    /// Largura máxima (0 = sem limite), como o `max-width` do CSS com margem automática.
956    max_width: f32,
957    /// Largura mínima, altura mínima e máxima (0 = sem limite).
958    min_width: f32,
959    /// Altura mínima: o layout e o `auto_size` não o deixam mais baixo (0 = sem limite).
960    min_height: f32,
961    /// Altura máxima: o layout e o `auto_size` não o deixam mais alto (0 = sem limite; a mínima vence).
962    max_height: f32,
963    /// Encaixado: estica na faixa ou fica com o próprio tamanho no começo, meio ou fim.
964    self_align: SelfAlign,
965    /// O tamanho sai do conteúdo: a altura; num Label encaixado à esquerda ou à direita, também a largura.
966    auto_size: bool,
967    /// Quantas colunas ocupa num `GridLayout` (o `colspan`; 1 ou 0: uma).
968    column_span: u32,
969    /// O lugar fixo num `GridLayout`: linha e coluna (-1: segue a ordem) e
970    /// quantas linhas ocupa. O relatório do Tabernáculo, G12.
971    grid_row: i16,
972    /// A coluna fixa num `GridLayout`, contando de 0 (-1: segue a ordem); vale junto com o `grid_row`.
973    grid_column: i16,
974    /// Quantas linhas ocupa num `GridLayout` (1 ou 0: uma).
975    row_span: u16,
976    /// Quanto do espaço que sobra na linha de um `FlowLayout` ele toma (o `flex-grow`): um
977    /// `Layout` vazio com `grow` 1 é o espaçador que empurra o resto para o fim (L04).
978    grow: f32,
979    /// As escalas de fonte e de espaços da vista ativa do form (postas pelo layout; veja
980    /// `views.rs`): os getters de `margins`/`padding` e a fonte da pintura já saem escalados.
981    pub(crate) text_scale: f32,
982    pub(crate) spacing_scale: f32,
983    /// Sombra do controle; quando há, vale no lugar da sombra do estilo.
984    shadow: Option<crate::canvas::Shadow>,
985    /// Um número livre para o código (não muda nada na tela).
986    tag: i64,
987    /// Os textos que quase nenhum controle usa (o `tag_string`, o `accessible_name`), numa
988    /// caixa só, criada quando um deles tem algo: 8 bytes por controle.
989    rare: Option<Box<RareTexts>>,
990    /// A variante do tema (`primary`, `outline`, `flat`, `card`...): o estilo `Classe.variante`.
991    style: String,
992    /// Tema próprio (pelo nome), que vale também para os filhos. Vazio = o do pai.
993    theme: String,
994    /// Dica mostrada com o mouse parado em cima.
995    hint: String,
996    state: ControlState,
997    pub(crate) bounds: RectF,
998    pub(crate) anchor_ref: Option<AnchorRef>,
999    /// Controle flutuante preso a outro (ver [`Ui::follow`](crate::Ui::follow)): o alvo e a
1000    /// distância do canto dele (medida no primeiro layout).
1001    pub(crate) follow: Option<(ComponentId, Option<PointF>)>,
1002    /// `visible` desligado pela propriedade no designer: o controle continua no layout e
1003    /// clicável, pintado translúcido (em execução ele some).
1004    pub(crate) design_hidden: bool,
1005    /// Só aparece no designer (o relatório: em execução, só a visualização o mostra).
1006    pub(crate) design_only: bool,
1007    /// Fica da esquerda para a direita mesmo com a interface espelhada (árabe), ele e os
1008    /// filhos: o designer da IDE, um gráfico, um mapa.
1009    pub(crate) keep_left_to_right: bool,
1010    /// As cores próprias (vazio = as do tema).
1011    pub(crate) colors: ColorOverride,
1012    /// A fonte própria; o que ficar sem valor vem do pai.
1013    pub(crate) font: FontOverride,
1014    /// Quanto o conteúdo está rolado.
1015    scroll_offset: PointF,
1016    /// A rolagem com que o último layout pôs os filhos: a posição de um filho no conteúdo é a
1017    /// dele mais esta, mesmo antes do próximo layout.
1018    pub(crate) laid_out_scroll: PointF,
1019    /// Faixas da tela cobertas pelo sistema (só no form; ver [`Ui::set_safe_area`](crate::Ui::set_safe_area)).
1020    pub(crate) safe_area: Bounds,
1021    /// Tamanho ocupado pelos filhos, calculado no layout (sem a rolagem).
1022    pub(crate) content_size: SizeF,
1023}
1024
1025impl Default for ControlBase {
1026    fn default() -> Self {
1027        Self::new(100.0, 100.0)
1028    }
1029}
1030
1031impl ControlBase {
1032    /// Propriedades publicadas comuns a todos os controles.
1033    pub const PROPS: &'static [PropInfo] = &[
1034        PropInfo::new("left", PropKind::Float, "Layout"),
1035        PropInfo::new("top", PropKind::Float, "Layout"),
1036        PropInfo::new("width", PropKind::Float, "Layout"),
1037        PropInfo::new("height", PropKind::Float, "Layout"),
1038        PropInfo::new("align", PropKind::Enum(<Align as crate::prop::PropEnum>::NAMES), "Layout"),
1039        PropInfo::new("anchors", PropKind::Set(&Anchors::NAMES), "Layout"),
1040        PropInfo::new("margins", PropKind::Bounds, "Layout"),
1041        PropInfo::new("padding", PropKind::Bounds, "Layout"),
1042        PropInfo::new("visible", PropKind::Bool, "Behavior"),
1043        PropInfo::new("enabled", PropKind::Bool, "Behavior"),
1044        PropInfo::new("hit_test", PropKind::Bool, "Behavior"),
1045        PropInfo::new("clip_children", PropKind::Bool, "Behavior"),
1046        PropInfo::new("inherit_state", PropKind::Bool, "Appearance"),
1047        PropInfo::new("translate", PropKind::Bool, "Behavior"),
1048        PropInfo::new("captures_wheel", PropKind::Bool, "Behavior"),
1049        PropInfo::new("can_focus", PropKind::Bool, "Behavior"),
1050        PropInfo::new("draggable", PropKind::Bool, "Behavior"),
1051        PropInfo::new("accepts_drops", PropKind::Bool, "Behavior"),
1052        PropInfo::new("drag_data", PropKind::String, "Behavior"),
1053        PropInfo::new("drag_label", PropKind::String, "Behavior"),
1054        PropInfo::new("drag_image", PropKind::Component, "Behavior"),
1055        PropInfo::new("drop_types", PropKind::String, "Behavior"),
1056        PropInfo::new("tab_stop", PropKind::Bool, "Behavior"),
1057        PropInfo::new("cursor", PropKind::Enum(<CursorShape as crate::prop::PropEnum>::NAMES), "Behavior"),
1058        PropInfo::new("opacity", PropKind::Float, "Appearance"),
1059        PropInfo::new("blend_mode", PropKind::Enum(<crate::BlendMode as crate::prop::PropEnum>::NAMES), "Appearance"),
1060        PropInfo::new("cache_layer", PropKind::Bool, "Appearance"),
1061        PropInfo::new("rotation", PropKind::Angle, "Layout"),
1062        PropInfo::new("scale", PropKind::Float, "Layout"),
1063        PropInfo::new("translate_x", PropKind::Float, "Appearance"),
1064        PropInfo::new("translate_y", PropKind::Float, "Appearance"),
1065        PropInfo::new("aspect_ratio", PropKind::Float, "Layout"),
1066        PropInfo::new("max_width", PropKind::Float, "Layout"),
1067        PropInfo::new("min_width", PropKind::Float, "Layout"),
1068        PropInfo::new("min_height", PropKind::Float, "Layout"),
1069        PropInfo::new("max_height", PropKind::Float, "Layout"),
1070        PropInfo::new("self_align", PropKind::Enum(<SelfAlign as crate::prop::PropEnum>::NAMES), "Layout"),
1071        PropInfo::new("auto_size", PropKind::Bool, "Layout"),
1072        PropInfo::new("column_span", PropKind::Int, "Layout"),
1073        PropInfo::new("grid_row", PropKind::Int, "Layout"),
1074        PropInfo::new("grid_column", PropKind::Int, "Layout"),
1075        PropInfo::new("row_span", PropKind::Int, "Layout"),
1076        PropInfo::new("grow", PropKind::Float, "Layout"),
1077        PropInfo::new("shadow", PropKind::Shadow, "Appearance"),
1078        PropInfo::new("style", PropKind::String, "Appearance"),
1079        PropInfo::new("theme", PropKind::String, "Appearance"),
1080        PropInfo::new("fill", PropKind::Color, "Appearance"),
1081        PropInfo::new("border_color", PropKind::Color, "Appearance"),
1082        PropInfo::new("text_color", PropKind::Color, "Appearance"),
1083        PropInfo::new("accent_color", PropKind::Color, "Appearance"),
1084        PropInfo::new("success_color", PropKind::Color, "Appearance"),
1085        PropInfo::new("warning_color", PropKind::Color, "Appearance"),
1086        PropInfo::new("danger_color", PropKind::Color, "Appearance"),
1087        PropInfo::new("font_family", PropKind::String, "Font"),
1088        PropInfo::new("font_size", PropKind::Float, "Font"),
1089        PropInfo::new("font_weight", PropKind::Enum(&FONT_WEIGHTS), "Font"),
1090        PropInfo::new("font_italic", PropKind::Bool, "Font"),
1091        PropInfo::new("font_underline", PropKind::Bool, "Font"),
1092        PropInfo::new("font_strikeout", PropKind::Bool, "Font"),
1093        PropInfo::new("hint", PropKind::String, "Behavior"),
1094        PropInfo::new("tag", PropKind::Int, "Misc"),
1095        PropInfo::new("tag_string", PropKind::String, "Misc"),
1096        PropInfo::new("accessible_name", PropKind::String, "Behavior"),
1097        PropInfo::new("popup_menu", PropKind::Component, "Behavior"),
1098        PropInfo::new("on_click", PropKind::Event, "Events"),
1099        PropInfo::new("on_dbl_click", PropKind::Event, "Events"),
1100        PropInfo::new("on_long_press", PropKind::Event, "Events"),
1101        PropInfo::new("on_pointer_down", PropKind::Event, "Events"),
1102        PropInfo::new("on_pointer_up", PropKind::Event, "Events"),
1103        PropInfo::new("on_pointer_move", PropKind::Event, "Events"),
1104        PropInfo::new("on_pointer_enter", PropKind::Event, "Events"),
1105        PropInfo::new("on_pointer_leave", PropKind::Event, "Events"),
1106        PropInfo::new("on_wheel", PropKind::Event, "Events"),
1107        PropInfo::new("on_gesture", PropKind::Event, "Events"),
1108        PropInfo::new("on_swipe", PropKind::Event, "Events"),
1109        PropInfo::new("on_key_down", PropKind::Event, "Events"),
1110        PropInfo::new("on_key_press", PropKind::Event, "Events"),
1111        PropInfo::new("on_key_up", PropKind::Event, "Events"),
1112        PropInfo::new("on_enter", PropKind::Event, "Events"),
1113        PropInfo::new("on_exit", PropKind::Event, "Events"),
1114        PropInfo::new("on_resize", PropKind::Event, "Events"),
1115        PropInfo::new("on_drag_start", PropKind::Event, "Events"),
1116        PropInfo::new("on_drag_over", PropKind::Event, "Events"),
1117        PropInfo::new("on_drag_move", PropKind::Event, "Events"),
1118        PropInfo::new("on_drag_leave", PropKind::Event, "Events"),
1119        PropInfo::new("on_drag_drop", PropKind::Event, "Events"),
1120        PropInfo::new("on_drag_end", PropKind::Event, "Events"),
1121    ];
1122
1123    pub fn new(width: f32, height: f32) -> Self {
1124        Self {
1125            left: 0.0,
1126            top: 0.0,
1127            width,
1128            height,
1129            margins: Bounds::ZERO,
1130            padding: Bounds::ZERO,
1131            align: Align::None,
1132            anchors: Anchors::default(),
1133            visible: true,
1134            enabled: true,
1135            hit_test: true,
1136            clip_children: false,
1137            inherit_state: false,
1138            translatable: true,
1139            captures_wheel: false,
1140            can_focus: false,
1141            draggable: false,
1142            accepts_drops: false,
1143            drag: None,
1144            tab_stop: true,
1145            pan_on_touch: true,
1146            popup_menu: None,
1147            cursor: CursorShape::Default,
1148            opacity: 1.0,
1149            blend_mode: crate::BlendMode::Normal,
1150            rotation: 0.0,
1151            scale: 1.0,
1152            translate: PointF::ZERO,
1153            cache_layer: false,
1154            aspect_ratio: 0.0,
1155            max_width: 0.0,
1156            min_width: 0.0,
1157            min_height: 0.0,
1158            max_height: 0.0,
1159            self_align: SelfAlign::Stretch,
1160            auto_size: false,
1161            column_span: 1,
1162            grid_row: -1,
1163            grid_column: -1,
1164            row_span: 1,
1165            grow: 0.0,
1166            text_scale: 1.0,
1167            spacing_scale: 1.0,
1168            shadow: None,
1169            tag: 0,
1170            rare: None,
1171            style: String::new(),
1172            theme: String::new(),
1173            hint: String::new(),
1174            state: ControlState::default(),
1175            bounds: RectF::new(0.0, 0.0, width, height),
1176            anchor_ref: None,
1177            follow: None,
1178            design_hidden: false,
1179            design_only: false,
1180            keep_left_to_right: false,
1181            colors: ColorOverride::default(),
1182            font: FontOverride::default(),
1183            scroll_offset: PointF::ZERO,
1184            laid_out_scroll: PointF::ZERO,
1185            content_size: SizeF::ZERO,
1186            safe_area: Bounds::default(),
1187        }
1188    }
1189
1190    // ----- leitura -----
1191
1192    pub fn left(&self) -> f32 {
1193        self.left
1194    }
1195
1196    pub fn top(&self) -> f32 {
1197        self.top
1198    }
1199
1200    pub fn width(&self) -> f32 {
1201        self.width
1202    }
1203
1204    pub fn height(&self) -> f32 {
1205        self.height
1206    }
1207
1208    pub fn position(&self) -> PointF {
1209        PointF::new(self.left, self.top)
1210    }
1211
1212    pub fn size(&self) -> SizeF {
1213        SizeF::new(self.width, self.height)
1214    }
1215
1216    /// As margens que valem no layout (com a escala de espaços da vista ativa; a propriedade
1217    /// guarda a do desenho).
1218    pub fn margins(&self) -> Bounds {
1219        if self.spacing_scale == 1.0 { self.margins } else { self.margins.scaled(self.spacing_scale) }
1220    }
1221
1222    /// O padding que vale no layout, como as [`margins`](Self::margins).
1223    pub fn padding(&self) -> Bounds {
1224        if self.spacing_scale == 1.0 { self.padding } else { self.padding.scaled(self.spacing_scale) }
1225    }
1226
1227    pub fn align(&self) -> Align {
1228        self.align
1229    }
1230
1231    pub fn anchors(&self) -> Anchors {
1232        self.anchors
1233    }
1234
1235    pub fn visible(&self) -> bool {
1236        self.visible
1237    }
1238
1239    /// Só aparece no designer (em execução não é pintado nem recebe o mouse).
1240    pub fn design_only(&self) -> bool {
1241        self.design_only
1242    }
1243
1244    /// As cores próprias.
1245    pub fn colors(&self) -> ColorOverride {
1246        self.colors
1247    }
1248
1249    pub fn set_colors(&mut self, colors: ColorOverride) -> &mut Self {
1250        self.colors = colors;
1251        self
1252    }
1253
1254    pub fn set_design_only(&mut self, on: bool) -> &mut Self {
1255        self.design_only = on;
1256        self
1257    }
1258
1259    /// Fica da esquerda para a direita (ele e os filhos) com a interface espelhada.
1260    pub fn keep_left_to_right(&self) -> bool {
1261        self.keep_left_to_right
1262    }
1263
1264    pub fn set_keep_left_to_right(&mut self, on: bool) -> &mut Self {
1265        self.keep_left_to_right = on;
1266        self
1267    }
1268
1269    pub fn enabled(&self) -> bool {
1270        self.enabled
1271    }
1272
1273    pub fn hit_test(&self) -> bool {
1274        self.hit_test
1275    }
1276
1277    pub fn translatable(&self) -> bool {
1278        self.translatable
1279    }
1280
1281    pub fn set_translatable(&mut self, v: bool) -> &mut Self {
1282        self.translatable = v;
1283        self
1284    }
1285
1286    pub fn inherit_state(&self) -> bool {
1287        self.inherit_state
1288    }
1289
1290    pub fn set_inherit_state(&mut self, v: bool) -> &mut Self {
1291        self.inherit_state = v;
1292        self
1293    }
1294
1295    pub fn clip_children(&self) -> bool {
1296        self.clip_children
1297    }
1298
1299    pub fn captures_wheel(&self) -> bool {
1300        self.captures_wheel
1301    }
1302
1303    /// Pode receber o foco do teclado (como `CanFocus`).
1304    /// Arrastável: passar de alguns pontos com o
1305    /// botão pressionado dispara `on_drag_start`, e o handler começa o arrasto com
1306    /// [`Ui::begin_drag`](crate::Ui::begin_drag).
1307    pub fn draggable(&self) -> bool {
1308        self.draggable
1309    }
1310
1311    pub fn set_draggable(&mut self, v: bool) -> &mut Self {
1312        self.draggable = v;
1313        self
1314    }
1315
1316    /// Recebe o que é arrastado: `on_drag_over` ao entrar (o handler recusa com
1317    /// [`Ui::reject_drop`](crate::Ui::reject_drop)) e `on_drag_drop` ao soltar.
1318    pub fn accepts_drops(&self) -> bool {
1319        self.accepts_drops
1320    }
1321
1322    pub fn set_accepts_drops(&mut self, v: bool) -> &mut Self {
1323        self.accepts_drops = v;
1324        self
1325    }
1326
1327    /// O que vai no arrasto declarado (vazio: só com o `on_drag_start`).
1328    pub fn drag_data(&self) -> &str {
1329        self.drag.as_ref().map_or("", |d| d.data.as_str())
1330    }
1331
1332    pub fn drag_label(&self) -> &str {
1333        self.drag.as_ref().map_or("", |d| d.label.as_str())
1334    }
1335
1336    /// O `DragImage` do arrasto (a imagem que acompanha o cursor).
1337    pub fn drag_image(&self) -> Option<ComponentId> {
1338        self.drag.as_ref().and_then(|d| d.image)
1339    }
1340
1341    /// O `DragImage` foi liberado: a referência sai.
1342    pub(crate) fn forget_drag_image(&mut self, doomed: &[ComponentId]) {
1343        if let Some(d) = self.drag.as_mut().filter(|d| d.image.is_some_and(|i| doomed.contains(&i))) {
1344            d.image = None;
1345        }
1346    }
1347
1348    /// Os tipos aceitos ao soltar (vazio: decide o `on_drag_over`).
1349    pub fn drop_types(&self) -> &str {
1350        self.drag.as_ref().map_or("", |d| d.drop_types.as_str())
1351    }
1352
1353    fn drag_decl(&mut self) -> &mut DragDecl {
1354        self.drag.get_or_insert_with(Default::default)
1355    }
1356
1357    pub fn can_focus(&self) -> bool {
1358        self.can_focus
1359    }
1360
1361    /// Participa da navegação com Tab (como `TabStop`).
1362    pub fn tab_stop(&self) -> bool {
1363        self.tab_stop
1364    }
1365
1366    /// Menu de contexto do controle.
1367    pub fn popup_menu(&self) -> Option<ComponentId> {
1368        self.popup_menu
1369    }
1370
1371    pub fn set_popup_menu(&mut self, menu: Option<ComponentId>) -> &mut Self {
1372        self.popup_menu = menu;
1373        self
1374    }
1375
1376    /// Ver [`set_pan_on_touch`](Self::set_pan_on_touch).
1377    pub fn pan_on_touch(&self) -> bool {
1378        self.pan_on_touch
1379    }
1380
1381    /// Cursor do mouse sobre o controle. `Default` herda o do pai.
1382    pub fn cursor(&self) -> CursorShape {
1383        self.cursor
1384    }
1385
1386    pub fn opacity(&self) -> f32 {
1387        self.opacity
1388    }
1389
1390    /// Como o controle se junta ao que está por baixo (veja o campo).
1391    pub fn blend_mode(&self) -> crate::BlendMode {
1392        self.blend_mode
1393    }
1394
1395    pub fn set_blend_mode(&mut self, mode: crate::BlendMode) -> &mut Self {
1396        self.blend_mode = mode;
1397        self
1398    }
1399
1400    /// O desenho guardado numa imagem (veja o campo).
1401    pub fn cache_layer(&self) -> bool {
1402        self.cache_layer
1403    }
1404
1405    pub fn set_cache_layer(&mut self, on: bool) -> &mut Self {
1406        self.cache_layer = on;
1407        self
1408    }
1409
1410    /// Giro em graus, em torno do centro. Só a pintura gira; o clique usa o retângulo
1411    /// sem giro.
1412    pub fn rotation(&self) -> f32 {
1413        self.rotation
1414    }
1415
1416    /// A escala dele e de tudo dentro dele ([`set_scale`](Self::set_scale); 1 = normal).
1417    pub fn scale(&self) -> f32 {
1418        self.scale
1419    }
1420
1421    /// O tamanho do espaço de dentro: o do retângulo dividido pela escala. É nele que o
1422    /// controle se desenha (`PaintCtx::rect`) e que os filhos são arrumados.
1423    pub fn inner_size(&self) -> SizeF {
1424        let s = self.scale;
1425        if s == 1.0 { self.bounds.size() } else { SizeF::new(self.bounds.width / s, self.bounds.height / s) }
1426    }
1427
1428    pub fn shadow(&self) -> Option<crate::canvas::Shadow> {
1429        self.shadow
1430    }
1431
1432    /// Proporção fixa (largura ÷ altura); 0 = livre. No layout, a altura sai da largura
1433    /// (Top, Bottom, Horizontal, None), a largura sai da altura (Left, Right, Vertical) ou
1434    /// o controle cabe na área mantendo a proporção (Client, Center).
1435    pub fn aspect_ratio(&self) -> f32 {
1436        self.aspect_ratio
1437    }
1438
1439    pub fn set_aspect_ratio(&mut self, ratio: f32) -> &mut Self {
1440        self.aspect_ratio = if ratio.is_finite() { ratio.max(0.0) } else { 0.0 };
1441        self
1442    }
1443
1444    /// Largura máxima (0 = sem limite). O controle não passa dela; alinhado em cima, embaixo ou
1445    /// no cliente, fica no meio da área (o conteúdo de uma página que não se espalha numa tela
1446    /// larga). No form, é a largura máxima da janela.
1447    pub fn max_width(&self) -> f32 {
1448        self.max_width
1449    }
1450
1451    pub fn set_max_width(&mut self, width: f32) -> &mut Self {
1452        self.max_width = if width.is_finite() { width.max(0.0) } else { 0.0 };
1453        self
1454    }
1455
1456    /// Largura mínima (0 = sem limite). O layout não deixa o controle mais estreito que ela,
1457    /// mesmo alinhado (`top`, `client`...): o que passar da área do pai fica cortado (ou rola,
1458    /// num ScrollBox), e um texto com `wrap` para de quebrar nessa largura. No form, é a
1459    /// largura mínima da janela.
1460    pub fn min_width(&self) -> f32 {
1461        self.min_width
1462    }
1463
1464    pub fn set_min_width(&mut self, width: f32) -> &mut Self {
1465        self.min_width = if width.is_finite() { width.max(0.0) } else { 0.0 };
1466        self
1467    }
1468
1469    /// Altura mínima (0 = sem limite), como a [`min_width`](Self::min_width).
1470    pub fn min_height(&self) -> f32 {
1471        self.min_height
1472    }
1473
1474    pub fn set_min_height(&mut self, height: f32) -> &mut Self {
1475        self.min_height = if height.is_finite() { height.max(0.0) } else { 0.0 };
1476        self
1477    }
1478
1479    /// Altura máxima (0 = sem limite). No form, é a altura máxima da janela.
1480    pub fn max_height(&self) -> f32 {
1481        self.max_height
1482    }
1483
1484    pub fn set_max_height(&mut self, height: f32) -> &mut Self {
1485        self.max_height = if height.is_finite() { height.max(0.0) } else { 0.0 };
1486        self
1487    }
1488
1489    /// A largura que o controle ocupa numa faixa de `available` (com a `max_width` e a
1490    /// `min_width`; a mínima vence).
1491    pub fn clamp_width(&self, available: f32) -> f32 {
1492        let w = if self.max_width > 0.0 { available.min(self.max_width) } else { available };
1493        w.max(self.min_width)
1494    }
1495
1496    /// A altura dentro da `min_height` e da `max_height` (a mínima vence).
1497    pub fn clamp_height(&self, height: f32) -> f32 {
1498        let h = if self.max_height > 0.0 { height.min(self.max_height) } else { height };
1499        h.max(self.min_height)
1500    }
1501
1502    /// Encaixado, estica na faixa (`stretch`) ou fica com o próprio tamanho no começo, no
1503    /// meio ou no fim: veja [`SelfAlign`].
1504    pub fn self_align(&self) -> SelfAlign {
1505        self.self_align
1506    }
1507
1508    pub fn set_self_align(&mut self, align: SelfAlign) -> &mut Self {
1509        self.self_align = align;
1510        self
1511    }
1512
1513    /// A largura numa faixa horizontal de `available` (encaixado em cima ou embaixo): a faixa
1514    /// toda ou, com `self_align`, a própria `width`; com `self_align` e `max_width`, a faixa até
1515    /// a máxima (o `width: 100%; max-width` do CSS). Sempre dentro dos limites.
1516    pub fn band_width(&self, available: f32) -> f32 {
1517        match self.self_align {
1518            SelfAlign::Stretch => self.clamp_width(available),
1519            _ if self.max_width > 0.0 => self.clamp_width(available),
1520            _ => self.clamp_width(self.width),
1521        }
1522    }
1523
1524    /// A altura numa faixa vertical de `available` (encaixado à esquerda ou à direita), como a
1525    /// [`band_width`](Self::band_width).
1526    pub fn band_height(&self, available: f32) -> f32 {
1527        match self.self_align {
1528            SelfAlign::Stretch => self.clamp_height(available),
1529            _ if self.max_height > 0.0 => self.clamp_height(available),
1530            _ => self.clamp_height(self.height),
1531        }
1532    }
1533
1534    /// Onde começa um tamanho `size` numa faixa de `available`: no começo, no meio (o
1535    /// `stretch` com a largura máxima sobrando) ou no fim. Passando da faixa, no começo.
1536    pub fn band_offset(&self, available: f32, size: f32) -> f32 {
1537        let spare = (available - size).max(0.0);
1538        match self.self_align {
1539            SelfAlign::Start => 0.0,
1540            SelfAlign::End => spare,
1541            SelfAlign::Stretch | SelfAlign::Center => spare / 2.0,
1542        }
1543    }
1544
1545    /// A altura sai do conteúdo, na largura que o controle tem:
1546    /// um Label com `wrap` fica da altura do texto quebrado; um contêiner, da
1547    /// altura dos filhos encaixados em cima e embaixo (mais o padding). Vale com `align`
1548    /// `top`, `bottom` ou `none`.
1549    pub fn auto_size(&self) -> bool {
1550        self.auto_size
1551    }
1552
1553    pub fn set_auto_size(&mut self, on: bool) -> &mut Self {
1554        self.auto_size = on;
1555        self
1556    }
1557
1558    /// Quantas colunas ocupa num `GridLayout` (pelo menos 1; numa grade com menos colunas,
1559    /// ocupa a linha inteira).
1560    pub fn column_span(&self) -> u32 {
1561        self.column_span.max(1)
1562    }
1563
1564    /// O lugar fixo na grade: (linha, coluna), ou `None` (segue a ordem dos filhos).
1565    pub fn grid_cell(&self) -> Option<(u32, u32)> {
1566        (self.grid_row >= 0 && self.grid_column >= 0).then(|| (self.grid_row as u32, self.grid_column as u32))
1567    }
1568
1569    pub fn set_grid_cell(&mut self, cell: Option<(u32, u32)>) -> &mut Self {
1570        let (r, c) = cell.map_or((-1, -1), |(r, c)| (r.min(i16::MAX as u32) as i16, c.min(i16::MAX as u32) as i16));
1571        self.grid_row = r;
1572        self.grid_column = c;
1573        self
1574    }
1575
1576    /// Quantas linhas ocupa num `GridLayout` (o `rowspan`).
1577    pub fn row_span(&self) -> u32 {
1578        u32::from(self.row_span.max(1))
1579    }
1580
1581    pub fn set_row_span(&mut self, span: u32) -> &mut Self {
1582        self.row_span = span.clamp(1, 64) as u16;
1583        self
1584    }
1585
1586    pub fn grow(&self) -> f32 {
1587        self.grow
1588    }
1589
1590    pub fn set_grow(&mut self, grow: f32) -> &mut Self {
1591        self.grow = grow.max(0.0);
1592        self
1593    }
1594
1595    pub fn set_column_span(&mut self, span: u32) -> &mut Self {
1596        self.column_span = span.max(1);
1597        self
1598    }
1599
1600    /// A escala de fonte da vista ativa do form (1 sem vista).
1601    pub fn text_scale(&self) -> f32 {
1602        self.text_scale
1603    }
1604
1605    /// A escala de espaços da vista ativa do form (1 sem vista).
1606    pub fn spacing_scale(&self) -> f32 {
1607        self.spacing_scale
1608    }
1609
1610    pub fn tag(&self) -> i64 {
1611        self.tag
1612    }
1613
1614    /// O nome que o leitor de tela fala (o `aria-label`), no lugar do texto do controle: um
1615    /// botão só com ícone, um campo sem rótulo. O relatório do Tabernáculo, C29.
1616    pub fn accessible_name(&self) -> &str {
1617        self.rare.as_ref().map_or("", |r| &r.accessible_name)
1618    }
1619
1620    pub fn set_accessible_name(&mut self, v: &str) -> &mut Self {
1621        self.rare_mut(|r| r.accessible_name = v.into());
1622        self
1623    }
1624
1625    fn rare_mut(&mut self, change: impl FnOnce(&mut RareTexts)) {
1626        let rare = self.rare.get_or_insert_with(Default::default);
1627        change(rare);
1628        if rare.tag_string.is_empty() && rare.accessible_name.is_empty() {
1629            self.rare = None;
1630        }
1631    }
1632
1633    pub fn tag_string(&self) -> &str {
1634        self.rare.as_ref().map_or("", |r| &r.tag_string)
1635    }
1636
1637    /// Variante de estilo do tema ("primary", "danger", "flat"...). Vazio = estilo da classe.
1638    pub fn style(&self) -> &str {
1639        &self.style
1640    }
1641
1642    /// Tema próprio do controle (e dos filhos), pelo nome. Vazio = o do pai.
1643    pub fn theme_name(&self) -> &str {
1644        &self.theme
1645    }
1646
1647    pub fn set_theme_name(&mut self, v: impl Into<String>) -> &mut Self {
1648        self.theme = v.into();
1649        self
1650    }
1651
1652    /// Dica (balão) mostrada com o mouse parado sobre o controle. Vazio = a do pai.
1653    pub fn hint(&self) -> &str {
1654        &self.hint
1655    }
1656
1657    pub fn set_hint(&mut self, v: impl Into<String>) -> &mut Self {
1658        self.hint = v.into();
1659        self
1660    }
1661
1662    pub fn state(&self) -> ControlState {
1663        self.state
1664    }
1665
1666    /// Posição e tamanho reais, relativos ao pai, calculados pelo layout.
1667    pub fn bounds(&self) -> RectF {
1668        self.bounds
1669    }
1670
1671    /// Quanto o conteúdo está rolado: os filhos são deslocados por este valor.
1672    pub fn scroll_offset(&self) -> PointF {
1673        self.scroll_offset
1674    }
1675
1676    /// A rolagem com que o último layout pôs os filhos ([`scroll_offset`](Self::scroll_offset)
1677    /// muda na hora; esta, no layout): somada à posição de um filho, dá onde ele está no conteúdo.
1678    pub fn laid_out_scroll(&self) -> PointF {
1679        self.laid_out_scroll
1680    }
1681
1682    /// Rola o conteúdo. Chame `invalidate` (ou mude por `ui.control_mut`) para refazer o
1683    /// layout.
1684    pub fn set_scroll_offset(&mut self, offset: PointF) -> &mut Self {
1685        self.scroll_offset = offset;
1686        self
1687    }
1688
1689    /// Tamanho ocupado pelos filhos visíveis (com margens e padding), calculado no
1690    /// layout. Serve para saber até onde rolar.
1691    pub fn content_size(&self) -> SizeF {
1692        self.content_size
1693    }
1694
1695    // ----- escrita (encadeável) -----
1696
1697    // A posição e o tamanho pedidos mudaram: as âncoras medem de novo a partir daqui. Só quando
1698    // o valor muda de fato: regravar o mesmo valor a cada arrumação (o `auto_size`) refazia a
1699    // referência sempre, e o controle ancorado nunca acompanhava o pai (relatório do InsightDB,
1700    // 11/11: nem a célula do GridLayout, nem a janela em tela cheia).
1701    pub fn set_left(&mut self, v: f32) -> &mut Self {
1702        if self.left != v {
1703            self.left = v;
1704            self.anchor_ref = None;
1705        }
1706        self
1707    }
1708
1709    pub fn set_top(&mut self, v: f32) -> &mut Self {
1710        if self.top != v {
1711            self.top = v;
1712            self.anchor_ref = None;
1713        }
1714        self
1715    }
1716
1717    pub fn set_position(&mut self, left: f32, top: f32) -> &mut Self {
1718        self.set_left(left).set_top(top)
1719    }
1720
1721    pub fn set_width(&mut self, v: f32) -> &mut Self {
1722        if self.width != v.max(0.0) {
1723            self.width = v.max(0.0);
1724            self.anchor_ref = None;
1725        }
1726        self
1727    }
1728
1729    pub fn set_height(&mut self, v: f32) -> &mut Self {
1730        if self.height != v.max(0.0) {
1731            self.height = v.max(0.0);
1732            self.anchor_ref = None;
1733        }
1734        self
1735    }
1736
1737    /// A largura que o próprio layout mede (o `auto_size`), como [`set_measured_height`].
1738    pub(crate) fn set_measured_width(&mut self, v: f32) {
1739        self.width = v.max(0.0);
1740        if let Some(r) = self.anchor_ref.as_mut() {
1741            r.rect.width = self.width;
1742        }
1743    }
1744
1745    /// A altura que o próprio layout mede (o `auto_size`): muda o tamanho sem perder a
1746    /// referência das âncoras (a altura guardada nela acompanha).
1747    pub(crate) fn set_measured_height(&mut self, v: f32) {
1748        self.height = v.max(0.0);
1749        if let Some(r) = self.anchor_ref.as_mut() {
1750            r.rect.height = self.height;
1751        }
1752    }
1753
1754    pub fn set_size(&mut self, width: f32, height: f32) -> &mut Self {
1755        self.set_width(width).set_height(height)
1756    }
1757
1758    /// Define posição e tamanho de uma vez.
1759    pub fn set_rect(&mut self, left: f32, top: f32, width: f32, height: f32) -> &mut Self {
1760        self.set_position(left, top).set_size(width, height)
1761    }
1762
1763    pub fn set_margins(&mut self, v: impl Into<Bounds>) -> &mut Self {
1764        self.margins = v.into();
1765        self
1766    }
1767
1768    pub fn set_padding(&mut self, v: impl Into<Bounds>) -> &mut Self {
1769        self.padding = v.into();
1770        self
1771    }
1772
1773    pub fn set_align(&mut self, v: Align) -> &mut Self {
1774        self.align = v;
1775        self.anchor_ref = None;
1776        self
1777    }
1778
1779    pub fn set_anchors(&mut self, v: Anchors) -> &mut Self {
1780        self.anchors = v;
1781        self.anchor_ref = None;
1782        self
1783    }
1784
1785    pub fn set_visible(&mut self, v: bool) -> &mut Self {
1786        self.visible = v;
1787        self
1788    }
1789
1790    pub fn set_enabled(&mut self, v: bool) -> &mut Self {
1791        self.enabled = v;
1792        self
1793    }
1794
1795    pub fn set_hit_test(&mut self, v: bool) -> &mut Self {
1796        self.hit_test = v;
1797        self
1798    }
1799
1800    pub fn set_clip_children(&mut self, v: bool) -> &mut Self {
1801        self.clip_children = v;
1802        self
1803    }
1804
1805    pub fn set_captures_wheel(&mut self, v: bool) -> &mut Self {
1806        self.captures_wheel = v;
1807        self
1808    }
1809
1810    pub fn set_can_focus(&mut self, v: bool) -> &mut Self {
1811        self.can_focus = v;
1812        self
1813    }
1814
1815    /// Arrastar o dedo sobre o controle rola o conteúdo (vira roda para o ScrollBox ou o
1816    /// DataGrid de baixo). Ligado por padrão; controles que precisam do arrasto em si (um
1817    /// Splitter, um designer) desligam.
1818    pub fn set_pan_on_touch(&mut self, v: bool) -> &mut Self {
1819        self.pan_on_touch = v;
1820        self
1821    }
1822
1823    pub fn set_tab_stop(&mut self, v: bool) -> &mut Self {
1824        self.tab_stop = v;
1825        self
1826    }
1827
1828    pub fn set_cursor(&mut self, v: CursorShape) -> &mut Self {
1829        self.cursor = v;
1830        self
1831    }
1832
1833    pub fn set_opacity(&mut self, v: f32) -> &mut Self {
1834        self.opacity = v.clamp(0.0, 1.0);
1835        self
1836    }
1837
1838    /// Deslocamento do desenho (sem mexer no layout).
1839    pub fn translate(&self) -> PointF {
1840        self.translate
1841    }
1842
1843    pub fn set_translate(&mut self, offset: PointF) -> &mut Self {
1844        self.translate = if offset.x.is_finite() && offset.y.is_finite() { offset } else { PointF::ZERO };
1845        self
1846    }
1847
1848    /// A escala dele e dos filhos (1 = normal; de 0,05 a 20).
1849    pub fn set_scale(&mut self, scale: f32) -> &mut Self {
1850        self.scale = if scale.is_finite() && scale > 0.0 { scale.clamp(0.05, 20.0) } else { 1.0 };
1851        self
1852    }
1853
1854    pub fn set_rotation(&mut self, degrees: f32) -> &mut Self {
1855        self.rotation = if degrees.is_finite() { degrees % 360.0 } else { 0.0 };
1856        self
1857    }
1858
1859    pub fn set_shadow(&mut self, shadow: Option<crate::canvas::Shadow>) -> &mut Self {
1860        self.shadow = shadow;
1861        self
1862    }
1863
1864    pub fn set_tag(&mut self, v: i64) -> &mut Self {
1865        self.tag = v;
1866        self
1867    }
1868
1869    pub fn set_tag_string(&mut self, v: &str) -> &mut Self {
1870        self.rare_mut(|r| r.tag_string = v.into());
1871        self
1872    }
1873
1874    pub fn set_style(&mut self, v: impl Into<String>) -> &mut Self {
1875        self.style = v.into();
1876        self
1877    }
1878
1879    /// Estado visual (hover, pressed...). Normalmente quem altera é o despacho de eventos;
1880    /// controles como CheckBox alteram `checked`.
1881    pub fn state_mut(&mut self) -> &mut ControlState {
1882        &mut self.state
1883    }
1884
1885    // ----- propriedades por nome -----
1886
1887    pub fn get_prop(&self, name: &str) -> Option<PropValue> {
1888        Some(match name {
1889            "left" => self.left.into(),
1890            "top" => self.top.into(),
1891            "width" => self.width.into(),
1892            "height" => self.height.into(),
1893            "align" => self.align.into(),
1894            "anchors" => self.anchors.into(),
1895            "margins" => self.margins.into(),
1896            "padding" => self.padding.into(),
1897            "visible" => self.visible.into(),
1898            "enabled" => self.enabled.into(),
1899            "hit_test" => self.hit_test.into(),
1900            "clip_children" => self.clip_children.into(),
1901            "inherit_state" => self.inherit_state.into(),
1902            "translate" => self.translatable.into(),
1903            "captures_wheel" => self.captures_wheel.into(),
1904            "can_focus" => self.can_focus.into(),
1905            "draggable" => self.draggable.into(),
1906            "accepts_drops" => self.accepts_drops.into(),
1907            "drag_data" => self.drag_data().into(),
1908            "drag_label" => self.drag_label().into(),
1909            "drag_image" => PropValue::Component(self.drag_image()),
1910            "drop_types" => self.drop_types().into(),
1911            "tab_stop" => self.tab_stop.into(),
1912            "cursor" => PropValue::enum_value(self.cursor),
1913            "opacity" => self.opacity.into(),
1914            "blend_mode" => PropValue::enum_value(self.blend_mode),
1915            "cache_layer" => self.cache_layer.into(),
1916            "rotation" => self.rotation.into(),
1917            "scale" => self.scale.into(),
1918            "translate_x" => self.translate.x.into(),
1919            "translate_y" => self.translate.y.into(),
1920            "aspect_ratio" => self.aspect_ratio.into(),
1921            "max_width" => self.max_width.into(),
1922            "min_width" => self.min_width.into(),
1923            "min_height" => self.min_height.into(),
1924            "max_height" => self.max_height.into(),
1925            "self_align" => PropValue::enum_value(self.self_align),
1926            "auto_size" => self.auto_size.into(),
1927            "column_span" => (self.column_span() as i64).into(),
1928            "grid_row" => i64::from(self.grid_row).into(),
1929            "grid_column" => i64::from(self.grid_column).into(),
1930            "row_span" => (self.row_span() as i64).into(),
1931            "grow" => f64::from(self.grow).into(),
1932            "shadow" => crate::prop::PropType::to_value(&self.shadow),
1933            "style" => self.style.clone().into(),
1934            "fill" => crate::prop::PropType::to_value(&self.colors.fill),
1935            "border_color" => crate::prop::PropType::to_value(&self.colors.border),
1936            "text_color" => crate::prop::PropType::to_value(&self.colors.text),
1937            "accent_color" => crate::prop::PropType::to_value(&self.colors.accent),
1938            "success_color" => crate::prop::PropType::to_value(&self.colors.success),
1939            "warning_color" => crate::prop::PropType::to_value(&self.colors.warning),
1940            "danger_color" => crate::prop::PropType::to_value(&self.colors.danger),
1941            "font_family" => self.font.family.clone().into(),
1942            "font_size" => crate::prop::PropType::to_value(&self.font.size),
1943            "font_weight" => PropValue::Enum(FONT_WEIGHTS[self.font.weight.map_or(0, |w| w as usize + 1)].into()),
1944            "font_italic" => self.font.italic.into(),
1945            "font_underline" => self.font.underline.into(),
1946            "font_strikeout" => self.font.strikeout.into(),
1947            "theme" => self.theme.clone().into(),
1948            "hint" => self.hint.clone().into(),
1949            "tag" => self.tag.into(),
1950            "tag_string" => self.tag_string().to_string().into(),
1951            "accessible_name" => self.accessible_name().to_string().into(),
1952            "popup_menu" => PropValue::Component(self.popup_menu),
1953            _ => return None,
1954        })
1955    }
1956
1957    pub fn set_prop(&mut self, name: &str, value: PropValue) -> Result<()> {
1958        match name {
1959            "left" => self.set_left(value.to_f32()?),
1960            "top" => self.set_top(value.to_f32()?),
1961            "width" => self.set_width(value.to_f32()?),
1962            "height" => self.set_height(value.to_f32()?),
1963            "align" => self.set_align(value.to_enum()?),
1964            "anchors" => self.set_anchors(value.to_anchors()?),
1965            "margins" => self.set_margins(value.to_bounds()?),
1966            "padding" => self.set_padding(value.to_bounds()?),
1967            "visible" => self.set_visible(value.to_bool()?),
1968            "enabled" => self.set_enabled(value.to_bool()?),
1969            "hit_test" => self.set_hit_test(value.to_bool()?),
1970            "clip_children" => self.set_clip_children(value.to_bool()?),
1971            "inherit_state" => self.set_inherit_state(value.to_bool()?),
1972            "translate" => self.set_translatable(value.to_bool()?),
1973            "captures_wheel" => self.set_captures_wheel(value.to_bool()?),
1974            "can_focus" => self.set_can_focus(value.to_bool()?),
1975            "draggable" => self.set_draggable(value.to_bool()?),
1976            "accepts_drops" => self.set_accepts_drops(value.to_bool()?),
1977            "drag_data" => {
1978                self.drag_decl().data = value.to_str()?.to_string();
1979                self
1980            }
1981            "drag_label" => {
1982                self.drag_decl().label = value.to_str()?.to_string();
1983                self
1984            }
1985            "drag_image" => {
1986                self.drag_decl().image = value.to_component()?;
1987                self
1988            }
1989            "drop_types" => {
1990                self.drag_decl().drop_types = value.to_str()?.to_string();
1991                self
1992            }
1993            "tab_stop" => self.set_tab_stop(value.to_bool()?),
1994            "cursor" => self.set_cursor(value.to_enum()?),
1995            "opacity" => self.set_opacity(value.to_f32()?),
1996            "blend_mode" => self.set_blend_mode(value.to_enum()?),
1997            "cache_layer" => self.set_cache_layer(value.to_bool()?),
1998            "rotation" => self.set_rotation(value.to_f32()?),
1999            "scale" => self.set_scale(value.to_f32()?),
2000            "translate_x" => self.set_translate(PointF::new(value.to_f32()?, self.translate.y)),
2001            "translate_y" => self.set_translate(PointF::new(self.translate.x, value.to_f32()?)),
2002            "aspect_ratio" => self.set_aspect_ratio(value.to_f32()?),
2003            "max_width" => self.set_max_width(value.to_f32()?),
2004            "min_width" => self.set_min_width(value.to_f32()?),
2005            "min_height" => self.set_min_height(value.to_f32()?),
2006            "max_height" => self.set_max_height(value.to_f32()?),
2007            "self_align" => self.set_self_align(value.to_enum()?),
2008            "auto_size" => self.set_auto_size(value.to_bool()?),
2009            "column_span" => self.set_column_span(value.to_f64()?.clamp(1.0, 64.0) as u32),
2010            "grid_row" => {
2011                self.grid_row = value.to_f64()?.clamp(-1.0, 4096.0) as i16;
2012                self
2013            }
2014            "grid_column" => {
2015                self.grid_column = value.to_f64()?.clamp(-1.0, 4096.0) as i16;
2016                self
2017            }
2018            "row_span" => self.set_row_span(value.to_f64()?.clamp(1.0, 64.0) as u32),
2019            "grow" => self.set_grow(value.to_f32()?),
2020            "shadow" => self.set_shadow(crate::prop::PropType::from_value(value)?),
2021            "style" => self.set_style(value.to_str()?),
2022            "fill" => {
2023                self.colors.fill = crate::prop::PropType::from_value(value)?;
2024                self
2025            }
2026            "border_color" => {
2027                self.colors.border = crate::prop::PropType::from_value(value)?;
2028                self
2029            }
2030            "text_color" => {
2031                self.colors.text = crate::prop::PropType::from_value(value)?;
2032                self
2033            }
2034            "accent_color" => {
2035                self.colors.accent = crate::prop::PropType::from_value(value)?;
2036                self
2037            }
2038            "success_color" => {
2039                self.colors.success = crate::prop::PropType::from_value(value)?;
2040                self
2041            }
2042            "warning_color" => {
2043                self.colors.warning = crate::prop::PropType::from_value(value)?;
2044                self
2045            }
2046            "danger_color" => {
2047                self.colors.danger = crate::prop::PropType::from_value(value)?;
2048                self
2049            }
2050            "font_family" => {
2051                self.font.family = value.to_str()?.to_string();
2052                self
2053            }
2054            "font_size" => {
2055                self.font.size = crate::prop::PropType::from_value(value)?;
2056                self
2057            }
2058            "font_weight" => {
2059                self.font.weight = font_weight_named(value.to_str()?)?;
2060                self
2061            }
2062            "font_italic" => {
2063                self.font.italic = value.to_bool()?;
2064                self
2065            }
2066            "font_underline" => {
2067                self.font.underline = value.to_bool()?;
2068                self
2069            }
2070            "font_strikeout" => {
2071                self.font.strikeout = value.to_bool()?;
2072                self
2073            }
2074            "theme" => self.set_theme_name(value.to_str()?),
2075            "hint" => self.set_hint(value.to_str()?),
2076            "tag" => self.set_tag(value.to_i64()?),
2077            "tag_string" => self.set_tag_string(value.to_str()?),
2078            "accessible_name" => self.set_accessible_name(value.to_str()?),
2079            "popup_menu" => {
2080                self.popup_menu = value.to_component()?;
2081                self
2082            }
2083            _ => return Err(Error::UnknownProperty(name.to_string())),
2084        };
2085        Ok(())
2086    }
2087}
2088
2089/// Os pesos da propriedade `font_weight`; `default` é o do pai (ou do tema).
2090pub const FONT_WEIGHTS: [&str; 8] = ["default", "thin", "light", "normal", "medium", "semibold", "bold", "black"];
2091
2092fn font_weight_named(name: &str) -> Result<Option<crate::canvas::FontWeight>> {
2093    use crate::canvas::FontWeight::*;
2094    let all = [Thin, Light, Normal, Medium, SemiBold, Bold, Black];
2095    match FONT_WEIGHTS.iter().position(|n| n.eq_ignore_ascii_case(name)) {
2096        Some(0) => Ok(None),
2097        Some(i) => Ok(Some(all[i - 1])),
2098        None => Err(Error::invalid(format!("valor '{name}' inválido; use um de: {}", FONT_WEIGHTS.join(", ")))),
2099    }
2100}
2101
2102/// A fonte de um controle por cima da do tema: família, tamanho,
2103/// peso, itálico, sublinhado e tachado. O que não tem valor vem do pai:
2104/// a fonte posta no form vale para tudo dentro dele.
2105#[derive(Clone, Debug, Default, PartialEq)]
2106pub struct FontOverride {
2107    /// A família da fonte (`"Segoe UI"`, `"monospace"`); vazio: a do pai.
2108    pub family: String,
2109    /// O tamanho da fonte, em pontos; sem valor: o do pai.
2110    pub size: Option<f32>,
2111    /// O peso da fonte (`normal`, `bold`...); sem valor: o do pai.
2112    pub weight: Option<crate::canvas::FontWeight>,
2113    /// Itálico; ligado vale também para os filhos.
2114    pub italic: bool,
2115    /// Sublinhado; ligado vale também para os filhos.
2116    pub underline: bool,
2117    /// Tachado (uma linha no meio do texto); ligado vale também para os filhos.
2118    pub strikeout: bool,
2119}
2120
2121impl FontOverride {
2122    pub fn is_empty(&self) -> bool {
2123        *self == Self::default()
2124    }
2125
2126    /// Esta fonte com o que faltar vindo de `parent`.
2127    pub fn over(&self, parent: &FontOverride) -> FontOverride {
2128        FontOverride {
2129            family: if self.family.is_empty() { parent.family.clone() } else { self.family.clone() },
2130            size: self.size.or(parent.size),
2131            weight: self.weight.or(parent.weight),
2132            italic: self.italic || parent.italic,
2133            underline: self.underline || parent.underline,
2134            strikeout: self.strikeout || parent.strikeout,
2135        }
2136    }
2137
2138    /// Aplica na fonte do estilo (a do tema).
2139    pub fn apply(&self, font: &mut crate::canvas::FontSpec) {
2140        if !self.family.is_empty() {
2141            font.family = self.family.clone();
2142        }
2143        if let Some(size) = self.size.filter(|s| *s > 0.0) {
2144            font.size = size;
2145        }
2146        if let Some(weight) = self.weight {
2147            font.weight = weight;
2148        }
2149        font.italic |= self.italic;
2150        font.underline |= self.underline;
2151        font.strikeout |= self.strikeout;
2152    }
2153}
2154
2155impl ControlBase {
2156    /// A fonte própria do controle (sem a herdada).
2157    pub fn font(&self) -> &FontOverride {
2158        &self.font
2159    }
2160
2161    pub fn set_font(&mut self, font: FontOverride) -> &mut Self {
2162        self.font = font;
2163        self
2164    }
2165}
2166
2167/// As cores próprias de um controle (vazio = as do tema):
2168/// valem para qualquer controle (`fill`, `border_color`, `text_color`, `accent_color` e as de
2169/// sentido: `success_color`, `warning_color`, `danger_color`).
2170/// O `Ui` as põe no estilo resolvido e no tema que o controle vê (`primary` e as variações,
2171/// `text`, `border`), então até os controles que leem o tema direto as seguem.
2172#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)]
2173pub struct ColorOverride {
2174    /// A cor do fundo; vazio: a do tema.
2175    pub fill: Option<crate::Color>,
2176    /// A cor da borda; vazio: a do tema.
2177    pub border: Option<crate::Color>,
2178    /// A cor do texto; vazio: a do tema.
2179    pub text: Option<crate::Color>,
2180    /// O destaque: a marca da caixa de seleção, a barra do progresso, o trilho preenchido,
2181    /// a seleção, o foco.
2182    pub accent: Option<crate::Color>,
2183    /// As cores de sentido: subir/positivo, atenção e cair/erro (candles, variações, avisos).
2184    /// Esta é a de subir/positivo; vazio: a do tema.
2185    pub success: Option<crate::Color>,
2186    /// A cor de sentido de atenção (avisos); vazio: a do tema.
2187    pub warning: Option<crate::Color>,
2188    /// A cor de sentido de cair/erro (candles em queda, variações negativas, erros); vazio: a do tema.
2189    pub danger: Option<crate::Color>,
2190}
2191
2192impl ColorOverride {
2193    pub fn is_empty(&self) -> bool {
2194        *self == Self::default()
2195    }
2196
2197    /// Muda alguma cor do tema (não só o estilo).
2198    pub(crate) fn recolors_theme(&self) -> bool {
2199        !self.is_empty()
2200    }
2201
2202    /// O tema com as cores próprias por cima.
2203    pub(crate) fn apply_theme(&self, theme: &crate::Theme) -> crate::Theme {
2204        use crate::Color;
2205        let mut t = theme.clone();
2206        let mut set = |name: &str, c: Color| {
2207            t.colors.insert(name.to_string(), c);
2208        };
2209        if let Some(a) = self.accent {
2210            let dark = luminance(a) < 0.5;
2211            set("primary", a);
2212            set("primary_hover", a.lerp(if dark { Color::WHITE } else { Color::BLACK }, 0.12));
2213            set("primary_pressed", a.lerp(if dark { Color::BLACK } else { Color::BLACK }, 0.15));
2214            set("on_primary", if luminance(a) < 0.6 { Color::WHITE } else { Color::BLACK });
2215            set("focus_ring", a);
2216            set("selection", a.with_opacity(0.25));
2217            set("primary_soft", a.with_opacity(0.1));
2218            set("primary_container", a.lerp(Color::WHITE, 0.82));
2219        }
2220        if let Some(c) = self.fill {
2221            // O fundo: o da superfície e o das áreas de dentro (um pouco mais escuro ou claro).
2222            let toward = if luminance(c) < 0.5 { Color::WHITE } else { Color::BLACK };
2223            set("surface", c);
2224            set("background", c);
2225            set("surface_2", c.lerp(toward.with_opacity(c.a as f32 / 255.0), 0.06));
2226        }
2227        if let Some(c) = self.text {
2228            set("text", c);
2229            set("text_muted", c.with_opacity(0.65));
2230            for on in ["on_primary", "on_danger", "on_success", "on_primary_container"] {
2231                set(on, c);
2232            }
2233        }
2234        if let Some(c) = self.border {
2235            set("border", c);
2236            set("track", c);
2237        }
2238        for (token, color) in [("success", self.success), ("warning", self.warning), ("danger", self.danger)] {
2239            if let Some(c) = color {
2240                set(token, c);
2241                set(&format!("{token}_soft"), c.with_opacity(0.1));
2242                set(&format!("{token}_hover"), c.lerp(Color::WHITE, 0.12));
2243                set(&format!("{token}_pressed"), c.lerp(Color::BLACK, 0.15));
2244                if token == "success" {
2245                    set("meter_low", c);
2246                } else if token == "danger" {
2247                    set("meter_high", c);
2248                } else {
2249                    set("meter_mid", c);
2250                }
2251            }
2252        }
2253        t
2254    }
2255}
2256
2257/// Luminância relativa (0 escuro, 1 claro).
2258pub(crate) fn luminance(c: crate::Color) -> f32 {
2259    (0.299 * c.r as f32 + 0.587 * c.g as f32 + 0.114 * c.b as f32) / 255.0
2260}
2261
2262/// As duas pontas de um conector ([`Component::connection`]).
2263#[derive(Clone, Copy, Debug, PartialEq)]
2264pub struct Connection {
2265    pub from: ComponentId,
2266    /// O ponto de ligação em `from` (`(1, 0.5)`: o meio do lado direito).
2267    pub from_at: (f32, f32),
2268    pub to: ComponentId,
2269    pub to_at: (f32, f32),
2270}
2271
2272impl Connection {
2273    /// Quanto a ponta sai do componente antes da primeira dobra.
2274    pub const STUB: f32 = 16.0;
2275
2276    /// A direção para fora do lado onde está o ponto (`(1, 0.5)` → direita).
2277    fn normal(at: (f32, f32)) -> PointF {
2278        let (x, y) = at;
2279        let d = [(x, PointF::new(-1.0, 0.0)), (1.0 - x, PointF::new(1.0, 0.0)), (y, PointF::new(0.0, -1.0)), (1.0 - y, PointF::new(0.0, 1.0))];
2280        d.iter().min_by(|a, b| a.0.total_cmp(&b.0)).map_or(PointF::new(1.0, 0.0), |d| d.1)
2281    }
2282
2283    /// O caminho em ângulos retos entre os dois pontos (nas coordenadas do pai), dados os
2284    /// retângulos dos dois componentes.
2285    pub fn route(&self, from: RectF, to: RectF) -> Vec<PointF> {
2286        let p0 = PointF::new(from.x + from.width * self.from_at.0, from.y + from.height * self.from_at.1);
2287        let p1 = PointF::new(to.x + to.width * self.to_at.0, to.y + to.height * self.to_at.1);
2288        let (n0, n1) = (Self::normal(self.from_at), Self::normal(self.to_at));
2289        let s0 = PointF::new(p0.x + n0.x * Self::STUB, p0.y + n0.y * Self::STUB);
2290        let s1 = PointF::new(p1.x + n1.x * Self::STUB, p1.y + n1.y * Self::STUB);
2291        let mut points = vec![p0, s0];
2292        if n0.x != 0.0 {
2293            // Sai na horizontal: anda até o meio em x, desce/sobe, segue.
2294            let mx = (s0.x + s1.x) / 2.0;
2295            points.push(PointF::new(mx, s0.y));
2296            points.push(PointF::new(mx, s1.y));
2297        } else {
2298            let my = (s0.y + s1.y) / 2.0;
2299            points.push(PointF::new(s0.x, my));
2300            points.push(PointF::new(s1.x, my));
2301        }
2302        points.push(s1);
2303        points.push(p1);
2304        points.dedup_by(|a, b| (a.x - b.x).abs() < 0.01 && (a.y - b.y).abs() < 0.01);
2305        points
2306    }
2307}
2308
2309/// O arrasto declarado de um controle (fica fora do `ControlBase` comum: quase nenhum tem).
2310#[derive(Clone, Debug, Default, PartialEq)]
2311pub struct DragDecl {
2312    /// O que vai num arrasto que começa nele, sem handler (`"cliente:123"`: o tipo é o que vem
2313    /// antes do primeiro `:`); vazio: o arrasto declarado não leva nada.
2314    pub data: String,
2315    /// O texto que acompanha o mouse durante o arrasto; vazio: sem rótulo.
2316    pub label: String,
2317    /// Os tipos que este destino aceita, separados por `;` (`"cliente;produto"`); vazio: quem
2318    /// decide é o `on_drag_over`.
2319    pub drop_types: String,
2320    /// O `DragImage` que acompanha o cursor no arrasto (a imagem e o tamanho).
2321    pub image: Option<ComponentId>,
2322}
2323
2324/// Os textos raros do [`ControlBase`].
2325#[derive(Clone, Debug, Default)]
2326struct RareTexts {
2327    /// Um texto livre para o código (um id, um caminho, um JSON pequeno).
2328    tag_string: Box<str>,
2329    /// O nome que o leitor de tela fala, no lugar do texto do controle (um botão só com
2330    /// ícone, um campo sem rótulo); vazio: o texto do próprio controle.
2331    accessible_name: Box<str>,
2332}