ui¶

Namespace-scope declarations of ui from the rendering headers.

Enumerations¶

BevelSides¶

enum class BevelSides : std::uint8_t

Header: winui/render/Bevel.hpp.

Which edges of a bevel draw. Group boxes, status-bar panes and etched separators draw only some of the four. A bit set: combine with |.

ArrowDirection¶

enum class ArrowDirection : std::uint8_t

Header: winui/render/Bevel.hpp.

Which way a solid classic arrow points (draw_classic_arrow()).

Stretch¶

enum class Stretch

Header: winui/render/Bitmap.hpp.

How content is stretched into its destination rect. The Image element, Icon, PersonPicture, AnimatedVisualPlayer, ScaleToFit and the shapes read it; fit_stretch() does the math.

ImageOrientation¶

enum class ImageOrientation : std::uint8_t

Header: winui/render/Bitmap.hpp.

How a photo's stored pixels have to be turned to be seen upright: the EXIF orientation tag (TIFF tag 274). The values are the tag's own; the names say what the correction is, the way exiftool does. Rotations are clockwise.

PixelFormat¶

enum class PixelFormat : std::uint8_t

Header: winui/render/Bitmap.hpp.

How a Bitmap's bytes are laid out: 4 bytes per pixel, row-major, rows packed with no padding.

GradientAxis¶

enum class GradientAxis

Header: winui/render/Brush.hpp.

The direction a LinearGradientBrush runs across the painted bounds.

FillRoundedRectGradient honors all three. StrokeRoundedRectGradient, Fluent's elevation border, always runs vertically.

BrushMappingMode¶

enum class BrushMappingMode

Header: winui/render/Brush.hpp.

Whether a gradient's points are fractions of the painted shape's bounding box (0,0 its top-left, 1,1 its bottom-right) or DIPs from its top-left.

GradientSpreadMethod¶

enum class GradientSpreadMethod

Header: winui/render/Brush.hpp.

What a gradient paints past its last stop: the end colors held (Pad), the gradient mirrored (Reflect) or started over (Repeat).

FocusVisual¶

enum class FocusVisual

Header: winui/render/FocusRing.hpp.

Which focus visual a theme draws: Fluent's two solid rings, a classic single-color dotted rect, or Metro's interleaved black+white dashed pair.

ImageLoadState¶

enum class ImageLoadState

Header: winui/render/ImageSource.hpp.

Where an ImageSource made by ImageSource::load() is. Every other source is Loaded.

FillRule¶

enum class FillRule

Header: winui/render/PathGeometry.hpp.

Which parts of a self-intersecting or multi-figure geometry are inside. EvenOdd (the default, markup F0) alternates at every crossing; Nonzero (F1) counts winding direction.

PathSegmentKind¶

enum class PathSegmentKind

Header: winui/render/PathGeometry.hpp.

Which curve this segment is, and so which of the points it uses.

BorderStyle¶

enum class BorderStyle

Header: winui/render/Renderer.hpp.

How a control's border is drawn: the Fluent fill alone, or a classic 2 px bevel.

Flat and Rounded draw no separate border; the control's fill is the whole look. Raised and Sunken add the Windows 95/98/2000 light/dark bevel around the fill, drawn by draw_bevel_border().

PenLineCap¶

enum class PenLineCap

Header: winui/render/Renderer.hpp.

How an open end (or each dash end) of a stroke is finished.

PenLineJoin¶

enum class PenLineJoin

Header: winui/render/Renderer.hpp.

How a stroke turns a corner.

Pattern¶

enum class Pattern

Header: winui/render/Renderer.hpp.

A two-color stipple fill: the classic 50 % dither of a disabled glyph, a drag rubber band or a scrollbar trough. Only one pattern exists. The enum leaves room for others, such as hatches, without a breaking change.

GeometryAA¶

enum class GeometryAA

Header: winui/render/Renderer.hpp.

Whether shapes are drawn with hard pixel edges or antialiased. The classic themes, Windows 95 through Vista/7, use hard edges to match the original look. The Modern and high-contrast themes antialias.

TextAA¶

enum class TextAA

Header: winui/render/Renderer.hpp.

How text is antialiased, by era.

SpellingAction¶

enum class SpellingAction

Header: winui/render/SpellChecker.hpp.

What the checker suggests doing about one error.

Symbol¶

enum class Symbol : char32_t

Header: winui/render/Symbol.hpp.

Named icons for ui::Icon, AppBarButton and anything else taking an IconSource. Each value is the Segoe MDL2 Assets / Segoe Fluent Icons codepoint the symbol draws, so the enumerators need no further description.

