Icon¶

Header: winui/ui/media/Icon.hpp. Spec: winui/ui/media/Icon.hpp.

A non-interactive icon: a symbol, a font glyph, a path, a bitmap or a picture.

It takes no input and no focus. Use it on its own or as part of a control's content, for example an icon beside a label in a Button. A glyph is drawn at its own size in the theme's symbol font, which is 20 DIPs for a Symbol. A path, a bitmap or a picture measures to its natural size and is fitted into the icon's box with its aspect ratio kept. size() makes any of them a square of that many DIPs. A glyph, a path and a monochrome bitmap take the theme's text color unless set_foreground() overrides it. A picture keeps its own colors. The declarative form is ui::Icon.

Example:

// Declarative: an icon-only button.
window.set_content(ui::Button{.content = ui::Icon{.source = ui::Symbol::Accept}});

// Imperative: icon + text as a Button's content.
auto button  = std::make_unique<ui::ButtonControl>();
auto content = std::make_unique<ui::StackControl>(ui::Orientation::Horizontal);
content->set_spacing(8.0f);
content->add(std::make_unique<ui::IconControl>(ui::Symbol::Save));
content->add(std::make_unique<ui::TextControl>("Save"));
button->set_content(std::move(content));

ui::Icon¶

An icon: a symbol, a font glyph, a path, a bitmap or a picture. Builds a ui::IconControl.

An icon carries no text, so give it an accessible name. Set .accessibility.decorative instead when a label next to it already says the same thing.

Example:

window.set_content(ui::HorizontalStack{
    .spacing = 8,
    .content = {
        ui::Icon{ .source = ui::Symbol::Save, .accessibility = { .name = "Save" } },
        ui::Icon{ .source = ui::IconGlyph{0xE77B}, .size = 16 },
        ui::Icon{ .source = ui::IconSource::path(*ui::PathGeometry::parse("M 0,0 L 12,6 0,12 Z")) },
        ui::Icon{ .source = ui::Bitmap::read("logo.png"), .size = 32 },
    },
});

Every field, in the order a designated initializer names them:

ui::Icon{
    .source, .size, .foreground, .style, .margin, .width, .height, .min_width, .min_height,
    .max_width, .max_height, .horizontal_alignment, .vertical_alignment, .visible, .tool_tip,
    .accessibility, .on_pointer_entered, .on_pointer_exited, .on_got_focus, .on_lost_focus,
    .on_key_down, .on_wheel, .control
}

Fields, in declaration order (designators must follow it):

Plus the common fields style, margin, width, height, min_width, min_height, max_width, max_height, horizontal_alignment, vertical_alignment, visible, tool_tip, accessibility every spec carries (conventions).

build¶

std::unique_ptr<Element> build()&&

Consumes the spec and returns the built ui::IconControl; the caller owns it.

ui::IconControl¶

Derives from ui::Element.

A non-interactive icon: a symbol, a font glyph, a path, a bitmap or a picture.

It takes no input and no focus. Use it on its own or as part of a control's content, for example an icon beside a label in a Button. A glyph is drawn at its own size in the theme's symbol font, which is 20 DIPs for a Symbol. A path, a bitmap or a picture measures to its natural size and is fitted into the icon's box with its aspect ratio kept. size() makes any of them a square of that many DIPs. A glyph, a path and a monochrome bitmap take the theme's text color unless set_foreground() overrides it. A picture keeps its own colors. The declarative form is ui::Icon.

Example:

// Declarative: an icon-only button.
window.set_content(ui::Button{.content = ui::Icon{.source = ui::Symbol::Accept}});

// Imperative: icon + text as a Button's content.
auto button  = std::make_unique<ui::ButtonControl>();
auto content = std::make_unique<ui::StackControl>(ui::Orientation::Horizontal);
content->set_spacing(8.0f);
content->add(std::make_unique<ui::IconControl>(ui::Symbol::Save));
content->add(std::make_unique<ui::TextControl>("Save"));
button->set_content(std::move(content));

IconControl¶

IconControl() = default

An icon with no source. It measures to nothing and draws nothing.

IconControl¶

IconControl(IconSource source)

An icon showing source.

source¶

const IconSource& source() const

The icon drawn. Empty by default.

set_source¶

void set_source(IconSource source)

Replaces the icon. Updates layout and redraws.

size¶

std::optional<float> size() const

The icon's size as a square of DIPs: a glyph's font size, or the square a path or picture is fitted into. nullopt (the default) is the glyph's own size, or the natural size of anything else.

set_size¶

void set_size(OptionalFloat size)

Sets or clears the size. Updates layout and redraws.

foreground¶

const Paint& foreground() const

The color of a glyph, a path or a monochrome bitmap: a fixed color or a theme resource. Unset (the default) is the theme's text color.

set_foreground¶

void set_foreground(Paint color)

Draws in color instead of the theme's text color. An empty Paint goes back to the theme's color. Redraws.

parallel_measure_safe¶

bool parallel_measure_safe() const override

Returns true, since measuring reads only the source's size.

automation_role¶

AutomationRole automation_role() const override

What screen readers and other assistive tools see of this node: the role, name, help text and children here, and what a client can do with the node through the providers automation_providers() lists (ui/Automation.hpp).

automation_role() is the role this node reports; Group by default.

measure_override¶

Size measure_override(Size available, const MeasureContext& context) const override

Implement these instead of measure() and arrange(). The base class has already applied margin, size limits and alignment by the time these run. measure_override() is pure (every concrete Element must size itself); arrange_override() defaults to a no-op since most leaves need nothing beyond having bounds() set, which the base already did.

render_override¶

void render_override(Renderer& renderer, const RenderContext& context) const override

What the control draws, in layout coordinates; render() has already applied the visual layer. A container draws its children through their render(), never their render_override().

Tests¶

• tests/test_styles.cpp