ui::ControlDescription¶

Header: winui/ui/ControlHeader.hpp.

The description an input control (TextBox, PasswordBox, NumberBox, AutoSuggestBox, RichEditBox, ComboBox) carries under itself. It draws wrapping text in the secondary text color and takes no room while empty. While the control's error is set, the error shows in its place in the critical color.

It works like ControlHeader, below the control instead of above it. measure() it along with the header, take its height out of the room the control measures in, and arrange() it off the bottom of the bounds.

Example:

class DescribedThing : public ui::Element
{
    ui::Size measure_override(ui::Size available, const ui::MeasureContext& context) const override
    {
        const ui::Size header      = header_.measure(available.width, context);
        const ui::Size description = description_.measure(available.width, context);
        const ui::Size under_head  = ui::ControlHeader::below(available, header);
        const ui::Size room        = ui::ControlHeader::below(under_head, description);
        const ui::Size body{120.0f, std::min(room.height, 32.0f)};
        return ui::ControlHeader::above(ui::ControlHeader::above(body, header), description);
    }
    void arrange_override(const ui::Rect&, const ui::ArrangeContext&) override
    {
        header_.arrange(*this);
        description_.arrange(*this); // bounds() is now the body's rect
    }

    ui::ControlHeader      header_{4.0f};
    ui::ControlDescription description_;
};

text¶

const std::string& text() const

The description text; empty (the default) collapses it entirely.

set_text¶

bool set_text(std::string text)

Returns whether the text changed, so the caller knows to mark itself dirty for layout and visuals.

error¶

const std::string& error() const

The error text; empty (the default) shows the description.

set_error¶

bool set_error(std::string error)

Returns whether the error changed, so the caller knows to mark itself dirty.

has_error¶

bool has_error() const

True while an error is set.

shown¶

const std::string& shown() const

What shows under the control: the error while one is set, else the description.

empty¶

bool empty() const

True while there is nothing to show: it takes no room and draws nothing.

measure¶

Size measure(float available_width, const MeasureContext& context) const

The room the description takes under the control, in DIPs. Zero when empty. It wraps at available_width when that is bounded (> 0).

arrange¶

void arrange(Element& control)

Takes the description (as last measured) off the bottom of control's bounds(), which are left as the control's own rect. Call it from the control's arrange_override(). A no-op while empty.

render¶

void render(Renderer& renderer, const Theme& theme, bool enabled) const

Draws the description where arrange() put it, in the secondary text color (the disabled color while the control is disabled), or the error in the critical color.