A Symbol converts implicitly to an IconSource; symbol_glyph() turns one into an IconGlyph.

Example:

window.set_content(ui::CommandBar{
    .primary = {ui::AppBarButton{.text = "Save", .icon = ui::Symbol::Save},
                ui::AppBarButton{.text = "Share", .icon = ui::Symbol::Share}},
});

const ui::Rect search_rect{8.0f, 8.0f, 16.0f, 16.0f};
ui::draw_icon(renderer, ui::symbol_glyph(ui::Symbol::Find, 16.0f), search_rect, theme.palette.text_fill_primary);

TextAlign¶

enum class TextAlign

Header: winui/render/Text.hpp.

Where a text run sits inside the box it is drawn into, per axis (TextStyle::horizontal and TextStyle::vertical). Leading/Trailing are left/right horizontally and top/bottom vertically.

TextRole¶

enum class TextRole

Header: winui/render/Text.hpp.

The semantic role a run of text plays on a page: what TextControl::set_role() (and ui::Text::role) takes and Theme::TypeRamp::for_role() resolves against the active theme's fonts. Body is the default, so a plain, role-less TextControl reads as body text.

Example:

window.set_content(ui::VerticalStack{
    .spacing  = 8,
    .content  = {
        ui::Text{.text = "Settings", .role = ui::TextRole::Title},
        ui::Text{.text = "Changes apply immediately.", .role = ui::TextRole::Caption},
    },
});

TextEffectKind¶

enum class TextEffectKind

Header: winui/render/Text.hpp.

Which extra rendering pass a TextEffect applies. The classic disabled label is Emboss: the string is drawn twice, once in the highlight color offset by (1,1) and then in the shadow color at the origin, for an engraved look. None (the default) keeps a single plain pass.

TextWrapping¶

enum class TextWrapping

Header: winui/render/Text.hpp.

Whether a run breaks onto further lines when it meets the width it is laid out in. Wrap breaks between words, and inside a word too long for a line on its own. WrapWholeWords never splits a word and lets one that doesn't fit overflow instead. Explicit line breaks (\n) start a new line in either mode.

CharacterCasing¶

enum class CharacterCasing

Header: winui/render/Text.hpp.

How a text input control such as TextBox cases what the user types or pastes. Text already in the control and text set from code keep their case.

FontWeight¶

enum class FontWeight : std::uint16_t

Header: winui/render/Text.hpp.

Font weight classes, with their OpenType values. Metro's type hierarchy is carried almost entirely by weight, on a ramp a plain bool bold can't express: Header and Subheader are Light, Body is SemiLight, Title is SemiBold and Caption is Regular.

TextAlignment¶

enum class TextAlignment

Header: winui/render/TextLayout.hpp.

Where each line sits across the width the text is laid out in. Justify stretches every line but a paragraph's last (and one ended by a line break) to the full width by widening the gaps between its words.

Aliases¶

Brush¶

using ui::Brush = std::variant<Color, LinearGradientBrush, RadialGradientBrush, AcrylicBrush>

Header: winui/render/Brush.hpp.

Any paint a Shape's fill or stroke accepts: a solid Color or one of the brush structs. Renderer::draw_geometry() takes it; control chrome keeps plain Color.

RenderCommand¶

using ui::RenderCommand = std::variant<
   FillRoundedRect,
   StrokeRoundedRect,
   DrawTextRun,
   PushClip,
   PopClip,
   FillRoundedRectGradient,
   StrokeLine,
   StrokeRoundedRectGradient,
   SetRasterization,
   FillEllipse,
   StrokeEllipse,
   FillRectPattern,
   DrawImageNineSlice,
   DrawImage,
   PushClipEllipse,
   PushOpacityLayer,
   PopOpacityLayer,
   StrokeWavyLine,
   FillPolygon,
   PushTransform,
   PopTransform,
   DrawImageRect,
   DrawSvg,
   DrawGeometry,
   StrokePolyline,
   PushClipRoundedRect>

Header: winui/render/Renderer.hpp.

One recorded draw call: the data form of every Renderer method. TestRenderer::commands is a vector of these, and describe() prints one line per command.

Functions¶

operator|¶

BevelSides operator|(BevelSides a, BevelSides b)

Header: winui/render/Bevel.hpp.

The union of two side sets.

operator&¶

BevelSides operator&(BevelSides a, BevelSides b)

Header: winui/render/Bevel.hpp.

The intersection of two side sets.

has_side¶

bool has_side(BevelSides sides, BevelSides side)

Header: winui/render/Bevel.hpp.

