ui¶

Namespace-scope declarations of ui from the tree and window headers.

Enumerations¶

EasingMode¶

enum class EasingMode

Header: winui/ui/Animation.hpp.

Which end of the curve the easing is applied to. EaseOut is the default.

KeyFrameKind¶

enum class KeyFrameKind

Header: winui/ui/Animation.hpp.

How a key frame's segment gets from the previous value to its own.

AnimatedProperty¶

enum class AnimatedProperty : std::uint8_t

Header: winui/ui/Animation.hpp.

What an animation started on an element drives (Element::start_animation()): the element's opacity, rotation, translation, scale or center point, whole or one component.

FillBehavior¶

enum class FillBehavior

Header: winui/ui/Animation.hpp.

Whether a finished animation keeps its last value (HoldEnd, the default) or hands the property back to the value it had before it started (Stop).

Vector3Components¶

enum class Vector3Components : std::uint8_t

Header: winui/ui/Animation.hpp.

Which components of a Vector3 property a transition animates; the others snap to their new value.

PageSlideDirection¶

enum class PageSlideDirection

Header: winui/ui/Animation.hpp.

The direction of a SlidePageTransition.

TransitionChannel¶

enum class TransitionChannel : std::uint8_t

Header: winui/ui/Animation.hpp.

Which transition-target value a storyboard track drives.

AutomationRole¶

enum class AutomationRole

Header: winui/ui/Automation.hpp.

What kind of thing a control is, as reported to accessibility clients such as screen readers. The default, Group, is right for every plain container. A Group node still appears in the accessibility tree, as a grouping node with no interaction.

A control reports its role by overriding Element::automation_role(), and what it lets a client do through the provider interfaces it lists in Element::automation_providers().

Example:

// A custom rating control exposed like a Slider to screen readers.
class Stars final : public ui::Element, private ui::RangeValueProvider
{
public:
    ui::AutomationRole automation_role() const override { return ui::AutomationRole::Slider; }

protected:
    void automation_providers(ui::AutomationProviders& out) override { out.range_value = this; }
    // measure_override()/render_override() omitted

private:
    double range_value() const override { return rating_; }
    double range_minimum() const override { return 0.0; }
    double range_maximum() const override { return 5.0; }
    double range_small_change() const override { return 1.0; }
    bool   range_read_only() const override { return false; }
    bool   set_range_value(double value) override { rating_ = value; return true; }

    double rating_ = 3.0;
};

ToggleState¶

enum class ToggleState

Header: winui/ui/Automation.hpp.

The Toggle pattern's three-valued state, reported by ToggleProvider::toggle_value().

AutomationProperty¶

enum class AutomationProperty

Header: winui/ui/AutomationTree.hpp.

A property of a node that changes as it is used, for AutomationEvents::property_changed().

DataPackageOperation¶

enum class DataPackageOperation : unsigned

Header: winui/ui/Clipboard.hpp.

What the source of a clipboard or drag payload wants done with it. The values are bit flags, so a combination such as Copy | Link is representable.

StandardDataFormat¶

enum class StandardDataFormat

Header: winui/ui/Clipboard.hpp.

The three formats Clipboard::contains() answers for.

StandardCommand¶

enum class StandardCommand

Header: winui/ui/Command.hpp.

The sixteen common commands standard_command() can pre-fill, plus None.

Visibility¶

enum class Visibility

Header: winui/ui/Element.hpp.

Whether an element is shown. A Collapsed element takes no room in layout, draws nothing, takes no input and leaves the tab ring, along with everything under it.

ElementTheme¶

enum class ElementTheme

Header: winui/ui/Element.hpp.

The theme an element (and everything under it) uses: light or dark whatever the window's is, or following it (Default).

Alignment¶

enum class Alignment

Header: winui/ui/Element.hpp.

How an element is placed within the (possibly larger) rect its parent affords it on one axis, once margin/min-size are accounted for. Stretch, the default, hands the element the whole rect. The other three shrink the element to its own desired extent and position it within the rect. A stack's child_alignment uses the same values for all of its children at once, on the axis across the stack (see Stack.hpp).

AutoVisibility¶

enum class AutoVisibility

Header: winui/ui/Element.hpp.

Whether a part a control can show is shown: decided by the control (Auto, the default), always, or never. A TeachingTip's tail, a CommandBar's More button and a NavigationShell's back button take it; each field's comment says what Auto decides there.

SelectionMode¶

enum class SelectionMode

Header: winui/ui/Element.hpp.

