docs

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:

C++
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:

C++
///
/// 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():

C++
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() and Container::Build() append children to the existing tree— calling either method a second time appends duplicate children. Call layout()->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:

C++
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():

C++
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:

C++
///
/// 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:

C++
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:

Overriding Container Layout

Pass a layout delegate to Container::SetLayoutOverride() when rows and columns cannot express your placement:

C++
///
/// 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:

C++
///
/// 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:

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.