True when sides includes any of the edges in side.

draw_bevel_border¶

void draw_bevel_border(Renderer& renderer, const Rect& bounds, BorderStyle style, const Color& light, const Color& highlight, const Color& shadow, const Color& dark_shadow, float step, BevelSides sides = BevelSides::All, bool soft = false, int rings = 2)

Header: winui/render/Bevel.hpp.

Draws a classic 3D border around bounds, two concentric rings of step width: Raised (a control at rest): the top and left get light outside highlight, the bottom and right get dark_shadow outside shadow. Sunken (a pressed or checked control): the same shape mirrored. The top and left get shadow outside dark_shadow, the bottom and right get highlight outside light. step is usually Theme::border_width, 1 DIP in every classic theme. sides picks which of the four edges draw (default: all). Any other BorderStyle draws nothing.

soft is the arrangement a push button is drawn with. It swaps the two top and left rings and leaves the bottom and right alone, so a soft raised button has highlight outside light on its lit side, where a window border has light outside highlight.

The outer ring runs the full length of each edge. The inner ring stops one step short at each corner where both adjoining edges draw, so the two rings nest without overlapping.

rings is how many of the two rings to draw. Every framed surface draws two. One draws the outer ring alone, the shape of a hot toolbar button. That shape takes the inner color pair on its one ring, so its caller passes light == highlight and dark_shadow == shadow. highlight and shadow go unread at rings == 1.

Every edge is a Renderer::stroke_line(): eight StrokeLine commands for a two-ring border on all four sides.

Example:

const ui::Color light       = ui::Color::from_rgba(223, 223, 223);
const ui::Color highlight   = ui::colors::White;
const ui::Color shadow      = ui::Color::from_rgba(128, 128, 128);
const ui::Color dark_shadow = ui::colors::Black;
const ui::Rect  bounds{0, 0, 75, 23};
const ui::Rect  pane{0, 0, 120, 20};

// A Windows 95 push button at rest, and the same button pressed.
ui::draw_bevel_border(renderer, bounds, ui::BorderStyle::Raised, light, highlight, shadow,
                         dark_shadow, 1.0f, ui::BevelSides::All, /*soft=*/true);
ui::draw_bevel_border(renderer, bounds, ui::BorderStyle::Sunken, light, highlight, shadow,
                         dark_shadow, 1.0f);

// A status-bar pane separator: the left and right edges only.
ui::draw_bevel_border(renderer, pane, ui::BorderStyle::Sunken, light, highlight, shadow,
                         dark_shadow, 1.0f, ui::BevelSides::Left | ui::BevelSides::Right);

draw_win3x_border¶

void draw_win3x_border(Renderer& renderer, const Rect& bounds, BorderStyle style, const Color& frame, const Color& highlight, const Color& shadow, float step, float radius = 0.0f)

Header: winui/render/Bevel.hpp.

Draws the Windows 3.x border around bounds, which is lopsided where draw_bevel_border() is symmetric:

raised: 1px frame on all four sides (outermost) 1px highlight on the top and left, inside it 2px shadow on the right and bottom, inside it pressed: 1px frame on all four sides 1px shadow on the top and left, and no bottom or right edge

Content inside this border sits off center, 2px in from the top and left and 3px from the right and bottom, which suits the era's pressed content offset of one pixel right and down.

radius rounds the frame only, for the push button, the era's one round-cornered surface. The highlight and shadow inside the frame stay straight. Pass 0 for every other surface. step is the width of the 1px units above, in DIPs. Flat and Rounded styles draw nothing.

Example:

const ui::Color frame     = ui::colors::Black;
const ui::Color highlight = ui::colors::White;
const ui::Color shadow    = ui::Color::from_rgba(128, 128, 128);
const ui::Rect  bounds{0, 0, 75, 23};
const bool      pressed = false;

// A Windows 3.1 push button: rounded frame, raised at rest, pressed while held.
const ui::BorderStyle style = pressed ? ui::BorderStyle::Sunken : ui::BorderStyle::Raised;
ui::draw_win3x_border(renderer, bounds, style, frame, highlight, shadow, 1.0f, /*radius=*/2.0f);

draw_classic_radio¶

void draw_classic_radio(Renderer& renderer, const Rect& box, const Color& light, const Color& highlight, const Color& shadow, const Color& dark_shadow, const Color& well, const std::optional<Color>& dot)

Header: winui/render/Bevel.hpp.

The classic radio button, drawn per device pixel at the target's own scale (Renderer::device_scale()): the sunken bevel made round, two one-pixel rings split along the diagonal from the top-right to the bottom-left corner, around a well disc.