How many items a collection lets the user select, and with which gestures (ListView, TileView, TableView).

PopupPlacement¶

enum class PopupPlacement

Header: winui/ui/Element.hpp.

Which side of its anchor a popup (ComboBox/Menu/Flyout/ToolTip/TeachingTip, see PopupRequest::placement) hangs from. When there isn't room, every popup flips to the opposite side of the same axis instead of covering the anchor. A TeachingTip also tries the other axis.

PopupPlacementAlignment¶

enum class PopupPlacementAlignment

Header: winui/ui/Element.hpp.

How a popup lines up with its anchor along the side PopupPlacement picked: centered, or with the left (top) edges or the right (bottom) edges lined up. A TeachingTip keeps its tail on the target's center, so Leading lets the card run right (or down) from the tail and Trailing left (or up).

PopupCloseReason¶

enum class PopupCloseReason

Header: winui/ui/Element.hpp.

Why a popup (Flyout, MenuFlyout, CommandBarFlyout, TeachingTip) closed.

HitRegion¶

enum class HitRegion

Header: winui/ui/Element.hpp.

What a press at a point means to the window around it, for a window whose content stands in for its caption: a Frame::Borderless window, or content extended into the title bar. Resize edges depend on DPI frame metrics, so the host classifies those itself before asking the tree. The caption-button values are for a caption the app draws itself: the press still reaches the element under it, and the host tells the OS what is there.

FocusRequest¶

enum class FocusRequest

Header: winui/ui/Element.hpp.

What an element asks Window to do with keyboard focus, once, polled on every layout pass through take_focus_request() below.

MessageBoxButtons¶

enum class MessageBoxButtons

Header: winui/ui/MessageBox.hpp.

The buttons a message box offers (MessageBoxOptions::buttons).

MessageBoxIcon¶

enum class MessageBoxIcon

Header: winui/ui/MessageBox.hpp.

The icon beside a message box's text (MessageBoxOptions::icon).

MessageBoxResult¶

enum class MessageBoxResult

Header: winui/ui/MessageBox.hpp.

The button the user chose, what ui::message_box() returns. Closing the box with Escape or its close button is Cancel, or Ok on a box whose only button is OK.

NotificationIcon¶

enum class NotificationIcon

Header: winui/ui/Notification.hpp.

The picture a notification carries (Notification::icon).

PickerLocation¶

enum class PickerLocation

Header: winui/ui/Pickers.hpp.

The known folder a picker opens in when no folder is given, the first time or every time as remember_last says. Unspecified leaves it to the dialog.

PrintDialog¶

enum class PrintDialog

Header: winui/ui/Printing.hpp.

Which print dialog ui::print() shows.

PrintResult¶

enum class PrintResult

Header: winui/ui/Printing.hpp.

How a print job ended.

WindowState¶

enum class WindowState

Header: winui/ui/WindowShell.hpp.

The state a window is in, read through Window::state() and asked for with Window::request_state(). Two things are not states:

• A snapped or arranged window (snap layouts, Win+Left/Right) is in the Normal state. The OS controls snapping, and an app cannot request it.
• Exclusive fullscreen, where the app owns the display mode, is not supported. Fullscreen is the borderless kind that browsers and video players use.

Visibility (Window::visible()) and always-on-top (WindowStyle::always_on_top) are independent of the state.

Example:

window.set_content(ui::Button{
    .text = ui::bind(window.state(), [](ui::WindowState s) {
        return std::string{s == ui::WindowState::Maximized ? "Restore" : "Maximize"}; }),
    .on_click = [&] {
        if (window.state().get() == ui::WindowState::Maximized) window.restore();
        else window.request_state(ui::WindowState::Maximized);
    },
});

TaskbarProgressState¶

enum class TaskbarProgressState

Header: winui/ui/WindowShell.hpp.

The state of the taskbar button's progress bar.

Frame¶

enum class Frame

Header: winui/ui/WindowStyle.hpp.

How much of the frame the OS draws (WindowStyle::frame).

Backdrop¶

enum class Backdrop

Header: winui/ui/WindowStyle.hpp.

The system material behind the window. Where the system has no backdrop materials, the window keeps its opaque background.

The theme can decline it (ChromeHints::allows_system_backdrop does for every era before Windows 11, and for high contrast), and so can the system, for example with transparency effects off or in energy saver mode. Seeded by ui::WindowOptions::backdrop, applied live through Window::set_backdrop(). While a backdrop is on, the client area is left transparent and Window::background() is not painted.

