XUI handbook

These documents describe XUI for application authors. The root README introduces the framework. CONTRIBUTING contains build and test instructions.

Learn XUI

XUI is a Windows desktop framework with retained controls, native text editing, and explicit ownership. It supports C++ and a C ABI, with C# and Rust wrappers. The .xui language generates C#; it is not XAML or a cross-language runtime. APIs are still evolving.

• Tutorials: Build a task card, add native input, compose controls, apply styles, and prepare a release.
• All controls: Choose a control and find its usage, language availability, and contract.
• Language guides: Start with C++, C, C#, Rust, or declarative .xui with C#.
• Book contents: Browse the complete GitBook navigation.

The handbook and the references below use the same Markdown source. Retype supplies a local preview and static output for GitHub Pages. See preview and deployment for commands and the publication approval requirement. The repository also retains GitBook Git Sync configuration. No hosted site is required to read these pages.

Start here

• Packages and deployment: dotnet new xui, NuGet, Cargo, native-only C++ integration, sample and Designer archives, and local DLL selection.
• Declarative XUI: Components, C# state, compiler diagnostics, project integration, hot reload, and VS Code or Microsoft Edit syntax support.
• Application composition and lifecycle: C++ examples, controls, sizing, scrolling, owned-child enumeration, native file dialogs, and accessibility.
• C ABI, C#, and Rust: Binding coverage, examples, data limits, and error contracts.
• WinUI-style appearance: Optional style selection, supported controls, and platform boundaries.
• Mica and acrylic materials: Windows 11 window backdrops, in-app acrylic surfaces, fallbacks, and binding coverage.
• Control styles and color resources: One shared API for all supported elements, named parts, typography, state rules, and version-2 migration.
• Control styling inventory: Delivered coverage, exact value limits, retained-child paths, and remaining native/binding gaps.

Control contracts

• Foundation controls: Binary and tri-state choices, selectors, badges, ranges, numeric inputs, popups, and animated progress.
• Collections and asynchronous data: Virtual lists, grids, trees, Miller columns, selection, and worker delivery.
• Context menus, tabs, and input: Native menus, tab dragging between windows, split panes, folder suggestions, and keyboard behavior.
• Commands and navigation: Menu bars, command surfaces, palettes, breadcrumbs, Shell commands, and title bars.
• Images and thumbnails: Decode limits, caching, cancellation, and Shell icons.
• Documents, dialogs, and color: Native editors, syntax highlighting, password access, modal content, and form controls.
• Scenes and native hosts: Vector shapes, offline maps, media, and optional web content.
• Swap chain panel: Composition surfaces, physical sizing and visible bounds, C/C# bindings, and the terminal adapter boundary.

The control references describe the C++ API unless stated otherwise. The binding reference takes precedence for C# and Rust coverage. Public headers and binding source define the available symbols.

Samples

• XUI Designer
• Control gallery
• C# and C++ file explorers: Navigation, icon galleries, List, Tree, Details, Columns, commands, and C# file previews.
• Minesweeper
• Floating C# card: Borderless alpha window or Desktop Acrylic card with borrowed HWND, drag area, native input, and a pixel/hit-test smoke check.
• Task Manager
• Thumbnail sample

Design and technical reports

• Zoey the XUI Lion: The XUI mascot, canonical artwork, and reusable icons.
• Styles and templates: Application-authored presentation, staged delivery, native-host boundaries, and performance acceptance.
• Opt-in animations: Four-edge reveals, coordinated layout, split panes, and the animation demo catalog.
• WinUI-style design proposal: Visual targets, implementation stages, and acceptance gates.
• Windows GUI memory report: Measurement methods, graphics allocations, and the limits of the recorded evidence.

Proposals distinguish implemented behavior from future work. Historical measurements describe their recorded environment, not every Windows system. Implementation plans and handoffs are in the maintainer index.