|
Ultralight C++ API 2.0.0
|
#include <AppCore/layout/LayoutNode.h>
Base class for Panels and Containers in a window layout tree.
An AppCore window arranges web views and native drawing regions into a tree of rows and columns, where each node shares space along its parent container's axis. LayoutNode represents an individual element in that hierarchy, whether it's a Container grouping child nodes or a Panel hosting a single View.
You use node handles to manage panes and containers dynamically at runtime, adapting the interface without rebuilding the layout tree.
This helper toggles a sidebar panel on and off:
Calling Hide() takes a node off screen and redistributes its space to sibling nodes, and Show() restores the node at its remembered size.
Hiding affects different node types:
Call SetSize(), SetMinSize(), or SetMaxSize() to update a node's declared size constraints at runtime. In a resizable container, double-clicking an adjacent divider restores both neighboring panes to the declared sizes set here (discarding any divider drags made since).
Accessors report layout rectangles across different coordinate spaces:
Both accessors are always up to date, except inside a layout override (see Container::SetLayoutOverride()), where a read returns the layout in progress. After a change (eg, SetSize()), reading either one lays the window out first and returns the new geometry right away, without waiting for a frame.
Both accessors return a zero rectangle before the node's first layout and after the node is removed.
Read the new size right after a change, and register OnLayoutChange() to follow later changes:
Callback registrations report geometry changes:
Both methods return a LayoutCallback that manages the registration (destroying it unregisters the callback).
A handle never keeps its node or its window alive (releasing one doesn't remove the node from the layout tree). To remove a node, call Container::Remove() or Foreground::Remove().
After a node is removed or its window closes, handles remain safe to call. Mutations do nothing, and accessors return safe fallback values.
Adding a child to a removed container or a closed window logs a warning and returns a handle that isn't attached to any window.
Public Member Functions | |
| virtual String | key () const =0 |
| Get the node's key (empty if unkeyed). | |
| virtual RefPtr< Container > | parent () const =0 |
| Get the node's parent container (null at the root or when detached). | |
| virtual int | index () const =0 |
| Get the node's index within its parent (-1 when detached). | |
| virtual RefPtr< Panel > | AsPanel ()=0 |
| Get this node as a Panel (null if it is not one). | |
| virtual RefPtr< Container > | AsContainer ()=0 |
| Get this node as a Container (null if it is not one). | |
| virtual void | Hide ()=0 |
| Hide the node and redistribute its space to its siblings. | |
| virtual void | Show ()=0 |
| Show the node again, restoring its remembered size exactly. | |
| virtual bool | is_hidden () const =0 |
| Whether or not the node is hidden. | |
| virtual Rect | bounds () const =0 |
| Get the node's rect in container-local logical pixels. | |
| virtual IntRect | device_bounds () const =0 |
| Get the node's rect in window back-buffer device pixels. | |
| virtual void | SetBounds (const Rect &bounds)=0 |
| Place this node manually. | |
| virtual void | SetSize (Size size)=0 |
| Set the node's declared size along its container's axis. | |
| virtual void | SetMinSize (Length min_size)=0 |
| Set the node's minimum size constraint. | |
| virtual void | SetMaxSize (Length max_size)=0 |
| Set the node's maximum size constraint. | |
| 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 LayoutCallback | OnLayoutChange (LayoutNodeCallback callback, void *user_data, LayoutDestroyUserDataCallback destroy_user_data)=0 |
| Register a callback that fires after layout changes this node's bounds. | |
| template<typename Callback> requires std::invocable<Callback&, LayoutNode&> || std::invocable<Callback&> | |
| LayoutCallback | OnUserResize (Callback callback) |
| Register a user-resize callback (invocable form). | |
| template<typename Callback> requires std::invocable<Callback&, LayoutNode&> || std::invocable<Callback&> | |
| LayoutCallback | OnLayoutChange (Callback callback) |
| Register a layout-change callback (invocable form). | |
| RefPtr< LayoutNode > | next_sibling () const |
| Get the sibling after this node (null at the end, at the root, or when detached). | |
| RefPtr< LayoutNode > | previous_sibling () const |
| Get the sibling before this node (null at the start, at the root, or when detached). | |
| Public Member Functions inherited from RefCounted | |
| virtual void | AddRef () const =0 |
| Increment the reference count (thread-safe). | |
| virtual void | Release () const =0 |
| Decrement the reference count (thread-safe). | |
| virtual int | ref_count () const =0 |
| Get the current reference count. | |
| virtual WeakControlBlock * | weak_control_block () const |
| Get the control block used to track weak references to this object. | |
Protected Member Functions | |
| virtual | ~LayoutNode () |
| Protected Member Functions inherited from RefCounted | |
| virtual | ~RefCounted () |
|
protectedvirtual |
Get this node as a Container (null if it is not one).
|
pure virtual |
Get the node's rect in container-local logical pixels.
This is the same space SetBounds() takes.
If anything changed since the last layout, the read lays the window out first.
|
pure virtual |
|
pure virtual |
|
pure virtual |
Get the node's index within its parent (-1 when detached).
|
pure virtual |
Whether or not the node is hidden.
This reports the node's own flag, so a node inside a hidden container still reports its own state even though it is not on screen.
|
pure virtual |
Get the node's key (empty if unkeyed).
|
inline |
Get the sibling after this node (null at the end, at the root, or when detached).
|
inlinenodiscard |
Register a layout-change callback (invocable form).
| callback | Any invocable. It may take the node as LayoutNode&, or nothing at all. |
|
nodiscardpure virtual |
Register a callback that fires after layout changes this node's bounds.
Use this to follow a node's geometry (eg, a reserved region that your own drawing fills).
The callback runs at the start of the app's next update (before AppListener::OnUpdate()). It can run earlier during mouse input (eg, a mouse move or press over the window, a divider release, a double-click reset), before the window routes that input. Mouse input delivers every pending change, not only one the input caused (eg, a SetSize() call your code made since the last update).
The callback never runs from inside a geometry read (bounds(), device_bounds()).
The callback fires once for all the layouts that ran since the last delivery. If a callback changes the layout again, the node can fire again in the same delivery.
Within one layout, children are notified before their container. A node an earlier layout changed is notified before the nodes a later layout changed.
Changing the layout from inside the callback is allowed– the change applies at the next layout.
| callback | The function to call. It receives user_data and this node. |
| user_data | Passed back to the callback on every fire (can be nullptr). |
| destroy_user_data | Called once when the registration drops user_data (can be nullptr). |
|
inlinenodiscard |
Register a user-resize callback (invocable form).
| callback | Any invocable. It may take the node as LayoutNode&, or nothing at all. |
|
nodiscardpure virtual |
Register a callback fired when the user resizes this node with a divider.
It fires on drag release, and again after a double-click resets the node to its declared size. Either way it fires only when the node's size changed.
| callback | The function to call. It receives user_data and this node. |
| user_data | Passed back to the callback on every fire (can be nullptr). |
| destroy_user_data | Called once when the registration drops user_data (can be nullptr). |
Get the node's parent container (null at the root or when detached).
|
inline |
Get the sibling before this node (null at the start, at the root, or when detached).
|
pure virtual |
Place this node manually.
| bounds | The node's new rect, in container-local logical pixels. |
|
pure virtual |
Set the node's maximum size constraint.
| max_size | The new maximum. An unset Length means no maximum. |
|
pure virtual |
Set the node's minimum size constraint.
| min_size | The new minimum. An unset Length means no minimum. |
|
pure virtual |
Set the node's declared size along its container's axis.
This acts like the size in the creation options– double-clicking an adjacent divider restores the node to the size declared here, discarding any user divider drags made since.
| size | The new declared size. An unset Size means one flex share (1fr). |
|
pure virtual |
Show the node again, restoring its remembered size exactly.