outer ring: shadow on the top/left half, highlight on the bottom/right inner ring: dark_shadow on the top/left half, light on the bottom/right dot: dot, a disc a little under half the ring's width, when set

At 96 DPI the ring is 12 x 12 inside a 13 x 13 box, with the spare column on the left and the spare row at the bottom, and the dot is 4 x 4 with its corners cut, matching the classic radio button pixel for pixel. Larger scales draw the same shape at their own size (a 14 px ring at 125 %, 18 at 150 %, 20 at 175 %) instead of scaling the 12 px one. Each ring stays one device pixel wide up to 200 %, where it becomes two.

Example:

// A checked Windows 95 radio button.
ui::draw_classic_radio(renderer, ui::Rect{0, 0, 13, 13},
                       ui::Color::from_rgba(223, 223, 223), ui::colors::White,
                       ui::Color::from_rgba(128, 128, 128), ui::colors::Black,
                       ui::colors::White, ui::colors::Black);

draw_classic_arrow¶

void draw_classic_arrow(Renderer& renderer, const Rect& area, ArrowDirection direction, const Color& color, float depth = 4.0f)

Header: winui/render/Bevel.hpp.

The classic solid arrow: a 45-degree triangle depth DIPs deep with a base of 2 * depth - 1, centered in area and drawn per device pixel (Renderer::device_scale()), so its sides stay true diagonals at any scale. The default depth 4 is the 7 x 4 arrow every classic scroll bar, spin button, combo box and drop-down carries at 96 DPI.

Example:

// A combo box's drop button arrow, and a menu item's cascade arrow.
const ui::Rect button_rect{104, 2, 16, 17};
const ui::Rect cascade_rect{140, 0, 16, 18};
ui::draw_classic_arrow(renderer, button_rect, ui::ArrowDirection::Down, ui::colors::Black);
ui::draw_classic_arrow(renderer, cascade_rect, ui::ArrowDirection::Right, ui::colors::Black);

draw_classic_tree_button¶

void draw_classic_tree_button(Renderer& renderer, const Rect& area, bool expanded, const Color& frame, const Color& well, const Color& sign)

Header: winui/render/Bevel.hpp.

The classic tree view's expand button: a 9 x 9 box in a one-pixel frame around a well, holding a 5 px plus while collapsed or a minus while expanded, in sign. Centered in area and drawn per device pixel like draw_classic_arrow().

Example:

const ui::Rect chevron_rect{0, 0, 16, 16};
const bool     node_expanded = true;
ui::draw_classic_tree_button(renderer, chevron_rect, node_expanded,
                             ui::Color::from_rgba(128, 128, 128), ui::colors::White, ui::colors::Black);

swaps_axes¶

bool swaps_axes(ImageOrientation orientation)

Header: winui/render/Bitmap.hpp.

Whether orientation swaps width and height.

compare¶

ImageDiff compare(const Bitmap& a, const Bitmap& b, int threshold = 0)

Header: winui/render/Bitmap.hpp.

Compares two images. A pixel mismatches when any channel differs by more than threshold. Two images in different formats are compared as RGBA.

fit_stretch¶

Rect fit_stretch(const Rect& bounds, Size natural, Stretch stretch)

Header: winui/render/Bitmap.hpp.

Fits a natural (unstretched) size into bounds per stretch, returning the resulting centered destination rect. Renderer::draw_image() fits an image's pixel size the same way, and AnimatedVisualPlayer and AnimatedIcon use this to fit caller-drawn content. With UniformToFill and None the result may extend past bounds, so clip if that matters. A zero-area natural size returns bounds unchanged.

Example:

const ui::Rect dest = ui::fit_stretch(ui::Rect{0, 0, 200, 100}, ui::Size{50, 50},
                                            ui::Stretch::Uniform);
// dest == {50, 0, 100, 100}: scaled to the height and centered horizontally.

fit_within¶

std::pair<int, int> fit_within(int width, int height, int max_width, int max_height)

Header: winui/render/Bitmap.hpp.

The size width × height shrinks to inside max_width × max_height (zero: unconstrained), aspect ratio kept, rounded to whole pixels and never below 1. Never larger than the input. What Bitmap::scaled_to_fit() and the decoders size their output by.

stroke_rounded_rect_inside¶

void stroke_rounded_rect_inside(Renderer& renderer, const Rect& bounds, float corner_radius, const Color& color, float width)

Header: winui/render/Chrome.hpp.

Strokes a control's border so the whole ring lands inside bounds.

