Skip to content

GroupBox

Header: winui/ui/containers/GroupBox.hpp. Spec: winui/ui/containers/GroupBox.hpp.

A header over a group of related controls, with the group framed.

Under Fluent, the header is TextRole::BodyStrong text above a card that holds the content. The card has a fill and a 1 DIP stroke at the theme's overlay corner radius, with 16 DIPs of padding. The other era themes draw a frame with the header breaking its top edge near the left corner. The frame is etched under Windows 9x and a single line under Aero, Luna and Windows 3.x and earlier, and Luna draws the header in blue. The content is inset as each era's guidelines say.

It takes no input and no focus of its own, so Tab moves straight to the controls inside. It groups only visually. Radio buttons inside still need a RadioGroup or a RadioButtons control to be exclusive.

Example: 

auto box = std::make_unique<ui::GroupBoxControl>("Appearance");
box->set_child(std::make_unique<ui::CheckBoxControl>("Show the status bar"));
window.set_content(std::move(box));

// Declaratively:
window.set_content(ui::GroupBox{
    .header  = "Appearance",
    .content = ui::CheckBox{.text = "Show the status bar"},
});

ui::GroupBox

A header over a group of related controls, with the group framed. Builds a ui::GroupBoxControl.

Example: 

window.set_content(ui::GroupBox{
    .header  = "Appearance",
    .content = ui::VerticalStack{
        .spacing = 8,
        .content = {
            ui::CheckBox{.text = "Show the status bar"},
            ui::CheckBox{.text = "Show line numbers"},
        },
    },
});

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

ui::GroupBox{
    .header, .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, .content
}

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

Field Type Default
header ui::Binding<std::string> The header text. Empty draws no header.
on_pointer_entered ui::Action The pointer moved onto the control.
on_pointer_exited ui::Action The pointer left the control.
on_got_focus ui::Action Keyboard focus arrived on the control, or on anything inside it, from outside it. A control with nothing focusable in it never gets focus, and never raises this.
on_lost_focus ui::Action Keyboard focus left the control and everything inside it.
on_key_down ui::Callback<ui::Handling(const ui::KeyEvent&)> A key pressed while focus is on the control or inside it, before the control's own handling; ui::Handled stops it there (Element::on_key_down()).
on_wheel ui::Callback<ui::Handling(const ui::PointerEvent&)> A wheel turn over the control, before the control scrolls; ui::Handled stops it there (Element::on_wheel()).
control ui::ControlOut<ui::GroupBox> Out: the handle that receives the built control.
content ui::Spec The grouped content.

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::GroupBoxControl; the caller owns it.

ui::GroupBoxControl

Derives from ui::ContentHost.

A header over a group of related controls, with the group framed.

Under Fluent, the header is TextRole::BodyStrong text above a card that holds the content. The card has a fill and a 1 DIP stroke at the theme's overlay corner radius, with 16 DIPs of padding. The other era themes draw a frame with the header breaking its top edge near the left corner. The frame is etched under Windows 9x and a single line under Aero, Luna and Windows 3.x and earlier, and Luna draws the header in blue. The content is inset as each era's guidelines say.

It takes no input and no focus of its own, so Tab moves straight to the controls inside. It groups only visually. Radio buttons inside still need a RadioGroup or a RadioButtons control to be exclusive.

Example: 

auto box = std::make_unique<ui::GroupBoxControl>("Appearance");
box->set_child(std::make_unique<ui::CheckBoxControl>("Show the status bar"));
window.set_content(std::move(box));

// Declaratively:
window.set_content(ui::GroupBox{
    .header  = "Appearance",
    .content = ui::CheckBox{.text = "Show the status bar"},
});

hit_test_transparent

bool hit_test_transparent() const override

Returns false, so the group box is hit anywhere in its bounds, even where it draws nothing.

GroupBoxControl

GroupBoxControl() = default

A group box with no header and no content.

GroupBoxControl

GroupBoxControl(std::string header)

A group box headed header.

const std::string& header() const

The header text. Empty draws no header, and the frame or card starts at the top.

set_header

void set_header(std::string header)

Sets the header text. Updates layout and redraws.

automation_name_fallback

std::string automation_name_fallback() const override

The header names the group when accessibility().name doesn't.

parallel_measure_safe

bool parallel_measure_safe() const override

Returns true, since measuring touches only the header text and the child.

measure_override

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

The child's desired size plus the header and the theme's frame or card insets.

arrange_override

void arrange_override(const Rect& final_rect, const ArrangeContext& context) override

Gives the child the rect inside the frame or card.

render_override

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

Draws the header and the frame or card, then the child.

Tests

  • tests/test_group_box.cpp