ui::IconSource¶

Header: winui/render/IconSource.hpp.

An icon as a value: a glyph, a symbol, a path or a picture, held by whatever shows an icon without hosting it as a child element.

Every control that shows an icon takes one in its icon field, and ui::Icon shows one on its own. Copyable and cheap to pass around. A Symbol, an IconGlyph and an ImageSource (a Bitmap, an SVG document or an animated image) convert to it implicitly; a path or a monochrome bitmap is made with path() and bitmap(). A default-constructed IconSource is empty and draws nothing.

A control draws it with draw_in_slot(): a glyph at the slot's glyph size, anything else fitted into the same square, so every kind of icon takes the room a glyph would.

Example:

ui::IconSource save_icon = ui::Symbol::Save;                            // a symbol
ui::IconSource share     = ui::IconGlyph{0xE72D};                       // a font glyph
ui::IconSource sigma     = ui::IconGlyph{0x03A3, "Candara", 20.0f};     // another font
ui::IconSource arrow     = ui::IconSource::path(*ui::PathGeometry::parse("F1 M 20,20L 24,10L 24,24L 5,24"));
ui::IconSource logo      = ui::IconSource::bitmap(ui::Bitmap::read_png("logo.png"));

window.set_content(ui::CommandBar{
    .primary = {
        ui::AppBarButton{.text = "Save", .icon = save_icon, .on_click = [] { save(); }},
        ui::AppBarButton{.text = "Share", .icon = share},
    },
});

// Drawing one yourself, from a render_override():
share.measure(measurer); // a glyph's box is measured (and cached) before draw()
share.draw(renderer, ui::Rect{0, 0, 20, 20}, theme.palette.text_fill_primary);

IconSource¶

IconSource() = default

No icon (a null IconSource).

IconSource¶

IconSource(IconGlyph glyph)

One glyph at glyph.size in glyph.font_family.

IconSource¶

IconSource(Symbol symbol)

The symbol's Segoe Fluent Icons glyph at 20px.

IconSource¶

template <typename P>
IconSource(P&& picture)
    requires std::convertible_to<P&&, ImageSource>

The picture as it is, from an ImageSource or anything that converts to one (a Bitmap, an SVG document, an animated image); the same as image().

empty¶

bool empty() const

True for a null IconSource (nothing to draw).

operator bool¶

operator bool() const

True when there is an icon; !empty().

glyph¶

const IconGlyph* glyph() const

The glyph for a font or symbol icon, else null. Points into this IconSource.

measure¶

Size measure(const TextMeasurer& measurer) const

The icon's own size before any ScaleToFit scales it. A glyph is measured with measurer and the result kept for draw(); everything else ignores it. Safe to call from a layout worker while another thread draws the same icon.

draw¶

void draw(Renderer& renderer, const Rect& box, const Color& foreground) const

Draws the icon into box as a Uniform ScaleToFit would: its natural size scaled to fit and centered. foreground colors a glyph, a path and a monochrome bitmap; a picture keeps its own colors. Copies of one IconSource may be drawn on several threads at once.

draw_in_slot¶

void draw_in_slot(Renderer& renderer, const Rect& box, const Color& foreground, float size = 0.0f, std::string_view symbol_font = {}) const

Draws the icon in a control's icon slot of size DIPs, centered in box: a glyph at size as draw_icon() draws it, anything else fitted into a size square as draw() does. A size of 0 is the glyph's own size, and fits anything else into box. symbol_font, when not empty, replaces the default symbol font of a glyph that names it (a theme's icon_font_family); a glyph from another font keeps its own.

slot_size¶

Size slot_size(float size = 0.0f) const

The room draw_in_slot() takes for size: a size square; for a size of 0 the glyph's own square, or the natural size of anything else.

extent¶

float extent(float fallback) const

The slot size a control gives this icon: a glyph's own size, or fallback for anything else (a control's icon size, so a picture takes the room a glyph would).

path¶

static IconSource path(PathGeometry data)

A path icon drawing data.

bitmap¶

static IconSource bitmap(Bitmap image, bool monochrome = true)

The picture, recolored to the foreground while monochrome (true by default). The foreground's RGB is drawn over the picture's own alpha.

image¶

static IconSource image(ImageSource source)

The picture as it is (an animated one shows its first frame).