A stroke covers half its width on each side of its path, so a border centered on a control's rect puts half of itself outside it. A clipping parent, such as SwipeControl, cuts that outer half on all four sides, and under an aliased, pixel-snapped theme the remaining half pixel rounds away. A border drawn inside never extends past its layout slot, like the edges of draw_bevel_border() and draw_win3x_border().

The path moves in by half a stroke, and the radius with it, so the ring's outer edge stays on the rect and corner the caller asked for. width is in DIPs.

Example:

// A 2px outline whose outer edge sits exactly on bounds, corner radius 4.
const ui::Rect bounds{0, 0, 120, 32};
ui::stroke_rounded_rect_inside(renderer, bounds, 4.0f, theme.colors().text, 2.0f);

stroke_rounded_rect_gradient_inside¶

void stroke_rounded_rect_gradient_inside(Renderer& renderer, const Rect& bounds, float corner_radius, const LinearGradientBrush& brush, float extent_px, float width)

Header: winui/render/Chrome.hpp.

The gradient counterpart of stroke_rounded_rect_inside(), for Fluent's elevation border. extent_px keeps its meaning, because the renderer anchors it at the edge of the path it strokes, which moves in with it. See StrokeRoundedRectGradient for its sign.

draw_control_chrome¶

void draw_control_chrome(Renderer& renderer, const Rect& bounds, float corner_radius, const ButtonVisual& visual, float border_width, bool draw_flat_border_fallback = false, bool use_border_gradient = true)

Header: winui/render/Chrome.hpp.

Draws visual's background fill and border around bounds at corner_radius, in this order: 1. The background: visual.background_gradient if set (XP and Vista chrome), else a flat visual.background fill. 1. visual.inner_shadow if set (Aero's pressed state): two 2px bands fading out from the top and left edges, over the fill and under the border. No other theme sets it. 1. visual.inset_well if set (Aero's check box): a square rim and a square fill inside the well, both diagonal gradients, under the border. 1. The border, at most one of: a. A bevel when visual.border_style is Raised or Sunken (the 3.x through 2000 chrome): draw_win3x_border() when the visual has a bevel_frame, else draw_bevel_border(). Nothing is drawn after a bevel. b. Otherwise visual.border_gradient, if set and use_border_gradient is true: Fluent's elevation border on a button at rest or under the pointer. A check box's checked visual carries one too, and the check box passes use_border_gradient = false to leave it undrawn. c. Otherwise a flat stroke of visual.border, when draw_flat_border_fallback or visual.draw_border is true. Buttons pass false, so their pressed, disabled and subtle states stay borderless, and a button visual that wants an outline sets draw_border itself, as Metro's dark button does. A check box passes true, so its box always shows an outline when there's no bevel. b and c are stroked inside bounds (see stroke_rounded_rect_inside()). 1. visual.inner_border if set (Aero, Luna): an inner_border_width gradient ring stroked inside the rect the border leaves, at the radius less the border. It is the innermost layer, so it comes last.

Every border is drawn at visual.resolved_border_width(): a visual's own ButtonVisual::border_width overrides the theme-wide border_width passed here, so one theme can give a button a 2px outline and a check box none at the same time.

Text and content are the caller's to draw afterwards; the window draws the focus ring.

Example:

class MyButton : public ui::Element
{
    bool        pressed_ = false;
    std::string label_   = "OK";

    void render_override(ui::Renderer& renderer, const ui::RenderContext& context) const override
    {
        const ui::Theme&        theme = context.theme;
        const ui::ButtonVisual& v     = pressed_ ? theme.button_pressed : theme.button_normal;
        ui::draw_control_chrome(renderer, bounds(), theme.resolved_button_corner_radius(), v,
                                theme.border_width);
        renderer.draw_text(label_, bounds(), v.text, ui::TextStyle{});
    }
};

draw_disclosure¶

void draw_disclosure(Renderer& renderer, const Theme& theme, const IconGlyph& glyph, ArrowDirection classic, const Rect& area, const Color& color, float glyph_size = 0.0f)

Header: winui/render/Chrome.hpp.

An expand, collapse or drop-down mark in area: the icon font's glyph at glyph_size (0 for the glyph's own size) in theme.icon_font_family, or, under a theme whose disclosure_visual is ThemeDisclosureVisual::ClassicArrow, the era's solid 7 x 4 arrow pointing classic (draw_classic_arrow()). Every control with such a mark draws it through this call, so a theme changes all of them at once.

Example:

