docs
Loading...
Searching...
No Matches
LayoutNode.h
Go to the documentation of this file.
1///
2/// Copyright (C) 2026 Ultralight, Inc. All rights reserved.
3/// A license is required for commercial use. https://ultralig.ht
4///
5#pragma once
6#include <AppCore/Defines.h>
10#include <Ultralight/RefPtr.h>
11#include <Ultralight/String.h>
12
13#include <concepts>
14#include <utility>
15
16namespace ultralight {
17
18class Container;
19class Panel;
20
21///
22/// Base class for Panel%s and Container%s in a window layout tree.
23///
24/// An AppCore window arranges web views and native drawing regions into a tree of rows and columns,
25/// where each node shares space along its parent container's axis. LayoutNode represents an
26/// individual element in that hierarchy, whether it's a Container grouping child nodes or a Panel
27/// hosting a single View.
28///
29/// You use node handles to manage panes and containers dynamically at runtime, adapting the
30/// interface without rebuilding the layout tree.
31///
32/// This helper toggles a sidebar panel on and off:
33///
34/// ```
35/// void ToggleSidebar(RefPtr<Panel> sidebar) {
36/// if (sidebar->is_hidden())
37/// sidebar->Show(); // back at its previous size
38/// else
39/// sidebar->Hide(); // its siblings take the space
40/// }
41/// ```
42///
43/// ## Showing and Hiding
44///
45/// Calling Hide() takes a node off screen and redistributes its space to sibling nodes, and Show()
46/// restores the node at its remembered size.
47///
48/// Hiding affects different node types:
49///
50/// - **Hiding a Container hides its entire subtree.**
51/// - **Hiding a Panel suspends its hosted View.** Painting and animations pause, and the page
52/// receives a `visibilitychange` event.
53///
54/// ## Declared Sizes
55///
56/// Call SetSize(), SetMinSize(), or SetMaxSize() to update a node's declared size constraints at
57/// runtime. In a resizable container, double-clicking an adjacent divider restores both neighboring
58/// panes to the declared sizes set here (discarding any divider drags made since).
59///
60/// ## Layout Geometry
61///
62/// Accessors report layout rectangles across different coordinate spaces:
63///
64/// - **bounds() returns container-local logical pixels.**
65/// - **device_bounds() returns window back-buffer device pixels.** Native rendering passes use this
66/// coordinate space to draw beneath or above web content.
67///
68/// Both accessors are always up to date, except inside a layout override (see
69/// Container::SetLayoutOverride()), where a read returns the layout in progress. After a change
70/// (eg, SetSize()), reading either one lays the window out first and returns the new geometry
71/// right away, without waiting for a frame.
72///
73/// Both accessors return a zero rectangle before the node's first layout and after the node is
74/// removed.
75///
76/// Read the new size right after a change, and register OnLayoutChange() to follow later changes:
77///
78/// ```
79/// sidebar->SetSize("320px");
80///
81/// // bounds() already holds the new rect here.
82/// float width = sidebar->bounds().width();
83///
84/// // Follow later changes too (eg, window resizes and divider drags):
85/// on_resize_ = sidebar->OnLayoutChange([](LayoutNode& node) {
86/// Log("sidebar is now " + std::to_string(node.bounds().width()) + "px wide");
87/// });
88/// ```
89///
90/// Callback registrations report geometry changes:
91///
92/// - **OnLayoutChange() fires when layout changes the node's bounds.** It runs at the start of the
93/// app's next update (before AppListener::OnUpdate()), or earlier during mouse input (eg, a mouse
94/// move or press over the window, a divider release), before the window routes that input. It
95/// never runs from inside a geometry read.
96/// - **OnUserResize() fires when a user resizes the node with a divider.** It fires on drag release
97/// and after a double-click restores declared sizes, only when the node's size changed.
98///
99/// Both methods return a LayoutCallback that manages the registration (destroying it unregisters
100/// the callback).
101///
102/// ## Node Lifetimes and Handles
103///
104/// A handle never keeps its node or its window alive (releasing one doesn't remove the node from
105/// the layout tree). To remove a node, call Container::Remove() or Foreground::Remove().
106///
107/// After a node is removed or its window closes, handles remain safe to call. Mutations do nothing,
108/// and accessors return safe fallback values.
109///
110/// Adding a child to a removed container or a closed window logs a warning and returns a handle
111/// that isn't attached to any window.
112///
113/// @note A View kept after its panel is removed loses its listeners-- register them again after
114/// adopting it into another panel.
115///
116/// @see Panel, Container, Container::Remove(), Foreground::Remove(), LayoutCallback
117///
119 public:
120 ///
121 /// Get the node's key (empty if unkeyed).
122 ///
123 virtual String key() const = 0;
124
125 ///
126 /// Get the node's parent container (null at the root or when detached).
127 ///
128 virtual RefPtr<Container> parent() const = 0;
129
130 ///
131 /// Get the node's index within its parent (-1 when detached).
132 ///
133 virtual int index() const = 0;
134
135 ///
136 /// Get this node as a Panel (null if it is not one).
137 ///
138 virtual RefPtr<Panel> AsPanel() = 0;
139
140 ///
141 /// Get this node as a Container (null if it is not one).
142 ///
144
145 ///
146 /// Hide the node and redistribute its space to its siblings.
147 ///
148 /// The node remembers its declared size, and Show() restores it.
149 ///
150 /// Hiding a Container hides its entire subtree.
151 ///
152 /// A hidden Panel's View stops rendering entirely-- painting and animations suspend. The page
153 /// receives a `visibilitychange` event.
154 ///
155 /// @note The `visibilitychange` event fires per panel rather than per window. Page code written
156 /// for tab-background semantics receives this event on every Hide() and Show().
157 ///
158 virtual void Hide() = 0;
159
160 ///
161 /// Show the node again, restoring its remembered size exactly.
162 ///
163 virtual void Show() = 0;
164
165 ///
166 /// Whether or not the node is hidden.
167 ///
168 /// This reports the node's own flag, so a node inside a hidden container still reports its
169 /// own state even though it is not on screen.
170 ///
171 virtual bool is_hidden() const = 0;
172
173 ///
174 /// Get the node's rect in container-local logical pixels.
175 ///
176 /// This is the same space SetBounds() takes.
177 ///
178 /// If anything changed since the last layout, the read lays the window out first.
179 ///
180 /// @note Returns a zero rect before the node's first layout and after the node is removed or
181 /// its window closes.
182 ///
183 virtual Rect bounds() const = 0;
184
185 ///
186 /// Get the node's rect in window back-buffer device pixels.
187 ///
188 /// This is the coordinate space your own drawing uses.
189 ///
190 /// If anything changed since the last layout, the read lays the window out first (the same as
191 /// bounds()).
192 ///
193 /// @note Returns a zero rect in the same cases as bounds().
194 ///
195 virtual IntRect device_bounds() const = 0;
196
197 ///
198 /// Place this node manually.
199 ///
200 /// @param bounds The node's new rect, in container-local logical pixels.
201 ///
202 /// @note This is only legal inside its container's layout delegate (see
203 /// Container::SetLayoutOverride()). Anywhere else it is a no-op with a warning.
204 ///
205 virtual void SetBounds(const Rect& bounds) = 0;
206
207 ///
208 /// Set the node's declared size along its container's axis.
209 ///
210 /// This acts like the size in the creation options-- double-clicking an adjacent divider
211 /// restores the node to the size declared here, discarding any user divider drags made since.
212 ///
213 /// @param size The new declared size. An unset Size means one flex share (`1fr`).
214 ///
215 /// @note A floating panel's size is fixed at creation. Calling SetSize(), SetMinSize(), or
216 /// SetMaxSize() on a floating panel does nothing and logs a warning.
217 ///
218 virtual void SetSize(Size size) = 0;
219
220 ///
221 /// Set the node's minimum size constraint.
222 ///
223 /// @param min_size The new minimum. An unset Length means no minimum.
224 ///
225 virtual void SetMinSize(Length min_size) = 0;
226
227 ///
228 /// Set the node's maximum size constraint.
229 ///
230 /// @param max_size The new maximum. An unset Length means no maximum.
231 ///
232 virtual void SetMaxSize(Length max_size) = 0;
233
234 ///
235 /// Register a callback fired when the user resizes this node with a divider.
236 ///
237 /// It fires on drag release, and again after a double-click resets the node to its declared
238 /// size. Either way it fires only when the node's size changed.
239 ///
240 /// @param callback The function to call. It receives `user_data` and this node.
241 ///
242 /// @param user_data Passed back to the callback on every fire (can be nullptr).
243 ///
244 /// @param destroy_user_data Called once when the registration drops `user_data` (can be
245 /// nullptr).
246 ///
247 /// @return Returns a LayoutCallback controlling how long the callback stays registered.
248 ///
249 /// @note Callbacks must not let exceptions propagate.
250 ///
251 [[nodiscard]] virtual LayoutCallback OnUserResize(
252 LayoutNodeCallback callback, void* user_data,
253 LayoutDestroyUserDataCallback destroy_user_data) = 0;
254
255 ///
256 /// Register a callback that fires after layout changes this node's bounds.
257 ///
258 /// Use this to follow a node's geometry (eg, a reserved region that your own drawing fills).
259 ///
260 /// The callback runs at the start of the app's next update (before AppListener::OnUpdate()). It
261 /// can run earlier during mouse input (eg, a mouse move or press over the window, a divider
262 /// release, a double-click reset), before the window routes that input. Mouse input delivers
263 /// every pending change, not only one the input caused (eg, a SetSize() call your code made
264 /// since the last update).
265 ///
266 /// The callback never runs from inside a geometry read (bounds(), device_bounds()).
267 ///
268 /// The callback fires once for all the layouts that ran since the last delivery. If a callback
269 /// changes the layout again, the node can fire again in the same delivery.
270 ///
271 /// Within one layout, children are notified before their container. A node an earlier layout
272 /// changed is notified before the nodes a later layout changed.
273 ///
274 /// Changing the layout from inside the callback is allowed-- the change applies at the next
275 /// layout.
276 ///
277 /// @param callback The function to call. It receives `user_data` and this node.
278 ///
279 /// @param user_data Passed back to the callback on every fire (can be nullptr).
280 ///
281 /// @param destroy_user_data Called once when the registration drops `user_data` (can be
282 /// nullptr).
283 ///
284 /// @return Returns a LayoutCallback controlling how long the callback stays registered.
285 ///
286 /// @note Callbacks must not let exceptions propagate.
287 ///
288 [[nodiscard]] virtual LayoutCallback OnLayoutChange(
289 LayoutNodeCallback callback, void* user_data,
290 LayoutDestroyUserDataCallback destroy_user_data) = 0;
291
292 ///
293 /// Register a user-resize callback (invocable form).
294 ///
295 /// @param callback Any invocable. It may take the node as `LayoutNode&`, or nothing at
296 /// all.
297 ///
298 /// @return Returns a LayoutCallback controlling how long the callback stays registered.
299 ///
300 template <typename Callback>
301 requires std::invocable<Callback&, LayoutNode&> || std::invocable<Callback&>
302 [[nodiscard]] LayoutCallback OnUserResize(Callback callback) {
303 return RegisterInvocable<Callback>(std::move(callback), true);
304 }
305
306 ///
307 /// Register a layout-change callback (invocable form).
308 ///
309 /// @param callback Any invocable. It may take the node as `LayoutNode&`, or nothing at
310 /// all.
311 ///
312 /// @return Returns a LayoutCallback controlling how long the callback stays registered.
313 ///
314 template <typename Callback>
315 requires std::invocable<Callback&, LayoutNode&> || std::invocable<Callback&>
316 [[nodiscard]] LayoutCallback OnLayoutChange(Callback callback) {
317 return RegisterInvocable<Callback>(std::move(callback), false);
318 }
319
320 ///
321 /// Get the sibling after this node (null at the end, at the root, or when detached).
322 ///
323 RefPtr<LayoutNode> next_sibling() const;
324
325 ///
326 /// Get the sibling before this node (null at the start, at the root, or when detached).
327 ///
328 RefPtr<LayoutNode> previous_sibling() const;
329
330 protected:
331 virtual ~LayoutNode();
332
333 private:
334 template <typename Callback>
335 LayoutCallback RegisterInvocable(Callback callback, bool user_resize) {
336 auto* holder = new Callback(std::move(callback));
337 LayoutNodeCallback trampoline = [](void* user_data, LayoutNode* node) {
338 auto& cb = *static_cast<Callback*>(user_data);
339 if constexpr (std::invocable<Callback&, LayoutNode&>)
340 cb(*node);
341 else
342 cb();
343 };
345 = [](void* user_data) { delete static_cast<Callback*>(user_data); };
346 return user_resize ? OnUserResize(trampoline, holder, destroy)
347 : OnLayoutChange(trampoline, holder, destroy);
348 }
349};
350
351} // namespace ultralight
#define AExport
Definition Defines.h:41
A layout node that organizes child nodes into a row or column.
Definition Container.h:109
Scoped handle that controls how long a layout callback stays registered.
Definition Callback.h:144
Base class for Panels and Containers in a window layout tree.
Definition LayoutNode.h:118
virtual RefPtr< Panel > AsPanel()=0
Get this node as a Panel (null if it is not one).
virtual void SetSize(Size size)=0
Set the node's declared size along its container's axis.
virtual RefPtr< Container > parent() const =0
Get the node's parent container (null at the root or when detached).
virtual void SetMaxSize(Length max_size)=0
Set the node's maximum size constraint.
virtual int index() const =0
Get the node's index within its parent (-1 when detached).
virtual RefPtr< Container > AsContainer()=0
Get this node as a Container (null if it is not one).
LayoutCallback OnUserResize(Callback callback)
Register a user-resize callback (invocable form).
Definition LayoutNode.h:302
virtual LayoutCallback OnLayoutChange(LayoutNodeCallback callback, void *user_data, LayoutDestroyUserDataCallback destroy_user_data)=0
Register a callback that fires after layout changes this node's bounds.
virtual void SetBounds(const Rect &bounds)=0
Place this node manually.
virtual void Show()=0
Show the node again, restoring its remembered size exactly.
virtual void Hide()=0
Hide the node and redistribute its space to its siblings.
LayoutCallback OnLayoutChange(Callback callback)
Register a layout-change callback (invocable form).
Definition LayoutNode.h:316
virtual Rect bounds() const =0
Get the node's rect in container-local logical pixels.
virtual void SetMinSize(Length min_size)=0
Set the node's minimum size constraint.
virtual String key() const =0
Get the node's key (empty if unkeyed).
virtual LayoutCallback OnUserResize(LayoutNodeCallback callback, void *user_data, LayoutDestroyUserDataCallback destroy_user_data)=0
Register a callback fired when the user resizes this node with a divider.
virtual IntRect device_bounds() const =0
Get the node's rect in window back-buffer device pixels.
virtual bool is_hidden() const =0
Whether or not the node is hidden.
A distance or size constraint in an AppCore layout.
Definition Length.h:60
A layout node that hosts a single web view.
Definition Panel.h:59
Interface for all ref-counted objects that will be managed using the RefPtr<> smart pointer.
Definition RefPtr.h:49
A nullable smart pointer.
Definition RefPtr.h:126
Fixed, percentage, and flexible sizes for panels and containers.
Definition Length.h:371
Unicode string container with conversions for UTF-8, UTF-16, and UTF-32.
Definition String.h:31
Root namespace for every public Ultralight type, function, and enumeration.
void(*) LayoutNodeCallback(void *user_data, LayoutNode *node)
Callback fired for a layout node event.
Definition Callback.h:38
void(*) LayoutDestroyUserDataCallback(void *user_data)
Destroy hook for a callback registration's user data.
Definition Callback.h:27
Integer Rectangle Helper.
Definition Geometry.h:533
Float Rectangle Helper.
Definition Geometry.h:416