Spacer¶

Header: winui/ui/panels/Spacer.hpp. Spec: winui/ui/panels/Spacer.hpp.

A gap in a stack that takes the room the other children leave. Built by ui::Spacer.

A StackControl gives its children what they ask for along its axis and leaves the rest of its slot empty at the end. A spacer takes that rest instead, so the children after it are pushed to the far edge: a toolbar with its last button on the right is a horizontal stack with a spacer in front of that button. Several spacers share the room by their weight, together with the stack's fills (FillControl). Outside a stack a spacer is an empty element of its minimum size.

Example:

auto  bar    = std::make_unique<ui::StackControl>(ui::Orientation::Horizontal);
bar->add(std::make_unique<ui::ButtonControl>("Back"));
bar->add(std::make_unique<ui::SpacerControl>());
bar->add(std::make_unique<ui::ButtonControl>("Next"));

ui::Spacer¶

A flexible gap in a stack: it takes the room the other children leave along the stack, which pushes whatever comes after it to the far edge. Builds a ui::SpacerControl.

A stack gives each child what it asks for and leaves the rest of its slot empty at the end. Put a Spacer where that empty room should be instead. With several spacers the room is shared by .weight, together with the stack's ui::Fill children. Set a minimum gap with .min_width, or .min_height in a vertical stack. The stack needs more room than its children ask for, or there is nothing to share. A stack sized to its content has none.

Example:

// A toolbar: two buttons on the left, one on the right.
window.set_content(ui::HorizontalStack{
    .spacing         = 8,
    .child_alignment = ui::Alignment::Center,
    .content         = {
        ui::Button{.text = "New"},
        ui::Button{.text = "Open"},
        ui::Spacer{},
        ui::Button{.text = "Settings"},
    },
});

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

ui::Spacer{
    .weight, .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::SpacerControl; the caller owns it.

ui::SpacerControl¶

Derives from ui::Element.

A gap in a stack that takes the room the other children leave. Built by ui::Spacer.

A StackControl gives its children what they ask for along its axis and leaves the rest of its slot empty at the end. A spacer takes that rest instead, so the children after it are pushed to the far edge: a toolbar with its last button on the right is a horizontal stack with a spacer in front of that button. Several spacers share the room by their weight, together with the stack's fills (FillControl). Outside a stack a spacer is an empty element of its minimum size.

Example:

auto  bar    = std::make_unique<ui::StackControl>(ui::Orientation::Horizontal);
bar->add(std::make_unique<ui::ButtonControl>("Back"));
bar->add(std::make_unique<ui::SpacerControl>());
bar->add(std::make_unique<ui::ButtonControl>("Next"));

SpacerControl¶

SpacerControl() = default

A spacer of weight 1.

weight¶

float weight() const

This spacer's share of the leftover room, relative to the other spacers in the same stack.

set_weight¶

void set_weight(float weight)

Sets the share; negative is treated as 0. Updates the layout.

parallel_measure_safe¶

bool parallel_measure_safe() const override

True: measuring reads nothing at all.

measure_override¶

Size measure_override(Size, const MeasureContext&) const override

Nothing of its own: a spacer is as small as its minimum size until a stack stretches it.

render_override¶

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

Draws nothing.

Tests¶

• tests/test_stack.cpp