// An Expander's header mark: a chevron, or a solid arrow in the classic packs.
const bool     expanded = true;
const ui::Rect chevron_rect{200, 8, 16, 16};
ui::draw_disclosure(renderer, theme, expanded ? ui::glyphs::ChevronUp : ui::glyphs::ChevronDown,
                    expanded ? ui::ArrowDirection::Up : ui::ArrowDirection::Down, chevron_rect,
                    theme.colors().text, 12.0f);

fill_overlay_surface¶

void fill_overlay_surface(Renderer& renderer, const Theme& theme, const Rect& bounds, float corner_radius, const Color& fallback)

Header: winui/render/Chrome.hpp.

A popup's surface: theme.overlay_material (in-app acrylic) when the theme has one, drawn through Renderer::draw_geometry() with fallback as the color a renderer that cannot blur paints, and a plain fallback fill otherwise. fallback is the surface's solid color, usually theme.surfaces.menu. Acrylic blurs what was drawn before it, so fill the surface first, then draw its content.

Example:

// A custom flyout's background.
const ui::Rect bounds{0, 0, 240, 160};
ui::fill_overlay_surface(renderer, theme, bounds, theme.overlay_corner_radius, theme.surfaces.menu);

draw_border¶

void draw_border(Renderer& renderer, const Rect& bounds, const std::optional<Color>& background, const std::optional<Color>& border_brush, const Thickness& thickness, float corner_radius)

Header: winui/render/Chrome.hpp.

A bordered box's background and border, as a Border or a panel draws them: the background fills the rect inside the border, at the corner radius less the border, and the border is laid inside bounds. Either color may be absent, which draws nothing for that layer.

A uniform thickness strokes one rounded ring. A non-uniform one fills the four edges as straight bands, so a rounded corner between two different widths comes out square.

Example:

// What ui::BorderControl::render_override() does with its own properties.
const ui::Rect bounds{0, 0, 200, 120};
ui::draw_border(renderer, bounds, ui::Color::from_rgba(243, 243, 243),
                   ui::Color::from_rgba(0, 0, 0, 40), ui::Thickness{1}, 8.0f);

describe¶

std::string describe(const std::vector<RenderCommand>& commands)

Header: winui/render/Describe.hpp.

A stable text dump of a render-command stream: one line per command, fields in a fixed order, floats at two decimals, colors as #RRGGBBAA. Golden-file tests compare against it, since it doesn't depend on resolution, fonts or the operating system.

Image and SVG commands print their sizes, not their contents. ui::testing::describe() prints a whole window.

Example:

// A renderer of your own, an export backend say, can keep each call as a RenderCommand
// and log a frame in this format.
class ExportRenderer : public ui::Renderer
{
public:
    void fill_rounded_rect(const ui::Rect& bounds, float radius, const ui::Color& color) override
    {
        frame_.push_back(ui::FillRoundedRect{bounds, radius, color});
        // ... draw it ...
    }

    // After an element has rendered into it:
    void log_frame() const
    {
        std::println("{}", ui::describe(frame_));
        //   FillRoundedRect rect=(0.00,0.00,10.00,10.00) radius=2.00 color=`#FFFFFFFF`
    }

private:
    std::vector<ui::RenderCommand> frame_;
};

draw_dotted_rect¶

void draw_dotted_rect(Renderer& renderer, const Rect& bounds, const Color& color, float dash_length = 1.0f, float phase = 0.0f)

Header: winui/render/FocusRing.hpp.

Draws a 1px dotted rectangle around bounds. The caller insets bounds from the control's edges first, leaving a few pixels between the bevel or fill and the dots. Dots are dash_length-long strokes of color separated by an equal gap, starting phase into the first gap. The default, 1px dashes at phase 0, alternates every pixel like the classic focus rect. Metro's dashed pair (draw_focus_ring()) draws this twice, one dash apart, so one color's dashes land exactly in the other's gaps. Each dash is a Renderer::stroke_line().

Example:

// The classic focus rect, 4px inside a Windows 95 button.
const ui::Rect bounds{0, 0, 75, 23};
ui::draw_dotted_rect(renderer, bounds.inset(ui::Thickness{4}), ui::colors::Black);

draw_focus_ring_at¶

void draw_focus_ring_at(Renderer& renderer, const Rect& bounds, const Thickness& outward, float radius, const FocusRingStyle& style)

Header: winui/render/FocusRing.hpp.

Draws a focus visual at its own distance from each side of bounds. For the Fluent rings, the outer ring's outer edge lands outward outside bounds on each side, inside for a negative side. FocusRingStyle::margin, 3 on every side, is the usual distance, and the few controls that differ pass their own. Any other kind of focus visual is drawn around bounds, as draw_focus_ring() draws it.

