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