Expand description
§aylis-core
Núcleo do aylis: modelo de componentes, árvore, propriedades publicadas, layout (Align, Anchors, Margins, Padding), temas e as interfaces (traits) com a plataforma.
Este crate não depende de nada do sistema operacional. Janela, input, timers e o
desenho de verdade ficam em crates de plataforma e de renderização, que implementam
os traits definidos aqui (Canvas, TextService, platform).
§Conceitos
| Conceito | No Aylis |
|---|---|
| Componente | qualquer tipo que implementa Component |
| Controle visual | um Component que tem um ControlBase |
| Estender um componente | composição: o componente guarda o “pai” e devolve em Component::inner |
| Criar e pôr num pai | Ui::add / Ui::create |
| Liberar | Ui::free (libera os filhos junto) |
| Achar pelo nome | Ui::find / Ui::find_in / Ui::find_path ("frmClientes.btnSalvar") |
| Nomes únicos por form | Ui::form_of: todo form é um escopo de nomes |
| Abrir, abrir modal e fechar | Ui::show / Ui::show_modal (resultado numa função) / Ui::close |
| Propriedade por nome | Ui::set_prop / Ui::get_prop |
| Ligar um evento | Ui::on_click / Ui::on ou por nome via Ui::register_handler |
Re-exports§
pub use align::Align;pub use align::Anchors;pub use align::SelfAlign;pub use i18n::tr;pub use i18n::tr_with;pub use anim::AnimationOptions;pub use anim::ColorAnimation;pub use anim::Easing;pub use anim::FloatAnimation;pub use anim::PropertyAnimation;pub use anim::Trigger;pub use canvas::BlendMode;pub use canvas::Brush;pub use canvas::Canvas;pub use canvas::FontSpec;pub use canvas::FontWeight;pub use canvas::GpuDevice;pub use canvas::GpuSurface;pub use canvas::GradientStop;pub use canvas::LineCap;pub use canvas::LineJoin;pub use canvas::Shadow;pub use canvas::Stroke;pub use canvas::TextAlign;pub use canvas::TextService;pub use canvas::TextStyle;pub use canvas::decorate_line;pub use color::Color;pub use component::ArrangeItem;pub use component::ChildPointer;pub use component::ClipShape;pub use component::ColorOverride;pub use component::Component;pub use component::ComponentId;pub use component::Connection;pub use component::ControlBase;pub use component::ControlState;pub use component::DesignHooks;pub use component::DragDrop;pub use component::LayoutHooks;pub use component::Popup;pub use component::Timed;pub use component::AccessibleItems;pub use component::FONT_WEIGHTS;pub use component::FontOverride;pub use component::MethodInfo;pub use component::NativeCommand;pub use component::NativeView;pub use component::NativeViewSlot;pub use component::PlatformHooks;pub use component::WebMessage;pub use component::url_origin;pub use component::prop_infos_of;pub use component::read_prop;pub use error::Error;pub use error::Result;pub use ui::DesignChanged;pub use event::ClickPointer;pub use event::EventArgs;pub use event::EventCtx;pub use event::GestureEvent;pub use event::GesturePhase;pub use event::Intercepted;pub use event::Key;pub use event::KeyEvent;pub use event::Modifiers;pub use event::PointerButton;pub use event::PointerEvent;pub use event::PointerKind;pub use event::PopupRequest;pub use event::ScrollOptions;pub use event::SwipeDirection;pub use event::SwipeEvent;pub use event::WHEEL_LINE;pub use event::WheelEvent;pub use forms::ModalResult;pub use forms::WindowPlacement;pub use bindings::Binding;pub use timing::TimerPrecision;pub use overscroll::Overscroll;pub use orientation::FormOrientation;pub use orientation::ScreenOrientation;pub use system_bars::BarIcons;pub use system_bars::SystemBarsStyle;pub use transition::TRANSITION_MS;pub use transition::Transition;pub use taskbar::JumpTask;pub use taskbar::TaskbarEvent;pub use taskbar::TaskbarProgress;pub use taskbar::TaskbarSpec;pub use taskbar::ThumbButton;pub use tray::TrayEvent;pub use tray::TrayEventKind;pub use tray::TraySpec;pub use window::ResizeEdge;pub use window::WINDOW_SETTINGS_CLASS;pub use window::WindowBackdrop;pub use window::WindowCommand;pub use window::WindowOptions;pub use geometry::Bounds;pub use geometry::PointF;pub use geometry::RectF;pub use geometry::SizeF;pub use icons::Icon;pub use keys::CharCase;pub use keys::CharFilter;pub use keys::mnemonic;pub use keys::parse_shortcut;pub use keys::shortcut_matches;pub use keys::shortcut_text;pub use keys::strip_mnemonic;pub use image::Image;pub use image::ImageFit;pub use image::ImageSource;pub use image::WeakImage;pub use image_cache::ImageCache;pub use image_cache::ImageCacheLimits;pub use image_cache::LayerCache;pub use image_cache::LayerCaching;pub use paint::PaintCtx;pub use path::Path;pub use path::PathCmd;pub use date::Date;pub use date::DateTime;pub use date::Time;pub use prop::RecordInfo;pub use event_value::DateRange;pub use event_value::EventArg;pub use event_value::EventValue;pub use event_value::FromSender;pub use gpu::FormPresent;pub use platform::Biometry;pub use platform::CursorShape;pub use platform::NotificationPriority;pub use platform::Permission;pub use platform::PermissionState;pub use providers::ErrorCorrection;pub use post::Poster;pub use prop::PropEnum;pub use prop::PropInfo;pub use prop::PropKind;pub use prop::PropValue;pub use registry::ClassInfo;pub use registry::ClassRegistry;pub use registry::VariantInfo;pub use registry::split_variant;pub use text::TextCase;pub use text::Trimming;pub use theme::ColorRef;pub use theme::Look;pub use theme::Material;pub use theme::Metric;pub use theme::ResolvedStyle;pub use theme::Style;pub use theme::StyleProps;pub use theme::Theme;pub use ui::ThemeSource;pub use ui::Ui;pub use exception::Exception;pub use textcore::TextMode;pub use question::Answer;pub use question::Asked;pub use views::FormView;pub use views::ViewChange;pub use views::ViewOrientation;pub use ui::EVENTS_PER_ROUND;pub use ui::LOOP_WARNING;pub use ui::MAX_EVENT_NESTING;pub use ui::MAX_TREE_DEPTH;pub use ui::SAFE_EVENT_NESTING;pub use ui::SAFE_TREE_DEPTH;pub use ui::is_identifier;
Modules§
- activity
- Observadores de atividade: tudo o que o usuário faz no app (ponteiro, roda, teclas,
texto) e o que o app responde (eventos com handler, forms que abrem e fecham, erros)
chega a quem estiver ouvindo. É a base do
EventRecorder(grava a sessão num arquivo que a IDE abre) e doAnalytics(métricas de uso), sem o núcleo saber de arquivos. - align
- Alinhamento e âncoras dos controles dentro do pai.
- anim
- Animações de propriedades (o “Animator”).
- automation
- Itens que um controle desenha sozinho (as abas de um TabControl, as linhas de um ListBox, os itens de um menu, as células de um grid) descritos para quem não vê a tela: os leitores de tela e a automação do sistema (UI Automation no Windows), o protocolo do inspetor e os testes. Cada item tem papel, nome, posição e estado, e aceita clicar ou selecionar — sem mandar evento de mouse para a janela.
- background
- O serviço em segundo plano (o componente
BackgroundService): a lógica sem tela do app (a unidadebackgrounddo projeto,pub fn run(service: Service)) numa thread que continua com a tela fechada. No Android ela fica num serviço em primeiro plano (a notificação fixa) e o sistema não mata o processo; no desktop, enquanto o app roda. - bindings
- Ligações de propriedades a dados: qualquer propriedade de qualquer componente pode mostrar um campo de um dataset (ou um texto montado com campos, ou uma expressão), e as editáveis gravam de volta.
- canvas
- Interface de desenho (o “TCanvas”). O core só conhece este trait; a implementação real (Skia na CPU ou na GPU) fica no crate de renderização.
- clipboard
- A área de transferência do app: texto, HTML, imagem e os formatos do próprio app (os componentes copiados no designer, um desenho, um registro), num lugar só.
- color
- Cor RGBA de 8 bits por canal.
- component
- O modelo de componentes:
ComponenteControlBase(os dados comuns de todo controle visual). - date
- As datas e as horas do calendário (sem fuso): o
DateEdit, oCalendare o acesso tipado as usam, e oaylis-datatambém (os campos de data dos datasets). - devices
- Os aparelhos de referência para ver um form como ele fica em cada um: o tamanho da tela
em pontos (em pé), os cantos, o recorte da câmera e as faixas cobertas pelo sistema (a
barra de status em cima, a barra de gestos embaixo). A IDE desenha a moldura no designer
e o app rodando no desktop abre do tamanho do aparelho (
AYLIS_DEVICE), com a área segura simulada e a mesma barra de status por cima. - error
- Erros do aylis.
- event
- Tipos de eventos de entrada (independentes de plataforma) e o contexto de evento.
- event_
value - O argumento tipado dos eventos: cada componente declara o que o evento leva
(
events: on_change: f64nocrate::properties!), o catálogo do acesso tipado escreve o handler com esse tipo nas 8 linguagens, e em Rust oEventValuetira o valor doEventArgs(o handler recebevalue: f64, não oargspara decifrar). - exception
- Um erro num handler ou num componente não derruba o app: o
Uipega o pânico (Rust) ou o erro que o backend relata (as outras linguagens), e o mostra ao usuário; o app continua aberto. - files
- Ler e gravar os arquivos que os diálogos devolvem, em qualquer plataforma.
- fonts
- Fontes de arquivo (TTF, OTF, TTC) usadas pelo app além das do sistema: as do projeto
(
assets/fonts/) ou registradas por código. O registro é do processo inteiro: os renderizadores (Skia, Direct2D, navegador) conferem ageneratione carregam as novas. - forms
- Forms abertos como janelas:
show,show_modal,closeeModalResult, com a pergunta antes de fechar (on_close_query) e o aviso ao fechar (on_close). - geometry
- Tipos geométricos: ponto, tamanho, retângulo e as medidas por lado.
- gpu
- Qual placa de vídeo usar quando a máquina tem mais de uma (a integrada e a dedicada de um notebook, ou duas placas num desktop). Vale para o processo inteiro: o Direct2D, o 3D e o OpenGL do Linux (pelo Mesa) leem a escolha ao abrir a GPU.
- handles
- O apoio do acesso tipado gerado (
self.edtNome.set_text(ui, ...)): cada componente de um form é um handle com oComponentIddele, resolvido uma vez ao abrir o form. Ler e gravar não falham calados: a falha (o componente foi liberado, o valor não serve) aparece no log em modo dev e vai para a atividade do app (a gravação, o relato). Quem quer tratar usa ostry_doHandle. - i18n
- Tradução: os textos da tela no idioma do usuário.
- icons
- Ícones vetoriais. O aylis traz um conjunto próprio (traço arredondado numa grade de
24×24) e aceita ícones do usuário em SVG (
Ui::register_icon). Os ícones mudam de cor com o tema: quem desenha passa a cor. - image
- Imagens para desenhar no
Canvas: um arquivo codificado (PNG, JPEG, WebP, GIF…) ou pixels RGBA prontos (um quadro de vídeo, uma imagem gerada). - image_
cache - O cache de imagens dos renderizadores: o que já foi feito de uma
Image(decodificada, enviada à placa de vídeo) para não refazer a cada pintura. - instances
- Forms com instância: cada form aberto tem a struct dele, com os componentes já resolvidos e o estado do usuário, e os handlers recebem essa struct. Um form aberto duas vezes (duas janelas de cliente, um frame embutido duas vezes) tem duas instâncias, e cada handler fala com a sua.
- keys
- Teclado do form: atalhos (“Ctrl+S”), as teclas que fazem o papel do Tab, os caracteres
que cada campo aceita (
allowed_chars/blocked_chars) e a letra do&nas legendas (o Alt+letra do Windows). - memory_
panel - O painel de memória do app em depuração: um quadro no canto do form principal com os
quadros por segundo, a memória do processo, o heap do Rust e as imagens guardadas pelos
renderizadores (
crate::image_cache::stats). Só aparece quando o app o liga (Ui::set_memory_panel): o app compilado comdevliga, a publicação nunca. Ctrl+Shift+M mostra e esconde. - messages
- As mensagens do próprio aylis (botões e títulos dos diálogos, validação dos campos, textos do grid…) nos idiomas que o aylis já traz: português (o original), inglês e espanhol.
- monitors
- Os monitores (lista, área útil, taxa) e a posição guardada de cada form.
Os monitores: a plataforma informa a lista
(
Ui::set_monitors) e em qual deles está a janela de cada form; o app lê comUi::monitorseUi::form_monitor(nas outras linguagens, pelo componenteScreen). Coordenadas em pixels físicos da área de trabalho, como o sistema dá (o monitor à esquerda do principal temxnegativo). - ndef
- NDEF, o formato das tags NFC: ler e montar as mensagens (os registros de texto, endereço e MIME) em Rust puro, para todas as plataformas falarem do mesmo jeito. O Android e os leitores USB (PC/SC) entregam e recebem os bytes; o navegador (Web NFC) já entrega os registros prontos.
- orientation
- A orientação da tela no celular (pedido do autor em 14/11), em três níveis:
- overscroll
- O efeito de fim da rolagem (decidido em 14/11): quando o dedo arrasta além do começo ou do fim de um contêiner com rolagem, ou a inércia bate na ponta, o contêiner mostra que acabou.
- pages
- Páginas gravadas: o que se desenha num
RecordingCanvasvira uma lista de operações que se repete em qualquer canvas (Page::replay, a visualização de um relatório) ou vira PDF pelo provedor de PDF (crate::providers::PdfProvider; o núcleo não escreve PDF). - paint
- Percurso de pintura da árvore e o contexto entregue a cada controle.
- palette
- Cores com nome: as do tema (
primary,text_3…) e as do projeto (a paleta do.aylisproj), usadas em qualquer propriedade de cor e nos estilos. - path
- Caminhos vetoriais: retas, curvas e arcos, para ícones, cabos,
gráficos e formas livres. Lê o atributo
ddo SVG. - platform
- Serviços de plataforma: os traits que cada sistema implementa.
- post
- Rodar código na thread da interface a partir de outra thread.
- profile
- Profiler (como o QML Profiler): blocos com começo e duração em faixas (handlers, eventos, layout, pintura, timers, animações, dados, recursos e as marcas à mão). Desligado, cada ponto de medição custa uma leitura atômica.
- prop
- Sistema de propriedades publicadas (o “RTTI” do aylis).
- providers
- Provedores (item 25): o que depende de projeto de terceiros vira um par. O componente que o
app usa diz o que faz (o
Barcode, oExport, oReport, oMapView, com as propriedades e os eventos de sempre); um componente provedor diz quem faz (com a biblioteca). O componente aponta o provedor pela propriedadeprovider, como odata_sourceaponta o dataset; sem provedor ligado, vale o provedor padrão do Aylis (não é erro). Trocar de biblioteca é trocar o provedor; um formato novo é um provedor novo; o app só leva o código dos provedores que os forms usam (oaylis-buildregistra por classe). - question
- Eventos que perguntam (item 3 dos ajustes): o
on_close_query(CanClose), obefore_poste obefore_delete(recusar a gravação), oon_validatedo campo, oon_key_down/on_key_press(engolir ou trocar a tecla), oon_drag_starte oon_drag_over. Quem dispara pergunta comUi::aske recebe a resposta: - registry
- Registro de classes: permite criar componentes pelo nome da classe, o que é usado pelos arquivos de layout, pela paleta da IDE e pelo controle remoto.
- span
- Um form em vários monitores (uma janela por monitor).
Um form em vários monitores (
span_monitorsdoForm): com monitores em placas de vídeo diferentes, uma janela que cobre todos faz o Windows copiar cada quadro de uma placa para a outra (vejadocs/gpu-por-monitor.md). Por isso o form vira uma janela por monitor, cada uma na placa do seu, e oUicontinua com um form só: - system_
bars - As barras do sistema no celular (a de status e a de navegação), pedidas pelo componente
SystemBars(decidido em 14/11). OUiguarda o pedido e a plataforma aplica: o Android pinta as barras e esconde; o iOS escolhe a cor dos ícones e esconde (a cor da barra no iOS é o que o app desenha por baixo dela: a faixa que o núcleo pinta,Ui::paints_status_strip); o navegador põe a cor natheme-colorda página. Sem pedido, a plataforma faz o de sempre (no Android, as barras com o fundo do form principal). - taskbar
- O botão do app na barra de tarefas: progresso, indicador, botões na miniatura (ao passar
o mouse) e tarefas no clique direito (a “jump list” do Windows). Um componente descreve
(
Component::taskbar); a plataforma aplica no botão da janela do form e devolve os cliques nos botões comoTaskbarEvent. - tasks
- Trabalho em segundo plano ligado a um dono (um componente ou um form): quando o dono é liberado (o form fechou), o resultado é descartado, em vez de rodar sobre um form que não existe mais (o acesso à memória de um form já fechado).
- text
- Disposição de texto em linhas: quebra automática e reticências (“…”), iguais em todos os renderizadores (Skia, navegador).
- textassist
- O motor de texto: correção ortográfica e sugestões para completar palavras, usado pelos
campos de texto (
spellcheck,autocomplete). A plataforma instala o motor nativo (no Windows, o corretor e a previsão de texto do sistema) emServices::text_assist; o app troca por outro motor (Hunspell, LanguageTool, uma lista de termos do negócio, um modelo de IA) implementandoTextAssiste pondo no lugar: - textcore
- O texto igual em todos os renderizadores (item 10): o modo de texto de cada plataforma.
- theme
- Temas: tokens (cores, fontes, raios, espaçamentos, durações), estilos por classe e
por estado, e variantes (
"Button.danger"). - themes
- Temas de plataforma que o aylis traz: o visual do Android (7, Material 2 e 3), do iOS
(7–12, 13–18 e 26), do Windows (7, 10, 11 e WinUI 3) e do Windows Phone, em claro e
escuro (quando a plataforma tem), e os da web (
web: Vuetify 3, Bootstrap 5, shadcn/ui, Ant Design 5 e Chakra UI). - timing
- A precisão dos timers (
TimerPrecision) e o esperar até um instante com ela. - transition
- Transições entre páginas e forms: esmaecer e deslizar. A página nova entra enquanto a
antiga sai, as duas desenhadas ao mesmo tempo (deslocadas com
translate_x/translate_yeopacity, que não mexem no layout); no fim, a antiga é escondida (ou o form é fechado) e os valores voltam ao normal. - tray
- Ícone na bandeja do sistema (perto do relógio): um componente descreve o ícone
(
Component::tray) e a plataforma mostra, anima e devolve os cliques como mensagem (TrayEvent) ao componente. - ui
Ui: dono de todos os componentes (arena), da árvore pai/filhos, dos nomes, das propriedades por nome, dos handlers de evento e do tema.- views
- Vistas do form (os “breakpoints”): ajustes por cima do form base, escolhidos pelo tamanho
real do form, pela orientação e pela plataforma. Um form com
views=phoneaté 599 etabletaté 1023 fica com o desenho base acima de 1023; abaixo, as mudanças da vista (propriedades, contêiner, escala de fonte e de espaços) valem por cima dele, e voltam ao base quando o form sai das condições. - window
- Comandos à janela de um form (minimizar, maximizar, arrastar…): o que uma barra de
título própria precisa. O
Uisó enfileira; a plataforma executa no laço dela.
Macros§
- leaf_
control - Implementa
class_name,controlecontrol_mutpara um controle “folha” (que guarda o próprioControlBaseno campobase). Fica no núcleo porque os controles moram em vários crates (aylis-controls-base,aylis-controls-charts…). - properties
- Publica campos como propriedades, gerando
props,get_propeset_propde umComponent. Use dentro doimpl Component for .... - stderr_
line - Uma linha no stderr, como o
eprintln!, mas sem entrar em pânico se ele estiver fechado: um app aberto pela IDE escreve num pipe, e com a IDE fechada (ou a execução parada) oeprintln!derrubava o app (“failed printing to stderr”).
Structs§
- Drag
Visual - O que acompanha o cursor num arrasto: uma imagem (a miniatura de um vídeo, o ícone de um
arquivo), do tamanho pedido, meio transparente, presa ao cursor pelo ponto
hotspot. No Windows ela vai numa janela própria e segue o mouse por cima de tudo, fora da janela também; nos outros sistemas, o form a pinta junto do mouse. - Screen
Pointer - O mouse na tela durante um arrasto: pixels físicos e a escala (pixels por ponto) da janela onde o arrasto começou.
- Scroll
Move - Pixels já pintados que andam (a rolagem): os de
rect(nas coordenadas do form) vão pararectdeslocado dedelta.
Enums§
- DragEnd
- Como acabou um arrasto (para o
Component::drag_endedda origem). - Frame
Damage - O que repintar num quadro (
Ui::take_frame).
Constants§
- FORM_
DRAG - O começo dos dados do arrasto de uma janela inteira (
Ui::window_drag_over): depois dele, o id do form. - HINT_
DELAY - Tempo com o mouse parado em cima até a dica aparecer, em segundos: o padrão, quando nem o
tema (
durations.hint, em ms) nem o app (Ui::set_hint_delay) dizem outro.
Functions§
- is_
right_ to_ left_ language - Os idiomas escritos da direita para a esquerda (árabe, hebraico, persa, urdu…).