Example:

// A check box rings box and label as one unit, 7 out at the sides and 3 above and below.
const ui::FocusRingStyle style = theme.focus_ring_style();
const ui::Rect           content_rect{0, 0, 120, 20};
ui::draw_focus_ring_at(renderer, content_rect, ui::Symmetric{.horizontal = 7.0f, .vertical = 3.0f}, 4.0f, style);

draw_focus_ring_rings¶

void draw_focus_ring_rings(Renderer& renderer, const Rect& bounds, float radius, const FocusRingStyle& style)

Header: winui/render/FocusRing.hpp.

Draws the Fluent two-ring focus visual, whatever style.kind says: a style.outer_width ring in style.outer_color whose outer edge lands style.margin outside bounds, and a style.inner_width ring in style.inner_color touching it on the inside. Both follow the control's corner radius, adjusted for each ring's distance, so the band stays concentric with the control's rounding. Use it instead of draw_focus_ring() in a control whose classic dotted rect needs other bounds than its rings, such as CheckBox.

Example:

// CheckBox: the modern ring hugs the box, while the classic dotted rect wraps the label.
const ui::FocusRingStyle style = theme.focus_ring_style();
const ui::Rect           box_rect{0, 0, 20, 20};
const ui::Rect           label_rect{28, 0, 80, 20};
if (style.kind == ui::FocusVisual::FluentRings)
{
    ui::draw_focus_ring_rings(renderer, box_rect, 4.0f, style);
}
else
{
    ui::draw_focus_ring(renderer, label_rect, 0.0f, style);
}

draw_focus_ring¶

void draw_focus_ring(Renderer& renderer, const Rect& bounds, float radius, const FocusRingStyle& style)

Header: winui/render/FocusRing.hpp.

Draws the focus visual style.kind calls for around bounds, at the control's corner radius: ClassicDotted: a dotted rect inset 4px (draw_dotted_rect()). MetroDashedPair: the same inset rect drawn twice, outer_color at phase 0 and inner_color at phase style.dash_length, so one color's dashes fill the other's gaps. FluentRings: draw_focus_ring_rings(). Every focusable control except CheckBox uses the same bounds for all three, so this is the one call most render_override() implementations need.

Example:

class MyControl : public ui::Element
{
    void render_override(ui::Renderer& renderer, const ui::RenderContext& context) const override
    {
        // ... the control's own drawing ...
        if (is_focused() && focus_visible())
        {
            const ui::Theme& theme = context.theme;
            ui::draw_focus_ring(renderer, bounds(), theme.corner_radius, theme.focus_ring_style());
        }
    }
};

draw_icon¶

void draw_icon(Renderer& renderer, const IconGlyph& glyph, const Rect& bounds, const Color& color, float size_override = 0.0f, std::string_view font_family = {})

Header: winui/render/IconGlyph.hpp.

Draws glyph centered in bounds through Renderer::draw_text(), in color at size_override (or glyph.size when size_override is 0, the default).

font_family, when not empty, overrides the glyph's own family. A theme picks its era's symbol font this way through Theme::icon_font_family: Segoe MDL2 Assets or Segoe Fluent Icons, which draw the same codepoints in two styles.

Example:

// InfoBar's icon: a filled circle, then the symbol on top, both at 16.
const ui::Rect  icon_rect{12, 14, 16, 16};
const ui::Color severity_color = ui::Color::from_rgba(196, 43, 28);
ui::draw_icon(renderer, ui::glyphs::CircleFill, icon_rect, severity_color, 16.0f, theme.icon_font_family);
ui::draw_icon(renderer, ui::glyphs::Important, icon_rect, ui::colors::White, 16.0f, theme.icon_font_family);

draw_drop_shadow¶

void draw_drop_shadow(Renderer& renderer, const Rect& bounds, float radius, const ShadowRecipe& recipe)

Header: winui/render/OverlayShadow.hpp.

Draws recipe's two shadows behind a surface occupying bounds (a rounded rect at radius). Call before drawing the surface's own background so its fill paints over the shadow's center.

Renderer has no blur, so each shadow is a stack of up to eight nested fill_rounded_rect() calls whose alphas composite to a Gaussian edge. The shadow reaches up to one blur radius past bounds, so leave room there or don't clip it. A recipe that doesn't cast draws nothing.

Example:

const ui::Rect bounds{16, 16, 200, 32};
ui::draw_drop_shadow(renderer, bounds, theme.overlay_corner_radius,
                     ui::ShadowRecipe::for_elevation(ui::elevation_z::ToolTip, theme.dark));

