User guide

Hello World

Window setup, state management, DOM creation, handling mouse clicks for a „counter“ app

• Hello World [Rust]
• Hello World [C]
• Hello World [C++]
• Hello World [Python]
• Hello World [C#]
• Hello World [Java]
• Hello World [Kotlin]
• Hello World [Lua]
• Hello World [Ruby]
• Hello World [Node.js]
• Hello World [OCaml]
• Hello World [Zig]
• Hello World [Go]
• Hello World [Pascal]
• Hello World [Scala]
• Hello World [Fortran]
• Hello World [Haskell]
• Hello World [Common Lisp]
• Hello World [PHP]
• Hello World [Perl]
• Hello World [D]
• Hello World [Nim]
• Hello World [Racket]
• Hello World [Red]
• Hello World [Odin]
• Hello World [Crystal]
• Hello World [Julia]
• Hello World [V]
• Hello World [Swift]

Application Architecture

Explains the concepts of architecting a larger Azul application

• Understanding RefAny — RefAny helps you to share and store type-erased data between callbacks and threads

Document Object Model

Node types, hierarchy, and CSS scoping

• Reconciliation — Diffing, restyle scope, and damage-rect repaint
• Datasets — Attaching state to a node for navigation and per-instance state
• Merge Callbacks — How widgets keep heavy resources across a layout rebuild
• Virtual Views — A node that materialises lazily, for infinite lists and embedded sub-DOMs
• Components — Reusable UI fragments - named functions of (args) -> Dom

Callbacks

What CallbackInfo exposes — state, DOM mutation, focus, async work

Routing

URL patterns, route params, and per-route layout callbacks

Styling with CSS

Stylesheets, selectors, and the cascade

• CSS Properties — Reference of every CSS property azul recognises
• System Themes — System colors, `@theme`, `@os`, and accessibility queries
• Styling Text — Font family, size, weight, alignment, decoration, and the system font keywords
• Icon Packs — Register icons and use them with `Dom::create_icon` or `<icon>`

Layout

Overview of the layout solver

• Simple Layout — Explains block formatting, sizing, positioning, the box model and how to handle overflowing content
• Inline Layout — Text flow, word breaks, writing modes, multi-column
• Flexbox — One-axis container layout with grow/shrink/basis
• Grid — Two-axis container layout with tracks and areas

Images

Loading raster images and CSS backgrounds

• SVG — Parsing and rendering SVG documents
• GL Canvas — Embedding an OpenGL canvas inside a Dom node

Events

Callbacks, event filters, and how state triggers relayout

Text Input

Editable text, IME, and the selection model

Text Selection

Selection ranges, cursors, and copy/paste

Timers

Timers, threads, and scheduled work

Animations

CSS transitions and @keyframes

Scrolling

Scroll containers, drag-and-drop, hit testing

Windows, Menus, Decorations

Windows, menus, decorations, and per-window state

Built-in Widgets

Built-in widgets and how to write your own

• Input Widgets — Text fields, checkboxes, radios, sliders, dropdowns
• Structural Widgets — Panels, splitters, tab views, list views, tree views

Debugging

Debug overlays, the inspector, and structured logging

Profiling

Tracking allocations and per-frame budgets

End-to-End Testing

Driving an Azul app from a script for tests

XML Parsing (Standalone)

Loading a Dom from an XML string

File Dialogs

Native open/save dialogs and folder pickers

Maps (MapWidget)

A slippy map widget with pan/zoom, tap-to-pin hooks, and lat/lon projection

Clipboard

Reading and writing the system clipboard

Generating PDFs (HTML-to-PDF)

Render a styled Dom to PDF bytes - headless, no window, no file I/O

Background Tasks

Running long jobs off the layout thread

SQL Database (Db)

A bundled-SQLite handle - execute/query with typed value arrays

Networking

HTTP from a callback

Device Input (Sensors, Gamepad, Geolocation)

React to motion sensors, gamepads, and location as events - no polling

Accessibility

Screen reader integration and ARIA roles

Realtime Media and Devices

Camera/mic capture, audio playback, and streaming A/V frames to a peer (the azul-meet pattern)

Mobile (iOS & Android) in Rust

Build, package, sign and install an Azul app as an .apk / .ipa — all Rust, from any OS, no Xcode or Android Studio

Headless Rendering

Running the pipeline without a window

Code Generation

How `azul-doc` regenerates bindings from `api.json`

Deploying to the web

Run the same azul binary as a web app — how the WASM lift works and how to ship it

Security Model

What azul does and doesn't defend against

Documentation Reference Backlog

Internals

• Async, Timers, Threading — Timers, threads, and IO callbacks across the layout thread
• Code Organization — Top-level crate map and where each piece lives
• DOM Internals — How the public `Dom` type is built, flattened, and reconciled
  • Component Type System — How typed component IDs resolve at the layout layer
  • IFrame Scroll and Display Lists — Iframe scroll regions and coordinate translation
  • VirtualView Lazy Loading — What the virtual view layer caches and how it survives layouts
• Events — Event dispatch, filter taxonomy, default actions
  • Hit Testing — Hit-test tag generation and cursor-to-node routing
• FFI Codegen — How `cargo build` cascades and the codegen pass
• Host-Invoker Pattern (managed-FFI callbacks) — How LuaJIT/Ruby/PHP/Node/etc. wire up Azul callbacks despite libffi's struct-by-value limit
• Layout — solver3 architecture, formatting contexts, and the per-frame relayout cycle
  • Fragmentation — Page breaks, widows, orphans, and PDF fragmentation
  • Inline Text — text3 - shaping, line breaking, BiDi, hyphenation, editing
• Rendering — From `StyledDom` to pixels - display list, GPU/CPU, resources
  • GL Function Loading — Loading GL function pointers across platforms
  • Image Pipeline — Decoding, caching, and uploading raster images
  • Text Pipeline — Font discovery, parsing, and fallback chain resolution
  • WebRender Bridge — How azul talks to WebRender
• Styling Subsystem — How parsed CSS becomes per-node resolved layout values
  • CSS Parser — The hand-written CSS parser
  • Cascade, Inheritance, Restyle — Selector matching, specificity, and computed values
  • Compact Property Cache — How layout results are stored across frames
  • System Style Discovery — Discovering OS theme, accent, fonts, and a11y settings
• Web Backend Internals — WASM target — server-side render, lift, dispatch
• Windowing — Per-window aggregate, headless variant, and the platform shell layer
  • Windowing — Accessibility — Per-platform a11y back-ends - UIA, AT-SPI, NSAccessibility
  • Windowing — Common — Shared shell infrastructure across platforms
  • Windowing — Linux DBus — Linux DBus integration for a11y, dialogs, notifications
  • Windowing — Linux Wayland — Linux Wayland shell - wl_surface, xdg-shell, libinput
  • Windowing — Linux X11 — Linux X11 shell - Xlib, GLX, XInput2
  • Windowing — Menus and CSD — Menus and client-side decorations across platforms
  • Windowing — Windows — Windows shell - Win32 messages, DirectComposition, IME
  • Windowing — macOS — macOS shell - Cocoa, AppKit, IME, a11y