Example:

int main()
{
    ui::Window window{{.title = "Mica", .backdrop = ui::Backdrop::Mica}};
    window.set_content(ui::Button{
        .text     = "Switch to Acrylic",
        .on_click = [&window] { window.set_backdrop(ui::Backdrop::Acrylic); }, // applied live
    });
    return ui::run(window);
}

Aliases¶

EasingFunction¶

using ui::EasingFunction = std::
   variant<CubicBezier, BackEase, BounceEase, CircleEase, CubicEase, ElasticEase, ExponentialEase, PowerEase, QuadraticEase, QuarticEase, QuinticEase, SineEase>

Header: winui/ui/Animation.hpp.

One easing curve: a CubicBezier (the default, which is linear) or one of the eleven named eases above. Assign any of them directly: .easing = ui::SineEase{ui::EasingMode::EaseInOut}.

Animation¶

using ui::Animation = std::variant<DoubleAnimation, KeyFrameAnimation, SpringAnimation, ExpressionAnimation>

Header: winui/ui/Animation.hpp.

Any of the four, for Element::start_animation().

PageTransition¶

using ui::PageTransition = std::variant<RisePageTransition, ZoomPageTransition, NoPageTransition, SlidePageTransition, FadeThroughPageTransition>

Header: winui/ui/Animation.hpp.

One of the navigation transitions, passed to NavigationFrameControl::navigate() or used as a NavigationTransition's default.

Transition¶

using ui::Transition = std::variant<EntranceTransition, RepositionTransition, ContentTransition, AddRemoveTransition, PopupTransition, NavigationTransition>

Header: winui/ui/Animation.hpp.

One transition, for Element::set_transitions(), Element::set_children_transitions() and the transitions-style spec fields.

TransitionList¶

using ui::TransitionList = std::vector<Transition>

Header: winui/ui/Animation.hpp.

An element's transitions, in the order they were given.

AutomationValue¶

using ui::AutomationValue = std::variant<std::monostate, bool, double, std::string, ToggleState>

Header: winui/ui/AutomationTree.hpp.

A property's value; std::monostate when the node has no such pattern.

Functions¶

animations_enabled¶

bool animations_enabled()

Header: winui/ui/Animation.hpp.

Whether animations play right now. False while a Window whose theme has Theme::animations_enabled off is ticking, laying out, rendering or dispatching input to its tree. True outside any window. A control that runs its own tween checks it, or advances its clock by animation_delta(), so the tween jumps to its end state instead of playing.

Example:

class Drawer : public ui::Element
{
    static constexpr ui::Duration SlideTime = 250ms;
    ui::Duration                  slide_{};

    void tick_override(ui::Duration delta) override
    {
        slide_ = std::min(slide_ + ui::animation_delta(delta), SlideTime);
        mark_dirty(ui::DirtyFlags::Visual);
    }
};

animation_delta¶

Duration animation_delta(Duration delta)

Header: winui/ui/Animation.hpp.

How far an animation's clock moves in a tick of delta: delta itself, or, while animations_enabled() is false, far enough to finish any finite animation in that one tick. Use it only for animations. A delay, a timeout, a blink or a looping indicator keeps counting delta.

ease¶

float ease(const EasingFunction& function, float t)

Header: winui/ui/Animation.hpp.

The eased progress for linear progress t (0..1), with the curve applied at the end its EasingMode names. The curves may overshoot 0..1 (Back, Elastic).

sample_key_frames¶

float sample_key_frames(std::span<const KeyFrame> frames, float base, Duration time)

Header: winui/ui/Animation.hpp.

The value of frames (sorted by time) at time. Each frame's segment starts at the previous frame's value, the first one's at base (the value the property had when the animation started). After the last frame its value holds.

key_frames_duration¶

Duration key_frames_duration(std::span<const KeyFrame> frames)

Header: winui/ui/Animation.hpp.

The time of the last key frame: a key frame animation's natural duration.

operator|¶

Vector3Components operator|(Vector3Components a, Vector3Components b)

Header: winui/ui/Animation.hpp.

Combines two component sets (Vector3Components::X | Vector3Components::Y).

has_component¶

bool has_component(Vector3Components set, Vector3Components c)

Header: winui/ui/Animation.hpp.

Whether set includes component c.

find_transition¶

template <typename T>
const T* find_transition(const TransitionList& transitions)

Header: winui/ui/Animation.hpp.

The first transition of type T in transitions, or nullptr.

sample_transition¶