draw_aero_popup_shadow¶

void draw_aero_popup_shadow(Renderer& renderer, const Rect& bounds, float radius)

Header: winui/render/OverlayShadow.hpp.

Aero's popup drop shadow, separate from the Fluent recipe above. Aero has no elevation scale and casts no shadow under a button, card or panel. It casts this one only, under a menu, submenu, tooltip, combo box drop-down or toolbar overflow.

The shape: the popup's own rect moved 5 px right and down and filled #71000000. The whole shadow lies inside that rect: a solid center 5 px in from each side, wrapped in a 5 px fall-off band, with round corners at radius + 5. Because the rect moves by exactly the band width, the top and left bands land under the popup, and a user sees a 5 px shadow down the right and along the bottom. A caller reserves a 5 px strip on the right and bottom of the popup for it.

Example:

// Under a Vista menu popup, before its own background and border.
const ui::Rect popup_bounds{0, 0, 180, 120};
ui::draw_aero_popup_shadow(renderer, popup_bounds, 0.0f);
renderer.fill_rounded_rect(popup_bounds, 0.0f, theme.surfaces.menu);

draw_overlay_shadow¶

void draw_overlay_shadow(Renderer& renderer, const Rect& bounds, float radius, bool dark, float z = elevation_z::Flyout)

Header: winui/render/OverlayShadow.hpp.

Draws a popup's drop shadow. A light-dismiss surface (Flyout, MenuFlyout, the ComboBox popup) sits at elevation 32, the default z. A tooltip is the one popup that sits a step lower, at elevation_z::ToolTip. dark picks the dark-theme alphas; pass theme.dark.

Example:

const ui::Rect flyout_bounds{0, 0, 240, 160};
ui::draw_overlay_shadow(renderer, flyout_bounds, theme.overlay_corner_radius, theme.dark);
renderer.fill_rounded_rect(flyout_bounds, theme.overlay_corner_radius, theme.surfaces.menu);

svg_natural_size¶

Size svg_natural_size(std::string_view markup)

Header: winui/render/SvgImage.hpp.

The natural size of an SVG document's root element, as SvgImage's constructor reads it. Lengths may be unitless or in px, pt, pc, in, cm or mm (CSS's 96 px per inch); percentages and font-relative units count as absent.

symbol_glyph¶

IconGlyph symbol_glyph(Symbol symbol, float size = 20.0f)

Header: winui/render/Symbol.hpp.

The glyph an icon draws for symbol: its codepoint at 20 DIPs, or at size DIPs. The family is Segoe Fluent Icons; draw_icon()'s font_family can swap in the era's font.

text_analyzer¶

const TextAnalyzer& text_analyzer()

Header: winui/render/TextAnalyzer.hpp.

The analyzer in use: the one a host installed with set_text_analyzer(), or the built-in one. Never null; the reference stays valid while the installed analyzer lives.

set_text_analyzer¶

void set_text_analyzer(const TextAnalyzer* analyzer)

Header: winui/render/TextAnalyzer.hpp.

Installs analyzer process-wide; not owned, and it has to outlive its use. nullptr goes back to the built-in one. The library installs the platform's analyzer at start-up.

code_point_at¶

char32_t code_point_at(std::string_view text, std::size_t pos)

Header: winui/render/TextAnalyzer.hpp.

Decodes the UTF-8 code point starting at byte pos, or 0 at the end.

code_point_before¶

char32_t code_point_before(std::string_view text, std::size_t pos)

Header: winui/render/TextAnalyzer.hpp.

Decodes the UTF-8 code point that ends at byte pos, or 0 at the start.

word_run¶

std::pair<std::size_t, std::size_t> word_run(std::string_view text, std::size_t pos, bool stop_at_line_break)

Header: winui/render/TextAnalyzer.hpp.

The run around pos whose code points all agree with the one at pos (the one before it at the end) on text_analyzer().is_word_char(): a word, or the spaces and punctuation between two. What a double-click selects. With stop_at_line_break the run never extends across a '

'. Returns the half-open byte range {start, end}; {0, 0} for empty text.

previous_word_start¶

std::size_t previous_word_start(std::string_view text, std::size_t pos)

Header: winui/render/TextAnalyzer.hpp.

Where Ctrl+Left goes from pos: back over white space, then to the start of the word (or the run of punctuation) before it.

next_word_start¶

std::size_t next_word_start(std::string_view text, std::size_t pos)

Header: winui/render/TextAnalyzer.hpp.

Where Ctrl+Right goes from pos: past the word (or the run of punctuation) at it, then past the white space after it, to the start of the next.