InfoBadge¶

Header: winui/ui/status/InfoBadge.hpp. Spec: winui/ui/status/InfoBadge.hpp.

A small non-interactive badge showing a number, an icon or a plain dot, typically over a navigation item or a button to flag new or pending items.

What it shows follows value() and icon(): a value shows the number; otherwise the icon if one is set; otherwise a dot. The fill comes from severity() (the accent by default) unless a local background() overrides it. The badge is squared whenever it would be narrower than tall, so a one-digit value is a circle, and its corners are always fully rounded.

Example:

// Declarative: an unread count bound to state, and a critical icon badge.
ui::Property<int> unread{5};
window.set_content(ui::HorizontalStack{
    .spacing  = 8.0f,
    .content  = {
        ui::InfoBadge{.value = unread},
        ui::InfoBadge{
            .severity = ui::InfoBadgeSeverity::Critical,
            .icon     = ui::InfoBadgeControl::severity_glyph(ui::InfoBadgeSeverity::Critical),
        },
    },
});

// Imperative:
auto  stack = std::make_unique<ui::StackControl>(ui::Orientation::Horizontal);
auto* badge = stack->add(std::make_unique<ui::InfoBadgeControl>(3));
badge->set_severity(ui::InfoBadgeSeverity::Attention);
badge->set_value(std::nullopt); // back to a dot

ui::InfoBadge¶

A small count, icon or dot badge. Builds a ui::InfoBadgeControl.

Example:

ui::Property<int> unread{3};

window.set_content(ui::HorizontalStack{
    .spacing  = 8,
    .content  = {
        ui::InfoBadge{.value    = unread},
        ui::InfoBadge{.severity = ui::InfoBadgeSeverity::Critical,
                      .icon     = ui::InfoBadgeControl::severity_glyph(ui::InfoBadgeSeverity::Critical)},
        ui::InfoBadge{}, // a plain dot in the accent color
    },
});

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

ui::InfoBadge{
    .value, .severity, .icon, .background, .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::InfoBadgeControl; the caller owns it.

ui::InfoBadgeControl¶

Derives from ui::Element.

A small non-interactive badge showing a number, an icon or a plain dot, typically over a navigation item or a button to flag new or pending items.

What it shows follows value() and icon(): a value shows the number; otherwise the icon if one is set; otherwise a dot. The fill comes from severity() (the accent by default) unless a local background() overrides it. The badge is squared whenever it would be narrower than tall, so a one-digit value is a circle, and its corners are always fully rounded.

Example:

// Declarative: an unread count bound to state, and a critical icon badge.
ui::Property<int> unread{5};
window.set_content(ui::HorizontalStack{
    .spacing  = 8.0f,
    .content  = {
        ui::InfoBadge{.value = unread},
        ui::InfoBadge{
            .severity = ui::InfoBadgeSeverity::Critical,
            .icon     = ui::InfoBadgeControl::severity_glyph(ui::InfoBadgeSeverity::Critical),
        },
    },
});

// Imperative:
auto  stack = std::make_unique<ui::StackControl>(ui::Orientation::Horizontal);
auto* badge = stack->add(std::make_unique<ui::InfoBadgeControl>(3));
badge->set_severity(ui::InfoBadgeSeverity::Attention);
badge->set_value(std::nullopt); // back to a dot

InfoBadgeControl¶

InfoBadgeControl() = default

A dot badge in the Default severity.

InfoBadgeControl¶

InfoBadgeControl(int value)

A badge showing value (clamped to >= 0).

value¶

std::optional<int> value() const

The number shown; unset (the default) shows the icon, or a dot when there is none.

set_value¶

void set_value(std::optional<int> value)

Sets the number (clamped to >= 0) or clears it. Does nothing if the clamped value is the current one.

severity¶

InfoBadgeSeverity severity() const

Which severity color the fill comes from; Default (the accent) by default.

set_severity¶

void set_severity(InfoBadgeSeverity severity)

Sets the severity; redraws.

icon¶

const IconSource& icon() const

The icon shown while value() is unset, sized to the badge: a glyph's code point and font at the badge's glyph size, or a path or picture fitted into the same square.

set_icon¶

void set_icon(IconSource icon)

Sets the icon; an empty source shows the plain dot while value() is unset.

background¶

const std::optional<Color>& background() const

A local fixed background, overriding the severity's color. nullopt when there is none or a theme resource is set.

background_resource¶

ThemeColor background_resource() const

The local background as a theme resource, or nullptr.

set_background¶

void set_background(std::optional<Color> background)

Sets or clears the local background and clears a theme-resource one; nullopt goes back to the severity's color. Redraws.

set_background¶

void set_background(ThemeColor resource)

Sets the local background to a theme resource, re-read under every theme, and clears a fixed one. Redraws.

parallel_measure_safe¶

bool parallel_measure_safe() const override

True: measuring reads only the badge's own state, the measurer and the theme.

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.

automation_name_fallback¶

std::string automation_name_fallback() const override

automation_name()'s fallback when accessibility().name is empty. Default: no inherent name, correct for controls with no visible text of their own (Slider, ProgressBar), which need an explicit accessibility().name from the caller. A control with its own visible text (Button, CheckBox, TextControl, ...) overrides this to return it.

severity_glyph¶

static IconGlyph severity_glyph(InfoBadgeSeverity severity)

The icon a severity shows: glyphs::InfoBadgeAttention for Attention, glyphs::InfoBarInformational for Informational, and glyphs::AcceptSymbol, glyphs::Important and glyphs::Cancel for Success, Caution and Critical. Default has no icon of its own and gets Attention's.

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().

Enumerations¶

InfoBadgeSeverity¶

enum class InfoBadgeSeverity

The severity a badge takes its background color from.

Tests¶

• tests/test_info_badge.cpp