TransitionTargetState sample_transition(const TransitionStoryboard& storyboard, Duration elapsed)

Header: winui/ui/Animation.hpp.

The transition target storyboard gives elapsed after it started. During its delay the tracks hold their first values. The target is set to the start values before a staggered storyboard begins, so a staggered entrance stays invisible while it waits.

transition_transform¶

Matrix transition_transform(const TransitionTargetState& target, const Rect& bounds)

Header: winui/ui/Animation.hpp.

The transform a transition target draws an element at bounds (window coordinates) through: its scale about scale_origin (relative to the size), then its translation. Identity when the target is at rest.

stagger_delay¶

Duration stagger_delay(std::size_t index, Duration delay)

Header: winui/ui/Animation.hpp.

The start delay of the element at index (from 0) among those started together. It waits (index + 1) times delay, so the first one already waits one.

run¶

int run(Window& window)

Header: winui/ui/App.hpp.

Show window and run the message loop until it is closed; returns the exit code.

The window is the app's main window. It is created from its WindowOptions if it has no OS window yet, and the loop also runs every other window the app shows (Window::show()) while it is open. Closing the main window ends the loop and closes whatever else is still open. run() only borrows the window: it is an object the app owns, usually a local in main(), and it is still a valid, closed Window when run() returns. Not re-entrant: one run() at a time.

Returns -1 when the window could not be created, or on a platform with no backend.

Example:

int main()
{
    ui::Window window{{.title = "Demo", .size = {400, 300}}};
    ui::Property<int> clicks{0};
    window.set_content(ui::Button{.text = "Click", .on_click = [&] { ++clicks; }});
    return ui::run(window);
}

run¶

int run()

Header: winui/ui/App.hpp.

Run the message loop with no main window. Every window the app shows runs on it. Closing the last one does not end the loop, only quit() does. Returns quit()'s exit code, and closes whatever is still open on the way out. For apps whose entry point is not a window, such as a tray icon. Not re-entrant.

Example:

int main()
{
    ui::Window tool{{.title = "Tool", .size = {300, 200}}};
    tool.set_content(ui::Button{.text = "Quit", .on_click = [] { ui::quit(); }});
    tool.show();
    return ui::run(); // closing the window does not end the loop, quit() does
}

open_window¶

Window& open_window(std::unique_ptr<Window> window)

Header: winui/ui/App.hpp.

Shows window and hands it to the message loop, which destroys it between two messages once it has closed. To get rid of it, call window.close() from anywhere, its own handlers included. For an app's secondary windows, such as a tool window, an inspector or a document, that should go away when closed.

Returns the window, so you can set it up further. To reach it later, keep window.ref(). Its get() returns null once the window is gone, and its is_open() tells bound UI when it closes. UI thread only.

Example:

auto about = std::make_unique<ui::Window>(ui::WindowOptions{.title = "About", .size = {320, 200}});
ui::Window& w = *about;
about->set_content(ui::Button{.text = "Close", .on_click = [&w] { w.close(); }});
ui::open_window(std::move(about));

quit¶

void quit(int exit_code = 0)

Header: winui/ui/App.hpp.

End the running loop (either run()) with exit_code. Posted, so the handler calling it returns first. UI thread only.

automation_children¶

std::vector<Element*> automation_children(const Element& node)

Header: winui/ui/AutomationTree.hpp.

The children an accessibility client sees under node, in navigation order.

A decorative node (Accessibility::decorative) or a NativeControl (automation_is_native_host()) is skipped, and its own children appear in its place as children of node. A collapsed node (Visibility::Collapsed) is left out with everything in it, since none of it is on screen. While node has a popup open, the popup's content comes last, unless that content names a closer parent through automation_parent_of(), as a submenu does with its item.

The returned pointers are non-owning and valid until the tree changes. Each call walks the tree again.

Example:

// The row only lays the buttons out, so it is marked decorative.
window.set_content(ui::VerticalStack{
    .content = {
        ui::Text{.text = "Unsaved changes"},
        ui::HorizontalStack{
            .accessibility = {.decorative = true},
            .content       = {ui::Button{.text = "Save"}, ui::Button{.text = "Discard"}},
        },
    },
});

// What a screen reader finds under the form: the text and both buttons, the row spliced out.
for (ui::Element* child : ui::automation_children(*window.content()))
{
    std::println("{}", child->automation_name()); // Unsaved changes, Save, Discard
}

automation_providers¶

AutomationProviders automation_providers(const Element& node)

