Reference¶

The public API, generated from the headers: one page per control, grouped by what it is for, and one page per type or namespace everywhere else.

How a Reference Page Is Laid Out¶

A control page puts the description and the control it builds side by side, in this order:

Purpose. The header to include, the spec's header, and what the control is.
Example. A short snippet showing the control in use, often both declared and hand-built.
The spec (ui::Button). Its fields in declaration order, which is the order designators have to follow, as a table of name, type, default and description. The common fields every spec shares are folded into one line that links to Conventions. Then build().
The control (ui::ButtonControl). What it derives from, its description, then its public members: constructors, getters and setters, event hooks, and the Element overrides it implements.
Related types. Helper classes and enums that belong to the control, such as ButtonVariant on the Button page or RadioGroup on the RadioButton page.
Example and tests. A snippet from a tutorial, where one exists, and the test files that cover the control. The tests are the most complete usage examples there are.

Every other page is a single class or struct, laid out the same way as the control part above, or a namespace page listing its free functions, enumerations, aliases and constants.

Namespaces¶

Namespace	What is in it	Where it shows up
`ui`	Everything an app writes. The specs, one aggregate per control (`ui::Button`, `ui::VerticalStack`, `ui::Text`, ...), with `Spec`, `Control<>`, `Style` and `ui::build()`; and the retained tree they build: the controls (`ui::ButtonControl`), `Element`, `Window`, `Property` and `bind()`, geometry and color, the `Renderer` interface, `Theme`, the headless host.	Controls and Layout for the specs and controls, the other sections for the rest.
`ui::testing`	The testing tier, opt-in through `<winui/testing.hpp>`: `HeadlessUI`, `TestRenderer`, the test doubles for the platform seams, `OffscreenCapture` and `seams()`.	Testing.

Smaller namespaces hold constants: ui::colors, ui::glyphs and ui::styles.

The library is libwinui and its headers are under winui/; the namespace is ui.

Specs Versus Controls¶

ui::Button describes a button. It is a plain aggregate you fill in with designated initializers, hand to a parent or a window, and never see again. ui::ButtonControl is the control that build() makes from it: a node in the tree, with state, setters and invariants. When you need to talk to a built control later, the spec's .control field fills a ui::Control<ui::Button> handle that reaches it.

The two are documented on the same page because you use them together. The control's name is the spec's name plus Control (ui::Text builds a ui::TextControl, ui::Rating a ui::RatingControl); Conventions lists the few pairs that differ, such as ui::VerticalStack and ui::HorizontalStack both building a ui::StackControl.

Every control can also be built by hand, and every spec field has a matching setter on the control. Mixing Imperative and Declarative shows both together.

Coming From WinUI or WPF¶

libwinui follows WinUI's controls closely but names them for clarity, so some names differ. A spec keeps the short name and its control is that name plus Control.

You are looking for	In libwinui
`StackPanel`	`ui::VerticalStack`, `ui::HorizontalStack`
`TextBlock`, `RichTextBlock`	`ui::Text`, `ui::RichText`
`ContentDialog`	`ui::Dialog`
`GridView`	`ui::TileView`
`DataGrid`	`ui::TableView`
`VariableSizedWrapGrid`	`ui::TilePanel`
`ItemsRepeater`	`ui::ForEach`
`UniformGridLayout`, `FlowLayout`	`ui::TileLayout`, `ui::WrapLayout` (item layouts)
`ScrollViewer`, `ScrollView`	`ui::Scroll`
`SplitView`	`ui::SidePane`
`TwoPaneView`, `Viewbox`, `ParallaxView`	`ui::TwoPane`, `ui::ScaleToFit`, `ui::Parallax`
`NavigationView`	`ui::NavigationShell`
`Frame`	`ui::NavigationFrame`
`TabView`, `Pivot`	`ui::Tabs`, `ui::Sections`
`FlipView`	`ui::Carousel`
`RatingControl`, `PagerControl`, `SwipeControl`	`ui::Rating`, `ui::Pager`, `ui::Swipe`
`BreadcrumbBar`	`ui::Breadcrumb`
`ContextFlyout`	`ui::ContextMenu`
`FontIcon`, `SymbolIcon`, `BitmapIcon`, `PathIcon`	`ui::Icon`
`XamlUICommand`, `KeyboardAccelerator`	`ui::Command`, `ui::Shortcut`
`*NavigationTransitionInfo`	`ui::PageTransition` (`ui::ZoomPageTransition`, `ui::SlidePageTransition`, ...)
`EntranceThemeTransition` and the other theme transitions	`ui::EntranceTransition`, `ui::RepositionTransition`, ...
`x:Name` and a field in code-behind	a `ui::Control<...>` handle and the spec's `.control`
`{x:Bind ..., Mode=TwoWay}`	`ui::bind(prop)` on an editable field
`FileOpenPicker`, `FileSavePicker`, `FolderPicker`	`ui::pick_file()`, `ui::pick_save_file()`, `ui::pick_folder()`
`Window.Activate()`, `Application.Start()`	`window.show()`, `ui::run(window)`

Generated Pages¶

Everything in this section except three pages comes from the headers, through Doxygen and docs/tools/gen_reference.py. This page, Conventions and the Themes overview are written by hand.

Section	Holds
Controls	One page per control and its spec, grouped by purpose: basic input, text, collections, navigation, menus and toolbars, dialogs and flyouts, status and info, media and icons, windowing and hosting.
Layout	Panels, containers, scrolling and gestures, panes and splitters.
Tree and window	`Element`, `Window`, focus, automation and the other types under `winui/ui/`.
Core	Geometry, color, input events, `Property`, `Binding`, the scheduler, UTF-8 helpers.
Rendering	The `Renderer` interface and its commands, `TestRenderer`, `describe()`, images, text styles, brushes and the seam interfaces.
Testing	The opt-in testing tier: `HeadlessUI`, `TestRenderer`, the test doubles for the platform seams and `OffscreenCapture`.
Themes	`Theme`, the palettes, `ThemeRequest` and the theme sources.

Outside Controls and Layout, a section lists its topic pages first (small types bundled on one page), then Classes, Structs and Namespaces. A namespace page holds that namespace's free functions, enumerations, aliases and constants for the section.

If something is missing or wrong on a generated page, the fix goes into the header's /// comment, not into the page. See Documentation.