Contributing¶

How libwinui works inside, and where a change hooks in.

Where to Start¶

Get the library building and the tests green first. Building covers the requirements, the CMake options and the commands; after a first build you have winui_tests.exe and the example apps in build/bin/Debug/.

Then run the gallery (gallery.exe). It has one page per control and a theme picker in its header that switches between every era pack and between light and dark. Most changes end with a look at the gallery page of the control you touched, in more than one theme.

What a Contribution Looks Like¶

Most changes are one of a few shapes, and each has its own page under Hooks:

• A control. A header and source file, its spec and build(), tests with TestRenderer and the headless host, a gallery page and a reference entry. See Add a Control.
• A spec field. A new property on an existing description, without breaking a single call site. See Add a Spec Field.
• A theme era. A palette, the derivation that turns it into a Theme, a ThemeVariant value and the tests that pin its values. See Add a Theme Era.
• A render command. A new drawing primitive through the recorder, the semantic dump and the Direct2D backend. See Add a Render Command.
• A platform seam. An operating system service behind an interface, with a test double and a Win32 implementation. See Add a Platform Seam.

Bug fixes follow the same rule as everything else: a test that fails before the fix and passes after it, in tests/.

Reading Order¶

1. Development: build it, learn the conventions, write tests, and keep these docs in sync.
2. How It Works: the tree, specs and build(), layout, rendering, input and focus, theming, era packs and platform seams.
3. The hook page for the change you are making.