Header: winui/ui/AutomationTree.hpp.

What an accessibility client can do with node: the provider for each pattern it supports now, null for the others (Element::automation_providers()). Screen readers reach a control through these, and a test can drive one the same way.

Example:

ui::CheckBoxControl check_box{"Remember me"};
if (ui::ToggleProvider* toggle = ui::automation_providers(check_box).toggle)
{
    toggle->toggle_next(); // as a screen reader's Toggle does
}

automation_parent¶

Element* automation_parent(const Element& node)

Header: winui/ui/AutomationTree.hpp.

The nearest ancestor that automation_children() would not skip, or nullptr at the root. It is the inverse of automation_children(): automation_parent(*child) is the node whose automation_children() lists child.

Example:

// Continuing the automation_children() example: with Save or Discard focused, the node above
// it is the form, because the decorative row between them is skipped.
if (ui::Element* focused = window.focused())
{
    ui::Element* group = ui::automation_parent(*focused); // window.content()
}

automation_focus¶

Element* automation_focus(Element* focused)

Header: winui/ui/AutomationTree.hpp.

The node a client sees as focused while focused has keyboard focus. That is the item the control names inside itself through Element::automation_focus(), followed as far as it goes (for a menu bar, the item in its open menu), or else focused itself. Returns nullptr for nullptr.

automation_role_name¶

const char* automation_role_name(AutomationRole role)

Header: winui/ui/AutomationTree.hpp.

A role's name as describe_automation() prints it: "Button", "TreeItem".

automation_value¶

AutomationValue automation_value(const Element& node, AutomationProperty property)

Header: winui/ui/AutomationTree.hpp.

The value of property on node now.

describe_automation¶

std::string describe_automation(const Element& root)

Header: winui/ui/AutomationTree.hpp.

A text dump of the accessibility tree rooted at root, the same on every machine and resolution. It has one line for root and one for each node automation_children() reports below it, indented two spaces per level. A line holds the role, the quoted name if it is not empty, # and the Accessibility::automation_id if one is set, and a bracketed list of the supported patterns if there are any. Every line ends in \n.

It does for accessibility what describe() does for rendering, and makes a stable check of what a screen reader sees in a test, with no window or accessibility client needed.

Example:

// Print what a screen reader sees of a window, e.g. while giving a custom control its role.
window.set_content(ui::VerticalStack{
    .content = {
        ui::Button{.text = "Save"},
        ui::CheckBox{.text = "Remember me"},
    },
});
std::print("{}", ui::describe_automation(*window.content()));
// Group
//   Button "Save" [Invoke]
//   CheckBox "Remember me" [Toggle=Off]

clipboard¶

Clipboard& clipboard()

Header: winui/ui/Clipboard.hpp.

The system clipboard, one for the whole process. It works from the first call, before any window exists. On a platform with no clipboard, it is an in-memory one. Use it on the UI thread.

Example:

ui::Property<std::string> report{"All tests passed"};
ui::ButtonControl         copy_button{"Copy report"};
copy_button.on_click([&] { ui::clipboard().set_text(report.get()); });

standard_command¶

Command standard_command(StandardCommand kind, CommandHandler execute = {}, Binding<bool> enabled = true)

Header: winui/ui/Command.hpp.

A Command with the standard text, symbol, shortcut and description of kind, running execute while enabled. Delete is "Delete", Symbol::Delete, the Delete key and "Delete the selected content". The text and description come from strings().commands and follow set_strings(). Any field set afterwards, before a control uses the command, wins.

Example:

ui::Property<bool> has_selection{false};
// Text "Delete", Symbol::Delete, the Delete key and the description come with the kind;
// the app adds what deleting means and when it is possible.
const ui::Command del = ui::standard_command(ui::StandardCommand::Delete,
                                             [&](std::string_view item) { remove_item(item); },
                                             has_selection);

// The button's text, icon, tooltip, shortcut and enabled state all come from `del`:
window.set_content(ui::CommandBar{
    .primary = {ui::AppBarButton{.command = del, .command_parameter = "List item 3"}},
});

on_ui_thread¶

UiThreadHop on_ui_thread(WindowRef window) noexcept

Header: winui/ui/Coroutine.hpp.

co_await ui::on_ui_thread(home) resumes the coroutine on the UI thread of the Window that home was taken from. Take home with Window::ref() on the UI thread, before the work starts. The resumption goes through Window::post(), so it runs inside the next tick(), ahead of on_tick(). It never resumes at once, even when the coroutine is already on the UI thread. Callable from any thread, also after the Window was destroyed, and it never reaches a new Window built at the old one's address.

