Layout.h

Overview

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();  // takes the rest of the row
 
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 in one layout pass on an upcoming frame. Geometry accessors like LayoutNode::bounds() report the updated layout once that pass completes.
• 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()

Go to the source code of this file.