Panel¶
Header: winui/ui/panels/Panel.hpp.
The shared base of the layout panels that own a list of children: Canvas, WrapPanel, TilePanel, RelativePanel and LayoutPanel.
A panel owns its children by std::unique_ptr and hands callers back non-owning observers. It draws an optional background behind the children, plus a border with corner radius and padding on the panels that publish them, and lists the children for every tree-wide walk. Children draw in render_order(), which is insertion order unless the panel overrides it. The window hit-tests them topmost first in that order, so a press reaches only the topmost child under it. orphan() takes a child back out alive. Panel cannot be constructed directly; derive from it and implement Element::measure_override() / arrange_override(), or use one of the panels above.
Example:
auto canvas = std::make_unique<ui::CanvasControl>();
canvas->set_background([](const ui::Theme& t) { return t.colors().background; });
canvas->set_background_transition(ui::BrushTransition{}); // blend on theme swaps
ui::ButtonControl* ok = canvas->add(std::make_unique<ui::ButtonControl>("OK"), 24.0f, 16.0f);
ok->on_click([] { /* ... */ });
for (const auto& child : canvas->children()) // insertion order
child->set_margin(ui::Thickness{4.0f});
window.set_content(std::move(canvas)); // the window takes ownership of the panel and its children
ui::Panel¶
Derives from ui::Element.
The shared base of the layout panels that own a list of children: Canvas, WrapPanel, TilePanel, RelativePanel and LayoutPanel.
A panel owns its children by std::unique_ptr and hands callers back non-owning observers. It draws an optional background behind the children, plus a border with corner radius and padding on the panels that publish them, and lists the children for every tree-wide walk. Children draw in render_order(), which is insertion order unless the panel overrides it. The window hit-tests them topmost first in that order, so a press reaches only the topmost child under it. orphan() takes a child back out alive. Panel cannot be constructed directly; derive from it and implement Element::measure_override() / arrange_override(), or use one of the panels above.
Example:
auto canvas = std::make_unique<ui::CanvasControl>();
canvas->set_background([](const ui::Theme& t) { return t.colors().background; });
canvas->set_background_transition(ui::BrushTransition{}); // blend on theme swaps
ui::ButtonControl* ok = canvas->add(std::make_unique<ui::ButtonControl>("OK"), 24.0f, 16.0f);
ok->on_click([] { /* ... */ });
for (const auto& child : canvas->children()) // insertion order
child->set_margin(ui::Thickness{4.0f});
window.set_content(std::move(canvas)); // the window takes ownership of the panel and its children
children_¶
The owned children in insertion order; derived panels read it in measure/arrange, append only through adopt_child() and remove only through remove_child()/clear_children().
children¶
The owned children in insertion order (not necessarily drawing order, see render_order()). The panel keeps ownership; the pointers stay valid for its lifetime.
background¶
The background, filled behind the children; nullopt (the default) draws nothing. Returns nullopt as well while a ThemeColor resource is set (see background_resource()).
background_resource¶
The theme resource the background is drawn from, or null when a fixed color (or nothing) is set. A ThemeColor is re-read whenever the panel is drawn, so it follows theme changes without a setter call (ui/BackgroundBrush.hpp).
set_background¶
Fixed background color; replaces any resource. Marks the panel for redraw.
set_background¶
Theme-resource background, e.g. [](const Theme& t) { return t.colors().background; }; replaces any fixed color. Marks the panel for redraw.
background_transition¶
With a transition set, a later change of what the background draws (a new color, or a resource under a new theme) blends from the color on screen (Animation.hpp's BrushTransition). nullopt (the default) changes it at once.
set_background_transition¶
Enables (or, with nullopt, disables) the background blend; takes effect on the next change.
orphan¶
Takes child out of the panel alive and hands it back, for adding somewhere else. Focus inside it is cleared. Null when it is not one of this panel's children.
for_each_child¶
Lists the children in insertion order, the order Tab visits them.
automation_children¶
The children in render_order(), not insertion order, so screen readers see them as they are stacked on screen (a Canvas's z-index), and hit_region() finds the topmost one.
Panel¶
Only derived panels construct a Panel; it starts empty, with no background or border.
adopt_child¶
Takes ownership of child, parents it and appends it. Returns the observer.
remove_child¶
Removes child, an observer adopt_child() returned, and lets it go. It is destroyed once the input or tick being handled has returned, since it may be the one whose handler asked for this. False when child is not one of this panel's children.
clear_children¶
Removes and lets go of every child, as remove_child() does each.
render_order¶
The children in drawing order, bottom first. Pointer input is hit-tested in the reverse, topmost first.
border_brush¶
The outline color; nullopt (the default) draws no border even with a non-zero border_thickness(). Nullopt as well while a ThemeColor is set.
border_brush_resource¶
The theme resource the border is drawn from, or null.
set_border_brush¶
A fixed outline color; replaces any resource. Marks the panel for redraw.
set_border_brush¶
An outline color read from the theme each time the panel is drawn; replaces any fixed color. Marks the panel for redraw.
border_thickness¶
The border width in DIPs per side (default zero); it insets the children like padding.
set_border_thickness¶
Sets the border width; marks the panel for layout and redraw.
corner_radius¶
The corner radius in DIPs, uniform for all four corners (default 0, square).
set_corner_radius¶
Sets the corner radius; marks the panel for redraw.
padding¶
The padding in DIPs between the border and the children (default zero).
set_padding¶
Sets the padding; marks the panel for layout.
content_inset¶
Border plus padding, the inset taken off every side.
render_override¶
Draws the background and border, then every child in render_order().
hit_test_children¶
The children in render_order(), topmost first.
tick_override¶
Advances the background transition, then ticks every child.
Tests¶
tests/test_layout_panels.cpp