When the window is closed or destroyed before that tick, the work is dropped and the coroutine never resumes. Its frame is destroyed instead, which runs the destructors of its locals, so nothing leaks. The frame is destroyed on the thread that dropped the work: - the awaiting thread, when the window was already closed or destroyed - the UI thread, when the window closes while the work is queued - the destroying thread, when the Window is destroyed while the work is queued

A coroutine that has to clean up after itself does it in a destructor, such as an RAII guard, since code after the co_await may never run. Anything that awaits this coroutine in turn never resumes either.

Example:

ui::FireAndForget refresh(ui::Window& window, ui::Property<std::string>& status)
{
    const ui::WindowRef home = window.ref(); // still on the UI thread
    co_await ui::on_background();
    std::string text = fetch_status();
    co_await ui::on_ui_thread(home);
    status = std::move(text); // the property's observers run on the UI thread
}

background_scheduler¶

Scheduler& background_scheduler()

Header: winui/ui/Coroutine.hpp.

The Scheduler on_background() uses when given none. It has one worker per hardware thread, is created on first use and is never destroyed. Its workers end with the process, so a coroutine waiting on it at exit is not resumed. A coroutine that hops back to a destroyed Window is dropped (see on_ui_thread()).

on_background¶

BackgroundHop on_background(Scheduler& scheduler) noexcept

Header: winui/ui/Coroutine.hpp.

co_await ui::on_background(scheduler) resumes the coroutine on one of scheduler's workers. Code running there must not touch the UI tree. In Scheduler::Inline mode it resumes at once on the calling thread. Every job queued on a Scheduler runs, also when the scheduler is destroyed, so a coroutine waiting here is always resumed.

Example:

ui::Scheduler pool{2};
auto work = [&]() -> ui::FireAndForget {
    co_await ui::on_background(pool);
    crunch();
};
work();

on_background¶

BackgroundHop on_background()

Header: winui/ui/Coroutine.hpp.

co_await ui::on_background() resumes the coroutine on a worker of background_scheduler(). It is meant for work that keeps a CPU busy. A long blocking wait, such as on a socket or a sleep, holds a worker the whole time, so give that its own Scheduler or thread.

The default pool is never joined, so work can still run on it after main() returned and the Window it hops back to is gone. on_ui_thread() then drops the coroutine. Anything else the coroutine refers to has to outlive it, or must not be touched after that hop.

set_jump_list¶

void set_jump_list(std::vector<JumpTask> tasks)

Header: winui/ui/JumpList.hpp.

Sets the app's jump list, the menu the system shows on a right-click on the app's taskbar button or its entry in Start. tasks go in its Tasks section, in this order, above the Recent section that ui::add_recent_file() fills. An empty list removes the tasks.

A task starts the app again. That second start usually hands its arguments to the instance already running through ui::claim_single_instance() and exits. The system stores the list, and it stays after the app quits until the next call replaces it. The list belongs to the app's taskbar button. When the app has set its own app identity, it is that identity's list, which the app's notifications also use. Otherwise it is the executable's. A system without jump lists ignores the call.

Example:

ui::set_jump_list({
    ui::JumpTask{.title = "New window", .arguments = "--new-window"},
    ui::JumpTask{.title = "New note", .arguments = "--new-note", .description = "Opens an empty note"},
});

add_recent_file¶

void add_recent_file(const std::filesystem::path& path)

Header: winui/ui/JumpList.hpp.

Records that the app opened the file at path, for the Recent section of its jump list and the system's list of recent files. The jump list shows it only for a file type the app is registered to open. Fire and forget. A system without the list ignores it.

Example:

if (const std::optional<std::filesystem::path> file = ui::pick_file(window))
{
    open_document(*file);
    ui::add_recent_file(*file);
}

launch_uri¶

void launch_uri(const std::string& uri)

Header: winui/ui/Launcher.hpp.

Opens uri with whatever app the OS has registered for it, fire and forget. An empty URI, or one nothing handles, does nothing.

Example:

window.set_content(ui::Button{.text = "Help", .on_click = [] { ui::launch_uri("https://example.com/help"); }});
ui::launch_uri("mailto:[email protected]"); // opens the mail client

launch_file¶

void launch_file(const std::filesystem::path& file)

Header: winui/ui/Launcher.hpp.

Opens file with the app registered for its type, as a double-click in the file manager does, fire and forget. An empty path, or one that does not exist, does nothing.

