Panels and containers for arranging web views across a window.
#include <AppCore/Layout.h>
The layout API arranges web content across an AppCore window using panels and containers. You declare sizes once, and the window recalculates the layout whenever it resizes or its display scale changes.
This example splits a window into a sidebar and a content pane:
RefPtr<Container> body = window->layout()->AddRow();
RefPtr<Panel> sidebar = body->AddPanel({ .size = "240px" });
RefPtr<Panel> content = body->AddPanel();
sidebar->view()->LoadURL("file:///sidebar.html");
content->view()->LoadURL("file:///content.html");
The Layout Tree
A window's tiled layout forms a tree rooted at Window::layout(). The root container is a column that spans the window's content area, holding child Panels and nested row or column Containers. Each Panel hosts one View, while containers manage the placement and sizing of their children.
Floating panels sit outside this tree in the window's Foreground layer, reached through Window::foreground(). They float above tiled panels without shifting the layout underneath, which suits overlays such as toasts, menus, and heads-up displays.
This diagram shows the relationship between a window, its tiled layout tree, and its floating layer:
Window
+- layout() Container (a column)
| +- Panel View
| +- Container (a row)
| +- Panel View
| +- Panel View
+- foreground() Foreground
+- Panel View
Where to Start
Choose the type that fits your layout task:
| Task | Type |
| Arrange views in rows or columns | Container |
| Host an individual web view | Panel |
| Float overlays above the layout | Foreground |
| Track bounds or listen for resizes | LayoutNode |
| Declare a whole layout in one expression | Window::BuildLayout() |
Rules for Layout Handles
Every container and panel handle follows these conventions:
- Call layout methods only on the main thread. Layout handles and tree mutations aren't thread-safe, so background threads must dispatch layout work through App::PostTask().
- A handle doesn't keep its node or window alive. Releasing a handle leaves its node in the tree, while calls on a handle after its node is removed or its window closes do nothing (see LayoutNode).
- Changes apply together at the next layout. Layout runs on the next geometry read (eg, LayoutNode::bounds()) or at the window's next frame, whichever comes first. Several changes made before then apply together, and geometry accessors always return up-to-date layout, except inside a layout delegate (see Container::SetLayoutOverride()).
- Mistakes log a warning rather than throwing. Disallowed actions do nothing and write a warning to the log.
- Note
- <AppCore/Window.h> already includes this header, so applications that create windows don't need to include <AppCore/Layout.h> directly.
- See also
- Window::layout(), Window::foreground(), Window::BuildLayout()