Laying Out Panels
Arrange web views into rows, columns, and resizable split panes inside an AppCore window.
On this page
You can arrange multiple web views across an AppCore window using a tree of panels and containers. Each panel hosts a single view, while containers organize them into rows and columns.
You declare sizes once— the window re-resolves the layout whenever it resizes or its display scale changes.
Panels tile the window surface. To float overlays like toasts or dialogs above the layout, see Floating Panels.
Building the Layout
You can build a window layout step by step using panels and containers, or declare the entire tree at once.
Adding a Single Panel
Call Window::AddPanel() with no arguments to create a panel that fills the entire window:
window->AddPanel()->view()->LoadURL("file:///app.html");
Call Panel::view() to access the hosted View and load web content.
For the equivalent C functions, see AppCore in C.
Arranging Rows and Columns
Call Window::layout() to access the root container, then add child rows or columns to split the space:
///
/// Split the window into a fixed-width sidebar and a fluid content pane.
///
RefPtr<Container> body = window->layout()->AddRow({ .key = "body" });
RefPtr<Panel> sidebar =
body->AddPanel({ .key = "sidebar", .size = "240px", .min_size = "160px" });
RefPtr<Panel> content = body->AddPanel({ .key = "content" });
sidebar->view()->LoadURL("file:///sidebar.html");
content->view()->LoadURL("file:///content.html");
The window's root container is a column that fills the window. Calling Container::AddRow() or Container::AddColumn() nests containers inside it, while Container::AddPanel() appends a panel to host web content.
Setting a key on any node lets you look it up later using Window::FindPanel() or Container::Find().
Single-Expression Layouts
Declare an entire layout tree in a single expression using Window::BuildLayout() alongside panel(), row(), and column():
RefPtr<Panel> toolbar, sidebar, content;
window->BuildLayout({},
panel({ .key = "toolbar", .size = "44px", .fixed = true }, &toolbar),
row({ .key = "body", .resizable = true },
panel({ .key = "sidebar", .size = "240px" }, &sidebar),
panel({ .key = "content" }, &content)));
toolbar->view()->LoadURL("file:///toolbar.html");
Passing pointers to node handles populates them directly during construction, so you don't need to look them up by key later.
👍 Appending Layout Elements
Window::BuildLayout()andContainer::Build()append children to the existing tree— calling either method a second time appends duplicate children. Calllayout()->RemoveAll()first if you want to rebuild from a clean slate.
Sizing Panels
You can control how nodes share space across a container and let users resize panes with draggable dividers.
Sizing Panels and Containers
A child node accepts fixed, percentage, or flexible sizes along its parent container's axis:
| Value | Description |
|---|---|
"240px" or 240 |
Logical pixels. |
"30%" |
Percent of the container's free space. |
"2fr" |
Flex share of the free space. |
A child created without an explicit size receives a single flex share (1fr).
You can constrain child dimensions with min_size and max_size. Containers also accept gap and padding, which take values in logical pixels only.
To adjust sizes at runtime, call LayoutNode::SetSize(), LayoutNode::SetMinSize(), or LayoutNode::SetMaxSize(). Changes apply together at the next layout— layout runs on the window's next frame or during the next geometry read (such as LayoutNode::bounds()), whichever comes first. Reading LayoutNode::bounds() right after setting a size lays out the window immediately, so you get the updated rectangle without waiting for a frame.
Creating Resizable Split Panes
Set resizable = true on a container to place draggable dividers between its direct children:
RefPtr<Container> body =
window->layout()->AddRow({ .key = "body", .resizable = true });
Dragging a divider resizes the panes on either side. Double-clicking a divider restores both neighboring panes to their declared sizes.
You can set min_size to prevent drags from collapsing a pane, or set fixed = true on a child so divider drags never resize it.
Styling Dividers
Customize divider appearance across the window with Window::SetDividerStyle(), or per container with Container::SetDividerStyle():
window->SetDividerStyle({ .visual_thickness = 1, .color = "#3c3c3c" });
You can configure the pointer hit width, visual line thickness, line color, and hover highlight color. Leaving the line color unset paints no line, allowing the window background to show through.
Hiding and Removing Nodes
Call LayoutNode::Hide() to hide a node and redistribute its space to sibling nodes. Calling LayoutNode::Show() restores the node at its previous size.
Hiding a container hides its entire subtree. When a panel is hidden, its hosted View suspends painting and animations, and the page receives a visibilitychange event.
To detach a node, call Container::Remove() on its parent container. Removing a panel drops its reference to the hosted View, but any View you keep in a RefPtr survives and can be adopted into another panel with Container::AdoptPanel().
📘 Node Handle Lifetimes
Node handles reference nodes without keeping them or their window alive— releasing a handle does not remove the node. After a node is removed or its window closes, handles remain safe to use— mutations do nothing, and
Panel::view()returns null.
Embedding Custom Content
An empty container reserves layout space without painting anything, providing a dedicated region for native rendering (such as a 3D game viewport).
Tracking Region Bounds
Register a layout listener with LayoutNode::OnLayoutChange() to receive updated geometry whenever the node moves or resizes:
///
/// Reserve the right-hand pane for the engine's 3D viewport.
///
RefPtr<Container> viewport = body->AddColumn({ .key = "viewport" });
///
/// The callback fires for as long as viewport_tracker_ is kept.
///
viewport_tracker_ = viewport->OnLayoutChange([](LayoutNode& node) {
ResizeViewport(node.device_bounds());
});
LayoutNode::device_bounds() returns the node's rectangle in window back-buffer device pixels— the coordinate space your own drawing uses. LayoutNode::bounds() returns container-local logical pixels instead. Both methods return a zero rectangle before the node's first layout and after the node is removed.
The callback runs at the start of the app's next update (before AppListener::OnUpdate()), or right away during mouse input that changes layout, such as divider drags or double-click resets. It never runs from inside a geometry read. The callback fires at most once per node each time the library delivers layout changes, even if several layouts ran in between. You must store the returned LayoutCallback— destroying it unregisters the listener.
Drawing Beneath and Above Views
Implement WindowListener::OnPaint() to draw custom graphics above every view, or WindowListener::OnClear() to draw beneath them:
class Overlay : public WindowListener {
public:
///
/// Draws an opaque red 100 x 100 quad (device pixels) above every View.
///
void OnPaint(Window* window) override {
GPUDriver* driver = Platform::instance().gpu_driver();
uint32_t target = window->render_buffer_id();
if (!driver || !target)
return; // a CPU-rendered window
Vertex_2f_4ub_2f_2f_28f v[4] = {};
const float xs[4] = {0, 100, 100, 0};
const float ys[4] = {0, 0, 100, 100};
for (int i = 0; i < 4; i++) {
v[i].pos[0] = v[i].obj[0] = xs[i];
v[i].pos[1] = v[i].obj[1] = ys[i];
v[i].color[0] = v[i].color[3] = 255;
}
IndexType indices[6] = {0, 1, 3, 1, 2, 3};
///
/// v and indices must stay alive until EndSynchronize() returns.
///
VertexBuffer vertices = {VertexBufferFormat::_2f_4ub_2f_2f_28f,
sizeof(v), reinterpret_cast<uint8_t*>(v)};
IndexBuffer index_buffer = {sizeof(indices),
reinterpret_cast<uint8_t*>(indices)};
Matrix identity;
identity.SetIdentity();
Command cmd = {};
cmd.command_type = CommandType::DrawGeometry;
cmd.gpu_state.render_buffer_id = target;
cmd.gpu_state.viewport_width = window->device_width();
cmd.gpu_state.viewport_height = window->device_height();
cmd.gpu_state.transform = identity.GetMatrix4x4();
cmd.gpu_state.shader_type = ShaderType::Fill;
cmd.indices_count = 6;
driver->BeginSynchronize();
if (!geometry_id_) {
geometry_id_ = driver->NextGeometryId();
driver->CreateGeometry(geometry_id_, vertices, index_buffer);
} else {
driver->UpdateGeometry(geometry_id_, vertices, index_buffer);
}
cmd.geometry_id = geometry_id_;
driver->UpdateCommandList({1, &cmd});
driver->EndSynchronize();
}
private:
uint32_t geometry_id_ = 0;
};
WindowListener::OnClear() fires after the window background draws but before any view renders. WindowListener::OnPaint() fires after all views render, right before the frame is presented.
On GPU-rendered windows, draw through the library's GPU driver (Platform::instance().gpu_driver()). Wrap all resource updates and draw commands between GPUDriver::BeginSynchronize() and GPUDriver::EndSynchronize().
Allocate geometry and texture IDs with GPUDriver::NextGeometryId() and GPUDriver::NextTextureId() so they don't collide with IDs the library creates. Set each command's render buffer to Window::render_buffer_id(), with its viewport sized to Window::device_width() and Window::device_height().
The library draws your commands right after the callback returns, in order with the rest of the frame— this applies across all GPU drivers, including an Asynchronous GPU Driver.
Drawing Rules
Follow these rules when drawing from window callbacks:
- Keep buffer data alive until synchronization ends. Drivers may read vertex and index buffers during
GPUDriver::EndSynchronize()rather than when you pass them. - Don't count on persistent GPU state. The driver doesn't preserve state changes past the callback.
- Never present the frame yourself. The window presents the finished frame once all drawing completes.
- Destroy resources inside a synchronize pair. Free geometry and textures by calling
GPUDriver::DestroyGeometry()orGPUDriver::DestroyTexture()betweenGPUDriver::BeginSynchronize()andGPUDriver::EndSynchronize(). - Animate using
Window::Invalidate(). Calling this schedules the next frame without needing an update from a view. - Draw to the native surface on CPU windows. When
Window::render_buffer_id()returns0, draw directly onto the OS window surface instead of using the GPU driver.
Overriding Container Layout
Pass a layout delegate to Container::SetLayoutOverride() when rows and columns cannot express your placement:
///
/// Place a sidebar and a content pane from app state.
///
body->SetLayoutOverride([](Container& c, const Rect& box) {
c.child_at(0)->SetBounds(
Rect::FromXYWH(box.x(), box.y(), sidebar_width, box.height()));
c.child_at(1)->SetBounds(
Rect::FromXYWH(box.x() + sidebar_width, box.y(),
box.width() - sidebar_width, box.height()));
});
The delegate receives the container and its content box in container-local logical pixels (inside any container padding). Position each direct child inside this box using LayoutNode::SetBounds().
Delegate Execution
The delegate runs when the container resizes, when its display scale changes, or after you call Container::SetNeedsLayout(). It also runs when children are added, removed, or moved. Showing, hiding, or changing a child's options triggers it as well.
Moving a container without changing its size shifts its children along with it— the delegate does not run.
The delegate must produce the same placement for the same inputs— layout can run more often than strictly needed.
Application State Changes
Call Container::SetNeedsLayout() whenever application state read by your delegate changes:
///
/// Later: the user widens the sidebar.
///
sidebar_width = 320;
body->SetNeedsLayout();
This call marks the container stale so the delegate runs again at the next layout— either on the next geometry read or at the next frame. Without it, the delegate will not see your updated state.
Delegate Rules
Follow these rules when writing a layout delegate:
- Position children relative to the content box. The container and its ancestors already have their new geometry, but other nodes across the tree may still hold previous layout. Reading another node's geometry logs a warning in developer mode.
- Direct children update after the delegate returns. The container's children keep their previous placement until the callback finishes.
- Do not pump the event loop, open modal dialogs, or close the window. These operations must not run from inside a layout delegate.
- Do not mutate the container or its ancestors on every run. Changing the container or an ancestor on every pass prevents the layout from settling and causes the library to log a warning.
Managing Keyboard Focus
Clicking a panel grants it keyboard focus. To set focus programmatically, call Panel::Focus(). Attempting to focus a hidden panel is ignored with a warning.
To inspect which panel currently owns focus, call Window::focused_panel().
🚧 Focusing Panels
Never call
View::Focus()directly on a panel's view. Focusing the view directly prevents the window from routing keyboard input to the active panel.
For handling text input methods and on-screen keyboards, see Keyboard Focus and Editable State.