Example:

if (auto path = ui::pick_save_file(window, {.suggested_name = "report.pdf"}))
{
    save_document(*path);
    ui::launch_file(*path); // shows it in the PDF viewer
}

message_box¶

MessageBoxResult message_box(const Window& owner, const MessageBoxOptions& options)

Header: winui/ui/MessageBox.hpp.

Shows the operating system's own message box over owner and waits until the user answers. The owner is disabled meanwhile, and the app's other windows keep painting. The OS draws the box in its own style, whatever theme the app uses. For a box in the app's theme, use a ui::Dialog.

Example:

const ui::MessageBoxResult answer = ui::message_box(window,
    {.title   = "Notes",
     .heading = "Save changes to todo.txt?",
     .text    = "Your changes are lost if you don't save them.",
     .buttons = ui::MessageBoxButtons::YesNoCancel,
     .icon    = ui::MessageBoxIcon::Warning});
if (answer == ui::MessageBoxResult::Yes)
{
    save();
}

message_box¶

MessageBoxResult message_box(const MessageBoxOptions& options)

Header: winui/ui/MessageBox.hpp.

ui::message_box() without an owner window, for a message before any window exists (a failed start-up) or after the last one closed. The box gets a taskbar button of its own.

Example:

int start(bool config_loaded)
{
    if (!config_loaded)
    {
        ui::message_box({.title = "Notes",
                         .text  = "The settings file is damaged.",
                         .icon  = ui::MessageBoxIcon::Error});
        return 1;
    }
    return 0;
}

notify¶

void notify(Notification notification)

Header: winui/ui/Notification.hpp.

Shows a desktop notification, a toast in the corner of the screen that also goes to the notification center. The app needs no tray icon and no installer. The first call registers the program with the system under its own name, so the toast shows the executable's description (or its file name) and its icon. The user's notification settings decide whether it shows, and do-not-disturb holds it back. Fire and forget. A system without notifications shows nothing.

A click reaches on_click while the app runs. Once the app has quit, clicking the entry in the notification center only removes it.

Example:

ui::notify({.title    = "Export finished",
            .text     = "report.pdf was saved to Documents.",
            .on_click = [&] { window.activate(); }});

pick_file¶

std::optional<std::filesystem::path> pick_file(const Window& owner, const PickFileOptions& options = {})

Header: winui/ui/Pickers.hpp.

The system's "open file" dialog, modal to owner. Returns the chosen file, or nothing if the user canceled. Blocks until the dialog closes; the window keeps painting meanwhile. Throws std::invalid_argument for a malformed extension, index or folder.

Example:

ui::Property<std::string> file_name;
window.set_content(ui::Button{.text = "Open...", .on_click = [&] {
    if (auto path = ui::pick_file(window, {.title      = "Pick an image",
                                           .file_types = {{.name = "Images", .extensions = {".png", ".jpg"}}}}))
    {
        file_name = ui::path_to_utf8(path->filename());
    }
}});

pick_files¶

std::vector<std::filesystem::path> pick_files(const Window& owner, const PickFileOptions& options = {})

Header: winui/ui/Pickers.hpp.

As pick_file(), letting the user choose several files. Empty if the user canceled.

pick_save_file¶

std::optional<std::filesystem::path> pick_save_file(const Window& owner, const PickSaveFileOptions& options = {})

Header: winui/ui/Pickers.hpp.

The system's "save file" dialog, modal to owner. Returns the path to write, or nothing if the user canceled. It creates no file.

pick_folder¶

std::optional<std::filesystem::path> pick_folder(const Window& owner, const PickFolderOptions& options = {})

Header: winui/ui/Pickers.hpp.

The system's folder dialog, modal to owner. Returns the chosen folder, or nothing if the user canceled.

pick_folders¶

std::vector<std::filesystem::path> pick_folders(const Window& owner, const PickFolderOptions& options = {})

Header: winui/ui/Pickers.hpp.

As pick_folder(), letting the user choose several folders. Empty if the user canceled.

print¶

PrintResult print(const Window& owner, PrintJob job)

Header: winui/ui/Printing.hpp.

Shows the system print dialog over owner, where the user picks the printer, pages, copies and paper and sees a live preview of the pages. Then draws the pages the user chose and hands them to the printer as vector output, so text stays text. Blocks until the job is spooled, which is quick compared to the printing itself. The app's windows keep handling input and painting meanwhile.

print¶

PrintResult print(PrintJob job)

Header: winui/ui/Printing.hpp.

print() with no owner window.

draw_element¶

void draw_element(Renderer& renderer, Element& content, const Rect& area, const PrintContext& context)

Header: winui/ui/Printing.hpp.

Lays content out in area and draws it: a draw_page that prints controls or a built spec.

Example:

ui::print(window, ui::PrintJob{
    .title      = "Hello",
    .page_count = [](const ui::PrintPage&, const ui::PrintContext&) { return std::size_t{1}; },
    .draw_page  = [](ui::Renderer& renderer, const ui::PrintPage& page, const ui::PrintContext& context)
    {
        std::unique_ptr<ui::Element> sheet = ui::build(ui::Text{.text = "Hello", .role = ui::TextRole::Title});
        ui::draw_element(renderer, *sheet, page.printable, context);
    },
});

claim_single_instance¶

bool claim_single_instance(std::string_view id, Callback<void(InstanceActivation)> on_activated)

Header: winui/ui/SingleInstance.hpp.

Makes this process the one instance of the program named id for the user's session.

The first process to claim id gets true and keeps the claim until it exits. A later start that claims the same id hands its command line to the first, which receives it through on_activated on its UI thread, and gets false: it should exit without opening a window. The running instance is allowed to bring its window to the front from on_activated.

id names the program, not the executable: pick something unique to the app, such as "com.example.notes". Call it from the UI thread, before the first window opens. A process that already holds the claim gets true again.

Example:

int main()
{
    ui::Window window{{.title = "Notes"}};
    if (!ui::claim_single_instance("com.example.notes",
                                   [&window](ui::InstanceActivation started)
                                   {
                                       if (started.arguments.size() > 1)
                                       {
                                           open_document(started.working_directory /
                                                         ui::path_from_utf8(started.arguments[1]));
                                       }
                                       window.activate();
                                   }))
    {
        return 0; // the running Notes opens the file
    }
    return ui::run(window);
}

tray_flyout_options¶

WindowOptions tray_flyout_options(TrayFlyoutOptions options = {})

Header: winui/ui/TrayIcon.hpp.

The WindowOptions of a tray flyout: a bare, always-on-top popup with rounded corners and no taskbar button, created hidden, that hides instead of closing. Construct an ordinary Window with it and hand that window to TrayIconOptions::flyout.

Example:

ui::Window flyout{ui::tray_flyout_options({.title = "Timer", .width = 320.0f})};

place_tray_flyout¶

Point place_tray_flyout(const Rect& anchor, const Rect& work_area, Size size, float margin)

Header: winui/ui/TrayIcon.hpp.

Where a flyout of size goes, beside a tray icon at anchor on a monitor whose work area is work_area, in any unit as long as all four agree. Returns the top-left. The taskbar is on the edge of the work area that the anchor lies outside of. The flyout sits margin inside that edge, centered on the anchor along it and kept margin clear of the corners. An anchor inside the work area, such as one in the overflow flyout or an empty rect, is treated as a bottom taskbar.

Public for an app that places a window of its own the same way.

Example:

// A notes window of the app's own, opened beside the tray icon the way a flyout is. `icon` is
// the icon's rect in screen DIPs, wherever the app got it from.
ui::Window     notes{{.title = "Notes"}};
const ui::Rect icon{1000.0f, 1040.0f, 32.0f, 32.0f};
const ui::Size size{360.0f, 400.0f};
if (const std::optional<ui::Rect> work = notes.work_area())
{
    notes.resize(size);
    notes.move(ui::place_tray_flyout(icon, *work, size, 12.0f));
}
// With the icon at {1000, 1040, 32, 32} and a 1920x1032 work area above a bottom taskbar, the
// window goes to {836, 620}: centered on the icon, 12 DIPs above the taskbar.

line_break¶

Inline line_break()

Header: winui/ui/text/Inlines.hpp.

A line break: an Inline holding only \n.

to_layout_paragraphs¶

std::vector<TextLayoutParagraph> to_layout_paragraphs(const std::vector<Paragraph>& paragraphs, const TextStyle& base, int character_spacing, std::vector<const Inline*>* links = nullptr)

Header: winui/ui/text/Inlines.hpp.

Turns paragraphs into the runs a TextLayout lays out, with base as the block's style. Each run gets its inline's own formatting over base, and character_spacing. Links are underlined and tagged with their index in document order. When links is given, it receives the links in that order. Its pointers point into paragraphs and stay valid only as long as it does.