docs
Loading...
Searching...
No Matches
CAPI_Layout.h

Overview

Panels and containers for arranging Views across an AppCore window in C.

#include <AppCore/CAPI/CAPI_Layout.h>

The layout C API arranges Views across an AppCore window using a tree of panels and containers. Each panel hosts a single View, while row and column containers organize them into a tiled hierarchy.

You declare sizes once when creating nodes, so you don't need to recalculate bounds manually when the window resizes or its display scale changes.

This example splits a window into a resizable sidebar and a content pane:

static ULWindow main_window = NULL; // From ulCreateWindow().
static ULPanel sidebar = NULL;
static ULPanel content = NULL;
void BuildLayout(void) {
ULContainerDesc body_desc = {0};
body_desc.struct_size = sizeof(ULContainerDesc);
body_desc.key = "body";
ULPanelDesc sidebar_desc = {0};
sidebar_desc.struct_size = sizeof(ULPanelDesc);
sidebar_desc.key = "sidebar";
sidebar_desc.size = ulLayoutSizePx(240);
sidebar_desc.min_size = ulLayoutSizePx(160);
ULContainer root = ulWindowGetLayout(main_window);
ULContainer body = ulContainerAddRow(root, &body_desc, NULL);
sidebar = ulContainerAddPanel(body, &sidebar_desc, NULL, NULL);
content = ulContainerAddPanel(body, NULL, NULL, NULL);
// The tree keeps both containers.
}
struct C_Window * ULWindow
Opaque handle to a Window object.
Definition CAPI_Defines.h:43
ULContainer ulWindowGetLayout(ULWindow window)
Get a window's layout, the root container of the tiled panel tree (a column).
@ kULLayoutFlags_Resizable
The user can resize this container's children by dragging the dividers between them (containers only)...
Definition CAPI_Layout.h:254
void ulDestroyContainer(ULContainer container)
Destroy a container handle.
ULPanel ulContainerAddPanel(ULContainer container, const ULPanelDesc *desc, ULViewConfig view_config, ULLayoutNode insert_before)
Create a panel in a container.
ULContainer ulContainerAddRow(ULContainer container, const ULContainerDesc *desc, ULLayoutNode insert_before)
Create a child row container (children arranged horizontally).
struct C_Container * ULContainer
Opaque handle to a container (a row or column of child nodes).
Definition CAPI_Layout.h:160
struct C_Panel * ULPanel
Opaque handle to a panel (a layout node hosting a View).
Definition CAPI_Layout.h:156
Options for creating a container (a row or column of child nodes).
Definition CAPI_Layout.h:300
uint32_t flags
A ULLayoutFlags combination: Fixed, Resizable, Hidden.
Definition CAPI_Layout.h:315
uint32_t struct_size
Must be sizeof(ULContainerDesc).
Definition CAPI_Layout.h:301
const char * key
Optional identity for lookup and diagnostics (see ULPanelDesc.key).
Definition CAPI_Layout.h:304
Options for creating a panel.
Definition CAPI_Layout.h:264
uint32_t struct_size
Must be sizeof(ULPanelDesc).
Definition CAPI_Layout.h:265
ULLayoutSize min_size
Minimum size constraint.
Definition CAPI_Layout.h:284
ULLayoutSize size
The panel's size along its container's axis.
Definition CAPI_Layout.h:278
const char * key
Optional identity for lookup (ulContainerFind()) and diagnostics, as null-terminated UTF-8 (copied).
Definition CAPI_Layout.h:272

Building the Layout Tree

The C++ layout headers (starting with <AppCore/Layout.h>) explain the underlying concepts for organizing panels into nested rows and columns under a window's root container. The C API doesn't provide a fluent builder, so you build the tree one call at a time.

Call ulWindowGetLayout() to obtain the window's root container, which is a column that spans the window's content area. To configure the root container's options (such as padding, gap, or resizable dividers), call ulWindowConfigureLayout().

Descriptors and Sizes

Zero-initialize every descriptor struct. Passing NULL applies default options for every field.

Construct ULLayoutSize values using ulLayoutSizePx() for logical pixels, ulLayoutSizePct() for percentages, or ulLayoutSizeFr() for flex factors. A zero-initialized ULLayoutSize leaves the dimension unset so the field's default applies, which differs from an explicit 0px.

Warning
Leaving struct_size set to 0 causes the library to ignore the descriptor, log a warning, and fall back to default values.

Handle Ownership

Layout handles manage references independently of the tree:

Note
A View that outlives its panel loses its ulViewSet*Callback() callbacks– register them again after adopting the View into another panel.

Handle Identity and Lifetime

Layout handles track identity rather than lifetime:

Event Callbacks

Layout and window events use individual callback setters:

  • Each event accepts only one callback per node, panel, or window. Setting a new callback replaces the existing registration, and passing NULL removes it.
  • Releasing a handle leaves its callbacks active. A callback continues firing until you replace or clear it, remove the node, or close the window.
  • Pass application state through user_data. The optional destroy_user_data hook (see ULUserDataDestroyCallback) cleans up that state when the library drops the registration.
  • Callback parameters are borrowed handles. They stay valid only during the call, and you must never destroy them. To keep a handle beyond the callback, duplicate it using ulCreateLayoutNodeRef() or ulCreatePanelRef().
  • Compare window handles in callbacks using ulWindowIsSame(), never ==. Focus-change and editable-state callbacks pass a borrowed ULWindow handle that doesn't equal your original window pointer.

This example tracks a container's bounds to resize an external drawing viewport:

static void OnViewportLayout(void* user_data, ULLayoutNode node) {
(void)user_data;
ResizeViewport(ulLayoutNodeGetDeviceBounds(node)); // node is borrowed
}
// Reserve a region of the row for your own drawing.
void AddViewport(ULContainer body) {
ULContainer viewport = ulContainerAddColumn(body, NULL, NULL);
ulLayoutNodeSetLayoutChangeCallback(node, OnViewportLayout, NULL, NULL);
ulDestroyContainer(viewport);
}
ULLayoutNode ulContainerAsLayoutNode(ULContainer container)
Get a container's base layout-node handle.
void ulLayoutNodeSetLayoutChangeCallback(ULLayoutNode node, ULLayoutNodeCallback callback, void *user_data, ULUserDataDestroyCallback destroy_user_data)
Set callback for when layout changes the node's bounds.
struct C_LayoutNode * ULLayoutNode
Opaque handle to a layout node, the shared base of panels and containers.
Definition CAPI_Layout.h:152
ULLayoutDeviceRect ulLayoutNodeGetDeviceBounds(ULLayoutNode node)
Get the node's rect from the most recent layout, in window back-buffer device pixels.
void ulDestroyLayoutNode(ULLayoutNode node)
Destroy a layout-node handle.
ULContainer ulContainerAddColumn(ULContainer container, const ULContainerDesc *desc, ULLayoutNode insert_before)
Create a child column container (children arranged vertically).
See also
ulWindowGetLayout(), ulWindowGetForeground(), ulContainerAddPanel(), ulContainerRemove(), ulLayoutNodeIsSame(), ulWindowIsSame(), ulWindowConfigureLayout(), ULUserDataDestroyCallback

Classes

struct  ULLayoutSize
 A size or constraint length, as a value plus a unit. More...
struct  ULLayoutDeviceRect
 A rectangle in device pixels (window-backbuffer space). More...
struct  ULPanelDesc
 Options for creating a panel. More...
struct  ULContainerDesc
 Options for creating a container (a row or column of child nodes). More...
struct  ULDividerStyleDesc
 Styling for the dividers between a resizable container's children. More...
struct  ULAnchorDesc
 Placement for a foreground (floating) panel, the flattened form of the C++ Anchor. More...
struct  ULForegroundPanelDesc
 Options for creating a foreground (floating) panel. More...

Functions

ULLayoutNode ulCreateLayoutNodeRef (ULLayoutNode node)
 Duplicate a layout-node handle.
void ulDestroyLayoutNode (ULLayoutNode node)
 Destroy a layout-node handle.
bool ulLayoutNodeIsAlive (ULLayoutNode node)
 Whether or not the node is still part of a live window's tree.
ULPanel ulCreatePanelRef (ULPanel panel)
 Duplicate a panel handle.
void ulDestroyPanel (ULPanel panel)
 Destroy a panel handle.
bool ulPanelIsAlive (ULPanel panel)
 Whether or not the panel is still part of a live window's tree.
ULContainer ulCreateContainerRef (ULContainer container)
 Duplicate a container handle.
void ulDestroyContainer (ULContainer container)
 Destroy a container handle.
bool ulContainerIsAlive (ULContainer container)
 Whether or not the container is still part of a live window's tree.
ULForeground ulCreateForegroundRef (ULForeground foreground)
 Duplicate a foreground handle.
void ulDestroyForeground (ULForeground foreground)
 Destroy a foreground handle.
bool ulForegroundIsAlive (ULForeground foreground)
 Whether or not the foreground still belongs to a live window.
bool ulLayoutNodeIsSame (ULLayoutNode a, ULLayoutNode b)
 Whether or not two handles refer to the same node.
bool ulWindowIsSame (ULWindow a, ULWindow b)
 Whether or not two handles refer to the same window.
ULLayoutNodeKind ulLayoutNodeGetKind (ULLayoutNode node)
 Get the kind of a layout node.
ULPanel ulLayoutNodeAsPanel (ULLayoutNode node)
 Get a node as a panel.
ULContainer ulLayoutNodeAsContainer (ULLayoutNode node)
 Get a node as a container.
ULLayoutNode ulPanelAsLayoutNode (ULPanel panel)
 Get a panel's base layout-node handle.
ULLayoutNode ulContainerAsLayoutNode (ULContainer container)
 Get a container's base layout-node handle.
ULString ulLayoutNodeGetKey (ULLayoutNode node)
 Get the node's key (empty if unkeyed).
ULContainer ulLayoutNodeGetParent (ULLayoutNode node)
 Get the node's parent container.
int ulLayoutNodeGetIndex (ULLayoutNode node)
 Get the node's index within its parent.
void ulLayoutNodeHide (ULLayoutNode node)
 Hide the node, redistributing its space to its siblings.
void ulLayoutNodeShow (ULLayoutNode node)
 Show the node again, restoring its remembered size exactly.
bool ulLayoutNodeIsHidden (ULLayoutNode node)
 Whether or not the node is hidden.
ULLayoutRect ulLayoutNodeGetBounds (ULLayoutNode node)
 Get the node's rect from the most recent layout, in container-local logical pixels.
ULLayoutDeviceRect ulLayoutNodeGetDeviceBounds (ULLayoutNode node)
 Get the node's rect from the most recent layout, in window back-buffer device pixels.
void ulLayoutNodeSetBounds (ULLayoutNode node, ULLayoutRect bounds)
 Place the node manually, in container-local logical pixels.
void ulLayoutNodeSetSize (ULLayoutNode node, ULLayoutSize size)
 Set the node's declared size along its container's axis.
void ulLayoutNodeSetMinSize (ULLayoutNode node, ULLayoutSize min_size)
 Set the node's minimum size constraint (px or percent, an fr unit is ignored with a warning).
void ulLayoutNodeSetMaxSize (ULLayoutNode node, ULLayoutSize max_size)
 Set the node's maximum size constraint (px or percent, an fr unit is ignored with a warning).
ULPanel ulContainerAddPanel (ULContainer container, const ULPanelDesc *desc, ULViewConfig view_config, ULLayoutNode insert_before)
 Create a panel in a container.
ULPanel ulContainerAdoptPanel (ULContainer container, const ULPanelDesc *desc, ULView view, ULLayoutNode insert_before)
 Create a panel that adopts an existing View (including a View created through a Session).
ULContainer ulContainerAddRow (ULContainer container, const ULContainerDesc *desc, ULLayoutNode insert_before)
 Create a child row container (children arranged horizontally).
ULContainer ulContainerAddColumn (ULContainer container, const ULContainerDesc *desc, ULLayoutNode insert_before)
 Create a child column container (children arranged vertically).
bool ulContainerRemove (ULContainer container, ULLayoutNode node)
 Remove a direct child (and, for a container child, its whole subtree) from the tree.
void ulContainerRemoveAll (ULContainer container)
 Remove every child.
bool ulContainerMove (ULContainer container, ULLayoutNode node, ULLayoutNode move_before)
 Reorder a direct child within its container.
int ulContainerGetChildCount (ULContainer container)
 Get the number of children.
ULLayoutNode ulContainerGetChildAt (ULContainer container, int index)
 Get the child at an index.
ULLayoutNode ulContainerFind (ULContainer container, const char *key)
 Find a descendant by key.
ULPanel ulContainerFindPanel (ULContainer container, const char *key)
 Find a descendant panel by key.
ULContainer ulContainerFindContainer (ULContainer container, const char *key)
 Find a descendant container by key.
void ulContainerSetLayoutOverride (ULContainer container, ULLayoutOverrideCallback callback, void *user_data, ULUserDataDestroyCallback destroy_user_data)
 Override a container's layout with a layout delegate.
bool ulContainerHasLayoutOverride (ULContainer container)
 Whether or not a container has a layout delegate installed.
void ulContainerSetDividerStyle (ULContainer container, const ULDividerStyleDesc *style)
 Set this container's divider style, overriding the window style field by field for the dividers between its own children.
ULView ulPanelGetView (ULPanel panel)
 Get the panel's hosted View.
void ulPanelFocus (ULPanel panel)
 Grant the panel exclusive keyboard focus.
void ulPanelBringToFront (ULPanel panel)
 Bring a floating panel to the top of the foreground layer.
ULPanel ulForegroundAddPanel (ULForeground foreground, const ULForegroundPanelDesc *desc, ULViewConfig view_config)
 Create a floating panel, composited above every tiled panel.
ULPanel ulForegroundAdoptPanel (ULForeground foreground, const ULForegroundPanelDesc *desc, ULView view)
 Create a floating panel that adopts an existing View (including one created through a Session, or one that survived a removal).
bool ulForegroundRemove (ULForeground foreground, ULPanel panel)
 Remove a floating panel from the foreground layer.
int ulForegroundGetPanelCount (ULForeground foreground)
 Get the number of floating panels (hidden panels included).
ULPanel ulForegroundGetPanelAt (ULForeground foreground, int index)
 Get the floating panel at an index in current z-order, bottom-most first.
ULPanel ulForegroundFindPanel (ULForeground foreground, const char *key)
 Find a floating panel by key.
ULContainer ulWindowGetLayout (ULWindow window)
 Get a window's layout, the root container of the tiled panel tree (a column).
ULForeground ulWindowGetForeground (ULWindow window)
 Get a window's foreground layer, which holds floating panels displayed above the window's layout (eg, a toast, an in-window dialog, or a command palette).
void ulWindowConfigureLayout (ULWindow window, const ULContainerDesc *desc)
 Configure the window's root container.
ULPanel ulWindowAddPanel (ULWindow window, const ULPanelDesc *desc, ULViewConfig view_config)
 Add a panel to the window's root container.
ULPanel ulWindowFindPanel (ULWindow window, const char *key)
 Find a panel by key anywhere in the window: the tiled layout first, then the foreground layer.
ULPanel ulWindowGetFocusedPanel (ULWindow window)
 Get the panel holding keyboard focus.
void ulWindowClearFocus (ULWindow window)
 Take keyboard focus away from every panel.
void ulWindowSetDividerStyle (ULWindow window, const ULDividerStyleDesc *style)
 Set the window-level divider style, the field-by-field fallback for every resizable container that does not override a field itself.
void ulLayoutNodeSetUserResizeCallback (ULLayoutNode node, ULLayoutNodeCallback callback, void *user_data, ULUserDataDestroyCallback destroy_user_data)
 Set callback for when the user resizes the node with a divider.
void ulLayoutNodeSetLayoutChangeCallback (ULLayoutNode node, ULLayoutNodeCallback callback, void *user_data, ULUserDataDestroyCallback destroy_user_data)
 Set callback for when layout changes the node's bounds.
void ulPanelSetDismissCallback (ULPanel panel, ULPanelCallback callback, void *user_data, ULUserDataDestroyCallback destroy_user_data)
 Set callback for when the library dismisses a floating panel (an auto-dismiss trigger, see ULForegroundPanelDesc).
void ulWindowSetFocusChangeCallback (ULWindow window, ULFocusChangeCallback callback, void *user_data, ULUserDataDestroyCallback destroy_user_data)
 Set callback for when the window's focused panel changes (the new panel may be NULL).
void ulWindowSetEditableStateCallback (ULWindow window, ULEditableStateCallback callback, void *user_data, ULUserDataDestroyCallback destroy_user_data)
 Set callback for when the focused panel's editable state changes.

Typedefs

typedef struct C_LayoutNode * ULLayoutNode
 Opaque handle to a layout node, the shared base of panels and containers.
typedef struct C_Panel * ULPanel
 Opaque handle to a panel (a layout node hosting a View).
typedef struct C_Container * ULContainer
 Opaque handle to a container (a row or column of child nodes).
typedef struct C_Foreground * ULForeground
 Opaque handle to a window's foreground layer (floating panels composited above the tiled layout).
typedef void(*) ULLayoutNodeCallback(void *user_data, ULLayoutNode node)
 The callback invoked for a layout node event.
typedef void(*) ULPanelCallback(void *user_data, ULPanel panel)
 The callback invoked for a panel event.
typedef void(*) ULFocusChangeCallback(void *user_data, ULWindow window, ULPanel focused)
 The callback invoked when a window's focused panel changes.
typedef void(*) ULEditableStateCallback(void *user_data, ULWindow window, ULPanel panel, ULEditableState state)
 The callback invoked when the focused panel's editable state changes.
typedef void(*) ULLayoutOverrideCallback(void *user_data, ULContainer container, ULLayoutRect content_box)
 The callback invoked to lay out a container's children manually.

Enumerations

enum  ULLayoutSizeUnit { kULLayoutSizeUnit_Default = 0 , kULLayoutSizeUnit_Px = 1 , kULLayoutSizeUnit_Pct = 2 , kULLayoutSizeUnit_Fr = 3 }
 The unit of a ULLayoutSize. More...
enum  ULLayoutNodeKind { kULLayoutNodeKind_None = 0 , kULLayoutNodeKind_Panel = 1 , kULLayoutNodeKind_Container = 2 }
 The kind of a layout node. More...
enum  ULLayoutFlags { kULLayoutFlags_Fixed = 1 << 0 , kULLayoutFlags_Hidden = 1 << 1 , kULLayoutFlags_Resizable = 1 << 2 }
 Flags for the desc structs' flags field. More...
enum  ULFocusPolicy { kULFocusPolicy_Auto = 0 , kULFocusPolicy_Grab = 1 , kULFocusPolicy_None = 2 }
 Keyboard-focus policy for a foreground (floating) panel. More...
enum  ULAnchorKind {
  kULAnchorKind_Default = 0 , kULAnchorKind_At = 1 , kULAnchorKind_WindowCorner = 2 , kULAnchorKind_WindowCenter = 3 ,
  kULAnchorKind_Below = 4
}
 The placement form of a ULAnchorDesc. More...
enum  ULAnchorCorner { kULAnchorCorner_TopLeft = 0 , kULAnchorCorner_TopRight = 1 , kULAnchorCorner_BottomLeft = 2 , kULAnchorCorner_BottomRight = 3 }
 A window corner (kULAnchorKind_WindowCorner). More...
enum  ULAnchorAlign { kULAnchorAlign_Start = 0 , kULAnchorAlign_Center = 1 , kULAnchorAlign_End = 2 }
 Cross-axis alignment of the floating panel against its anchor rect (kULAnchorKind_Below). More...
enum  ULAnchorFit { kULAnchorFit_None = 0 , kULAnchorFit_Flip = 1 }
 Fit behavior when an anchored floating panel does not fit on its preferred side (kULAnchorKind_Below). More...

Function Documentation

◆ ulContainerAddColumn()

ULContainer ulContainerAddColumn ( ULContainer container,
const ULContainerDesc * desc,
ULLayoutNode insert_before )

Create a child column container (children arranged vertically).

Parameters
containerThe receiving container.
descThe new container's options (may be NULL for all defaults).
insert_beforeThe direct child to insert before (may be NULL to append at the end).
Returns
Returns a new ULContainer instance. If the container was removed or its window closed, it logs a warning and returns a container that isn't in any window (changes to it do nothing). You must call ulDestroyContainer() when finished.
See also
Container::AddColumn()

◆ ulContainerAddPanel()

ULPanel ulContainerAddPanel ( ULContainer container,
const ULPanelDesc * desc,
ULViewConfig view_config,
ULLayoutNode insert_before )

Create a panel in a container.

Parameters
containerThe receiving container.
descThe panel's options (may be NULL for all defaults).
view_configConfiguration for the panel's new View (may be NULL for window defaults). The fields describing the hosting window (device scale, display id, acceleration) are filled in from the window for you, and every other field is yours.
insert_beforeThe direct child to insert before (may be NULL to append at the end). An anchor that is not a direct child logs a warning and the panel appends at the end.
Returns
Returns a new ULPanel instance. If the container was removed or its window closed, it logs a warning and returns a panel that isn't in any window (changes to it do nothing). You must call ulDestroyPanel() when finished.
Note
To host a deliberately CPU-rendered View on a GPU window, create the View with ulCreateView() and adopt it with ulContainerAdoptPanel().
See also
Container::AddPanel()

◆ ulContainerAddRow()

ULContainer ulContainerAddRow ( ULContainer container,
const ULContainerDesc * desc,
ULLayoutNode insert_before )

Create a child row container (children arranged horizontally).

Parameters
containerThe receiving container.
descThe new container's options (may be NULL for all defaults).
insert_beforeThe direct child to insert before (may be NULL to append at the end).
Returns
Returns a new ULContainer instance. If the container was removed or its window closed, it logs a warning and returns a container that isn't in any window (changes to it do nothing). You must call ulDestroyContainer() when finished.
See also
Container::AddRow()

◆ ulContainerAdoptPanel()

ULPanel ulContainerAdoptPanel ( ULContainer container,
const ULPanelDesc * desc,
ULView view,
ULLayoutNode insert_before )

Create a panel that adopts an existing View (including a View created through a Session).

The panel takes a reference to the View and resizes it to the panel's bounds.

Parameters
containerThe receiving container.
descThe panel's options (may be NULL for all defaults).
viewThe View to adopt. Must not be NULL.
insert_beforeThe direct child to insert before (may be NULL to append at the end).
Returns
Returns a new ULPanel instance. If the container was removed or its window closed, or view is NULL, it logs a warning and returns a panel that isn't in any window (changes to it do nothing). You must call ulDestroyPanel() when finished.
See also
Container::AdoptPanel()

◆ ulContainerAsLayoutNode()

ULLayoutNode ulContainerAsLayoutNode ( ULContainer container)

Get a container's base layout-node handle.

Returns
Returns a new ULLayoutNode instance (NULL when container is NULL). You must call ulDestroyLayoutNode() when finished.

◆ ulContainerFind()

ULLayoutNode ulContainerFind ( ULContainer container,
const char * key )

Find a descendant by key.

Returns
Returns a new ULLayoutNode instance, or NULL when not found. With duplicate keys the most recently created match wins. You must call ulDestroyLayoutNode() when finished.

◆ ulContainerFindContainer()

ULContainer ulContainerFindContainer ( ULContainer container,
const char * key )

Find a descendant container by key.

Returns
Returns a new ULContainer instance, or NULL when not found or the match is not a container. You must call ulDestroyContainer() when finished.

◆ ulContainerFindPanel()

ULPanel ulContainerFindPanel ( ULContainer container,
const char * key )

Find a descendant panel by key.

Returns
Returns a new ULPanel instance, or NULL when not found or the match is not a panel. You must call ulDestroyPanel() when finished.

◆ ulContainerGetChildAt()

ULLayoutNode ulContainerGetChildAt ( ULContainer container,
int index )

Get the child at an index.

Returns
Returns a new ULLayoutNode instance, or NULL when the index is out of range. You must call ulDestroyLayoutNode() when finished.

◆ ulContainerGetChildCount()

int ulContainerGetChildCount ( ULContainer container)

Get the number of children.

◆ ulContainerHasLayoutOverride()

bool ulContainerHasLayoutOverride ( ULContainer container)

Whether or not a container has a layout delegate installed.

◆ ulContainerIsAlive()

bool ulContainerIsAlive ( ULContainer container)

Whether or not the container is still part of a live window's tree.

Note
Safe to call from any thread. The answer is advisory.

◆ ulContainerMove()

bool ulContainerMove ( ULContainer container,
ULLayoutNode node,
ULLayoutNode move_before )

Reorder a direct child within its container.

A node from a different container (or window) is a no-op with a warning. An anchor that is not a direct child falls back to the end, with a warning.

Parameters
containerThe container holding the child.
nodeThe direct child to move.
move_beforeThe direct child to move node before (may be NULL to move to the end).
Returns
Returns whether or not the node was reordered.

◆ ulContainerRemove()

bool ulContainerRemove ( ULContainer container,
ULLayoutNode node )

Remove a direct child (and, for a container child, its whole subtree) from the tree.

Removal detaches the child and drops each removed panel's reference to its View. A View you hold a reference to survives removal and can be adopted into another panel or window. Removed handles stay safe to use, and changes to them do nothing.

Returns
Returns whether or not the node was a direct child and was removed.

◆ ulContainerRemoveAll()

void ulContainerRemoveAll ( ULContainer container)

Remove every child.

Equivalent to ulContainerRemove() on each child in turn.

◆ ulContainerSetDividerStyle()

void ulContainerSetDividerStyle ( ULContainer container,
const ULDividerStyleDesc * style )

Set this container's divider style, overriding the window style field by field for the dividers between its own children.

Parameters
containerThe container whose dividers to style.
styleThe style desc, or NULL to clear the override back to the window style. A zeroed desc clears it too.
Note
Negative or non-finite widths and invalid colors are ignored with a warning.
See also
Container::SetDividerStyle()

◆ ulContainerSetLayoutOverride()

void ulContainerSetLayoutOverride ( ULContainer container,
ULLayoutOverrideCallback callback,
void * user_data,
ULUserDataDestroyCallback destroy_user_data )

Override a container's layout with a layout delegate.

The delegate runs each time the window performs layout (after any layout change, a resize, or a display scale change). It never runs while the container has no children.

The delegate places the container's direct children by calling ulLayoutNodeSetBounds().

content_box is the container's content box (inside its padding) in container-local logical pixels.

Placed rects are snapped and clipped to the content box.

A placed rect persists until the delegate places that child again.

Children the delegate has never placed occupy no region.

Pass a NULL callback to restore default layout.

Note
The Resizable flag is ignored (with a warning) while a container has a layout delegate. Dividers only exist between children the container itself lays out.

◆ ulCreateContainerRef()

ULContainer ulCreateContainerRef ( ULContainer container)

Duplicate a container handle.

Returns
Returns a new ULContainer referring to the same container. You must call ulDestroyContainer() when finished, on this handle and the original both.
Note
Safe to call from any thread.

◆ ulCreateForegroundRef()

ULForeground ulCreateForegroundRef ( ULForeground foreground)

Duplicate a foreground handle.

Returns
Returns a new ULForeground referring to the same foreground layer. You must call ulDestroyForeground() when finished, on this handle and the original both.
Note
Safe to call from any thread.

◆ ulCreateLayoutNodeRef()

ULLayoutNode ulCreateLayoutNodeRef ( ULLayoutNode node)

Duplicate a layout-node handle.

Returns
Returns a new ULLayoutNode referring to the same node. You must call ulDestroyLayoutNode() when finished, on this handle and the original both.
Note
Safe to call from any thread.

◆ ulCreatePanelRef()

ULPanel ulCreatePanelRef ( ULPanel panel)

Duplicate a panel handle.

Returns
Returns a new ULPanel referring to the same panel. You must call ulDestroyPanel() when finished, on this handle and the original both.
Note
Safe to call from any thread.

◆ ulDestroyContainer()

void ulDestroyContainer ( ULContainer container)

Destroy a container handle.

Destroying a handle never removes the container from its tree (see ulContainerRemove()).

Note
Safe to call from any thread.

◆ ulDestroyForeground()

void ulDestroyForeground ( ULForeground foreground)

Destroy a foreground handle.

Destroying a handle never affects the foreground layer or its floating panels.

Note
Safe to call from any thread.

◆ ulDestroyLayoutNode()

void ulDestroyLayoutNode ( ULLayoutNode node)

Destroy a layout-node handle.

Destroying a handle never removes the node from its tree (see ulContainerRemove()).

Note
Safe to call from any thread.

◆ ulDestroyPanel()

void ulDestroyPanel ( ULPanel panel)

Destroy a panel handle.

Destroying a handle never removes the panel from its tree (see ulContainerRemove()).

Note
Safe to call from any thread.

◆ ulForegroundAddPanel()

ULPanel ulForegroundAddPanel ( ULForeground foreground,
const ULForegroundPanelDesc * desc,
ULViewConfig view_config )

Create a floating panel, composited above every tiled panel.

The panel is sized on both axes against the window and placed per its ULAnchorDesc. Floating panels stack in creation order, refined by ulPanelBringToFront(), and the top-most panel is hit-tested first.

Parameters
foregroundThe window's foreground layer.
descThe panel's options, or NULL for an unkeyed full-window floating panel.
view_configThe View configuration, or NULL for the window default. The fields describing the hosting window (device scale, display id, acceleration) are filled in from the window for you, and every other field is yours.
Returns
Returns a new ULPanel instance. If the window has closed, it logs a warning and returns a panel that isn't in any window (changes to it do nothing). You must call ulDestroyPanel() when finished.
See also
Foreground::AddPanel()

◆ ulForegroundAdoptPanel()

ULPanel ulForegroundAdoptPanel ( ULForeground foreground,
const ULForegroundPanelDesc * desc,
ULView view )

Create a floating panel that adopts an existing View (including one created through a Session, or one that survived a removal).

The panel takes a reference to the View and resizes it to the panel's bounds.

Parameters
foregroundThe window's foreground layer.
descThe panel's options, or NULL for an unkeyed full-window floating panel.
viewThe View to adopt. Must not be NULL.
Returns
Returns a new ULPanel instance. If view is NULL or the window has closed, it logs a warning and returns a panel that isn't in any window (changes to it do nothing). You must call ulDestroyPanel() when finished.
See also
Foreground::AdoptPanel()

◆ ulForegroundFindPanel()

ULPanel ulForegroundFindPanel ( ULForeground foreground,
const char * key )

Find a floating panel by key.

Returns
Returns a new ULPanel instance, or NULL when not found. With duplicate keys the most recently created match wins. You must call ulDestroyPanel() when finished.

◆ ulForegroundGetPanelAt()

ULPanel ulForegroundGetPanelAt ( ULForeground foreground,
int index )

Get the floating panel at an index in current z-order, bottom-most first.

Returns
Returns a new ULPanel instance, or NULL when the index is out of range. You must call ulDestroyPanel() when finished.

◆ ulForegroundGetPanelCount()

int ulForegroundGetPanelCount ( ULForeground foreground)

Get the number of floating panels (hidden panels included).

◆ ulForegroundIsAlive()

bool ulForegroundIsAlive ( ULForeground foreground)

Whether or not the foreground still belongs to a live window.

Note
Safe to call from any thread. The answer is advisory.

◆ ulForegroundRemove()

bool ulForegroundRemove ( ULForeground foreground,
ULPanel panel )

Remove a floating panel from the foreground layer.

Removal drops the panel's reference to its View, and a reference you hold keeps the View adoptable. The removed handle stays safe to use, and changes to it do nothing.

Returns
Returns whether or not the panel was one of this window's floating panels and was removed. A panel that is not one of them is a no-op with a warning.

◆ ulLayoutNodeAsContainer()

ULContainer ulLayoutNodeAsContainer ( ULLayoutNode node)

Get a node as a container.

Returns
Returns a new ULContainer instance, or NULL when the node is not a container. You must call ulDestroyContainer() when finished.

◆ ulLayoutNodeAsPanel()

ULPanel ulLayoutNodeAsPanel ( ULLayoutNode node)

Get a node as a panel.

Returns
Returns a new ULPanel instance, or NULL when the node is not a panel. You must call ulDestroyPanel() when finished.

◆ ulLayoutNodeGetBounds()

ULLayoutRect ulLayoutNodeGetBounds ( ULLayoutNode node)

Get the node's rect from the most recent layout, in container-local logical pixels.

This is the same space ulLayoutNodeSetBounds() takes.

Returns
Returns the node's rect, or a zero rect before the node's first layout and after the node is removed or its window closes.

◆ ulLayoutNodeGetDeviceBounds()

ULLayoutDeviceRect ulLayoutNodeGetDeviceBounds ( ULLayoutNode node)

Get the node's rect from the most recent layout, in window back-buffer device pixels.

This is the coordinate space your own drawing uses.

Returns
Returns the node's rect, or a zero rect before the node's first layout and after the node is removed or its window closes.

◆ ulLayoutNodeGetIndex()

int ulLayoutNodeGetIndex ( ULLayoutNode node)

Get the node's index within its parent.

Returns
Returns the index, or -1 when the node is detached.

◆ ulLayoutNodeGetKey()

ULString ulLayoutNodeGetKey ( ULLayoutNode node)

Get the node's key (empty if unkeyed).

Returns
Returns a new ULString instance. You must call ulDestroyString() when finished.

◆ ulLayoutNodeGetKind()

ULLayoutNodeKind ulLayoutNodeGetKind ( ULLayoutNode node)

Get the kind of a layout node.

Returns
Returns the node's kind, or kULLayoutNodeKind_None when node is NULL.

◆ ulLayoutNodeGetParent()

ULContainer ulLayoutNodeGetParent ( ULLayoutNode node)

Get the node's parent container.

Returns
Returns a new ULContainer instance, or NULL at the root or when detached. You must call ulDestroyContainer() when finished.

◆ ulLayoutNodeHide()

void ulLayoutNodeHide ( ULLayoutNode node)

Hide the node, redistributing its space to its siblings.

The declared size is remembered and restored by ulLayoutNodeShow(). Hiding a container hides its whole subtree.

Note
A hidden panel's View stops rendering entirely. Painting and animations suspend, and the page receives a visibilitychange event (a per-panel signal).

◆ ulLayoutNodeIsAlive()

bool ulLayoutNodeIsAlive ( ULLayoutNode node)

Whether or not the node is still part of a live window's tree.

Note
Safe to call from any thread. The answer is advisory, since it can change as soon as it is returned.

◆ ulLayoutNodeIsHidden()

bool ulLayoutNodeIsHidden ( ULLayoutNode node)

Whether or not the node is hidden.

This reports the node's own hidden flag, so a node inside a hidden container still reports its own state.

◆ ulLayoutNodeIsSame()

bool ulLayoutNodeIsSame ( ULLayoutNode a,
ULLayoutNode b )

Whether or not two handles refer to the same node.

Handles are references, so two lookups of one node return distinct handles that compare equal here.

Returns
Returns false when either handle is NULL, or when the nodes differ.

◆ ulLayoutNodeSetBounds()

void ulLayoutNodeSetBounds ( ULLayoutNode node,
ULLayoutRect bounds )

Place the node manually, in container-local logical pixels.

Precondition
Only legal inside its container's layout delegate (see ulContainerSetLayoutOverride()). Anywhere else this is a no-op with a warning.

◆ ulLayoutNodeSetLayoutChangeCallback()

void ulLayoutNodeSetLayoutChangeCallback ( ULLayoutNode node,
ULLayoutNodeCallback callback,
void * user_data,
ULUserDataDestroyCallback destroy_user_data )

Set callback for when layout changes the node's bounds.

The callback runs at most once per frame.

Use this callback to follow a node's geometry, such as a reserved region your own drawing fills.

◆ ulLayoutNodeSetMaxSize()

void ulLayoutNodeSetMaxSize ( ULLayoutNode node,
ULLayoutSize max_size )

Set the node's maximum size constraint (px or percent, an fr unit is ignored with a warning).

◆ ulLayoutNodeSetMinSize()

void ulLayoutNodeSetMinSize ( ULLayoutNode node,
ULLayoutSize min_size )

Set the node's minimum size constraint (px or percent, an fr unit is ignored with a warning).

◆ ulLayoutNodeSetSize()

void ulLayoutNodeSetSize ( ULLayoutNode node,
ULLayoutSize size )

Set the node's declared size along its container's axis.

◆ ulLayoutNodeSetUserResizeCallback()

void ulLayoutNodeSetUserResizeCallback ( ULLayoutNode node,
ULLayoutNodeCallback callback,
void * user_data,
ULUserDataDestroyCallback destroy_user_data )

Set callback for when the user resizes the node with a divider.

It fires on drag release and after a double-click reset, and only when the node's size changed.

◆ ulLayoutNodeShow()

void ulLayoutNodeShow ( ULLayoutNode node)

Show the node again, restoring its remembered size exactly.

◆ ulPanelAsLayoutNode()

ULLayoutNode ulPanelAsLayoutNode ( ULPanel panel)

Get a panel's base layout-node handle.

Returns
Returns a new ULLayoutNode instance (NULL when panel is NULL). You must call ulDestroyLayoutNode() when finished.

◆ ulPanelBringToFront()

void ulPanelBringToFront ( ULPanel panel)

Bring a floating panel to the top of the foreground layer.

The panel paints on top of other floating panels and receives mouse input first.

Note
A tiled panel composites in tree order. Calling this function on a tiled panel is a no-op with a warning.

◆ ulPanelFocus()

void ulPanelFocus ( ULPanel panel)

Grant the panel exclusive keyboard focus.

You should always focus a panel through this function (or a user click) rather than focusing its View directly, otherwise the panel's window won't know where to route keyboard input.

Note
Focusing a hidden panel (or one inside a hidden container) is ignored with a warning. Focusing a foreground panel created with kULFocusPolicy_None is ignored too, since such a panel never takes keyboard focus.

◆ ulPanelGetView()

ULView ulPanelGetView ( ULPanel panel)

Get the panel's hosted View.

Returns
Returns a new ULView instance referring to the panel's View, or NULL after the panel is removed or its window closes. You must call ulDestroyView() when finished, which releases only your reference, never the panel's.

◆ ulPanelIsAlive()

bool ulPanelIsAlive ( ULPanel panel)

Whether or not the panel is still part of a live window's tree.

Note
Safe to call from any thread. The answer is advisory.

◆ ulPanelSetDismissCallback()

void ulPanelSetDismissCallback ( ULPanel panel,
ULPanelCallback callback,
void * user_data,
ULUserDataDestroyCallback destroy_user_data )

Set callback for when the library dismisses a floating panel (an auto-dismiss trigger, see ULForegroundPanelDesc).

Application-initiated hides never fire it.

◆ ulWindowAddPanel()

ULPanel ulWindowAddPanel ( ULWindow window,
const ULPanelDesc * desc,
ULViewConfig view_config )

Add a panel to the window's root container.

This is shorthand for ulContainerAddPanel() on ulWindowGetLayout() with an append position. A bare panel with a NULL desc fills the whole window.

Parameters
windowThe window to add the panel to.
descThe panel's options (may be NULL for all defaults).
view_configConfiguration for the panel's new View (may be NULL for window defaults, see ulContainerAddPanel()).
Returns
Returns a new ULPanel instance, or NULL when window is NULL. After the window closes, it logs a warning and returns a panel that isn't in any window (changes to it do nothing). You must call ulDestroyPanel() when finished.

◆ ulWindowClearFocus()

void ulWindowClearFocus ( ULWindow window)

Take keyboard focus away from every panel.

As with ulViewUnfocus(), the page's focused element gets a blur event but stays focused in the document, and shows focus again the next time you call ulPanelFocus().

Note
If a panel had focus, the window's focus-change callback fires with a NULL panel.
See also
ulPanelFocus(), ulWindowSetFocusChangeCallback()

◆ ulWindowConfigureLayout()

void ulWindowConfigureLayout ( ULWindow window,
const ULContainerDesc * desc )

Configure the window's root container.

This applies key, the Resizable and Hidden flags, gap, and padding from the desc to the root of the tiled tree. The root always fills the window, so the sizing fields and the Fixed flag are ignored.

The desc re-applies wholesale on every call, so an unset field restores its default.

Parameters
windowThe window whose root container to configure.
descThe root's options, or NULL to reset the root to defaults.
See also
Window::BuildLayout()

◆ ulWindowFindPanel()

ULPanel ulWindowFindPanel ( ULWindow window,
const char * key )

Find a panel by key anywhere in the window: the tiled layout first, then the foreground layer.

Returns
Returns a new ULPanel instance, or NULL when not found. You must call ulDestroyPanel() when finished.

◆ ulWindowGetFocusedPanel()

ULPanel ulWindowGetFocusedPanel ( ULWindow window)

Get the panel holding keyboard focus.

Returns
Returns a new ULPanel instance, or NULL when no panel holds focus. You must call ulDestroyPanel() when finished.

◆ ulWindowGetForeground()

ULForeground ulWindowGetForeground ( ULWindow window)

Get a window's foreground layer, which holds floating panels displayed above the window's layout (eg, a toast, an in-window dialog, or a command palette).

Floating panels clip to the window. For menus and dropdowns that need to extend outside it, use ulCreatePopupWindow() instead.

Returns
Returns a new ULForeground instance (after the window closes, changes to it do nothing). You must call ulDestroyForeground() when finished.
See also
Window::foreground()

◆ ulWindowGetLayout()

ULContainer ulWindowGetLayout ( ULWindow window)

Get a window's layout, the root container of the tiled panel tree (a column).

Build the window's content by adding panels and nested containers to it.

Returns
Returns a new ULContainer instance (after the window closes, changes to it do nothing). You must call ulDestroyContainer() when finished.

◆ ulWindowIsSame()

bool ulWindowIsSame ( ULWindow a,
ULWindow b )

Whether or not two handles refer to the same window.

The focus-change and editable-state callbacks pass a borrowed window handle that never equals the one ulCreateWindow() returned, so compare the two with this.

Parameters
aThe first window handle (can be NULL).
bThe second window handle (can be NULL).
Returns
Returns false when either handle is NULL, or when the windows differ.

◆ ulWindowSetDividerStyle()

void ulWindowSetDividerStyle ( ULWindow window,
const ULDividerStyleDesc * style )

Set the window-level divider style, the field-by-field fallback for every resizable container that does not override a field itself.

Parameters
windowThe window whose dividers to style.
styleThe style desc, or NULL to restore the built-in defaults. A zeroed desc restores them too.
Note
Negative or non-finite widths and invalid colors are ignored with a warning.
See also
Window::SetDividerStyle()

◆ ulWindowSetEditableStateCallback()

void ulWindowSetEditableStateCallback ( ULWindow window,
ULEditableStateCallback callback,
void * user_data,
ULUserDataDestroyCallback destroy_user_data )

Set callback for when the focused panel's editable state changes.

This is the window-level form of ulViewSetChangeEditableStateCallback(): one callback reports the focused panel's state, so a multi-panel app doesn't need to set one on each View. You can use it to show and hide an on-screen keyboard, for example.

Note
The window uses each panel View's editable-state hook to track this. If you call ulViewSetChangeEditableStateCallback() on a hosted View, that View's changes stop reaching this callback and the window's input method handling.

◆ ulWindowSetFocusChangeCallback()

void ulWindowSetFocusChangeCallback ( ULWindow window,
ULFocusChangeCallback callback,
void * user_data,
ULUserDataDestroyCallback destroy_user_data )

Set callback for when the window's focused panel changes (the new panel may be NULL).

Typedef Documentation

◆ ULContainer

typedef struct C_Container* ULContainer

Opaque handle to a container (a row or column of child nodes).

See also
ulWindowGetLayout(), ulContainerAddRow(), ulDestroyContainer()

◆ ULEditableStateCallback

typedef void(*) ULEditableStateCallback(void *user_data, ULWindow window, ULPanel panel, ULEditableState state)

The callback invoked when the focused panel's editable state changes.

Parameters
windowThe window reporting the change. Borrowed, with the same rules as ULFocusChangeCallback's window.
panelThe panel the state describes, or NULL when no panel holds focus. Borrowed. Call ulCreatePanelRef() to keep it beyond the call.
stateThe new editable state (see ULEditableState in <Ultralight/CAPI/CAPI_Editor.h>).
See also
ulWindowSetEditableStateCallback()

◆ ULFocusChangeCallback

typedef void(*) ULFocusChangeCallback(void *user_data, ULWindow window, ULPanel focused)

The callback invoked when a window's focused panel changes.

Parameters
windowThe window whose focused panel changed. Borrowed, valid only for the duration of the call. Keep your own window handle if you need one afterwards, and never destroy this one. Compare it to your own handle with ulWindowIsSame(), never ==.
focusedThe panel that now holds focus, or NULL when no panel does. Borrowed. Call ulCreatePanelRef() to keep it beyond the call.
See also
ulWindowSetFocusChangeCallback()

◆ ULForeground

typedef struct C_Foreground* ULForeground

Opaque handle to a window's foreground layer (floating panels composited above the tiled layout).

See also
ulWindowGetForeground(), ulDestroyForeground()

◆ ULLayoutNode

typedef struct C_LayoutNode* ULLayoutNode

Opaque handle to a layout node, the shared base of panels and containers.

See also
ulPanelAsLayoutNode(), ulContainerAsLayoutNode(), ulLayoutNodeIsSame(), ulDestroyLayoutNode()

◆ ULLayoutNodeCallback

typedef void(*) ULLayoutNodeCallback(void *user_data, ULLayoutNode node)

The callback invoked for a layout node event.

Parameters
nodeThe node the event is about. Borrowed. Call ulCreateLayoutNodeRef() to keep it beyond the call.
See also
ulLayoutNodeSetLayoutChangeCallback(), ulLayoutNodeSetUserResizeCallback()

◆ ULLayoutOverrideCallback

typedef void(*) ULLayoutOverrideCallback(void *user_data, ULContainer container, ULLayoutRect content_box)

The callback invoked to lay out a container's children manually.

Parameters
containerThe container being laid out. Borrowed. Call ulCreateContainerRef() to keep it beyond the call.
content_boxThe container's content box, in container-local logical pixels.
See also
ulContainerSetLayoutOverride()

◆ ULPanel

typedef struct C_Panel* ULPanel

Opaque handle to a panel (a layout node hosting a View).

See also
ulContainerAddPanel(), ulDestroyPanel()

◆ ULPanelCallback

typedef void(*) ULPanelCallback(void *user_data, ULPanel panel)

The callback invoked for a panel event.

Parameters
panelThe panel the event is about. Borrowed. Call ulCreatePanelRef() to keep it beyond the call.
See also
ulPanelSetDismissCallback()

Enumeration Type Documentation

◆ ULAnchorAlign

Cross-axis alignment of the floating panel against its anchor rect (kULAnchorKind_Below).

Enumerator
kULAnchorAlign_Start 

Left edges align.

kULAnchorAlign_Center 
kULAnchorAlign_End 

Right edges align.

◆ ULAnchorCorner

A window corner (kULAnchorKind_WindowCorner).

Enumerator
kULAnchorCorner_TopLeft 
kULAnchorCorner_TopRight 
kULAnchorCorner_BottomLeft 
kULAnchorCorner_BottomRight 

◆ ULAnchorFit

Fit behavior when an anchored floating panel does not fit on its preferred side (kULAnchorKind_Below).

Enumerator
kULAnchorFit_None 
kULAnchorFit_Flip 

Place above the rect when it does not fit beneath.

◆ ULAnchorKind

The placement form of a ULAnchorDesc.

Enumerator
kULAnchorKind_Default 

The window origin (with the default 100% sizes, a full-window panel).

kULAnchorKind_At 

Absolute window-space logical px.

kULAnchorKind_WindowCorner 

A window corner, following the window.

kULAnchorKind_WindowCenter 

Centered in the window, following the window.

kULAnchorKind_Below 

Under an anchor rect in a target panel.

◆ ULFocusPolicy

Keyboard-focus policy for a foreground (floating) panel.

Enumerator
kULFocusPolicy_Auto 

Takes focus when clicked, like any panel.

Showing the panel never takes focus.

kULFocusPolicy_Grab 

Takes keyboard focus when created (unless hidden) and each time it is shown, even from inside a click handler (dropdowns, palettes, in-window dialogs).

kULFocusPolicy_None 

Never takes keyboard focus.

Calling ulPanelFocus() on it is ignored with a warning (toasts, HUDs).

◆ ULLayoutFlags

Flags for the desc structs' flags field.

Enumerator
kULLayoutFlags_Fixed 

The user cannot resize this node with a divider drag (panels and containers).

kULLayoutFlags_Hidden 

Created hidden, shows later without a layout flash (all descs).

kULLayoutFlags_Resizable 

The user can resize this container's children by dragging the dividers between them (containers only).

◆ ULLayoutNodeKind

The kind of a layout node.

See also
ulLayoutNodeGetKind()
Enumerator
kULLayoutNodeKind_None 

NULL or invalid handle.

kULLayoutNodeKind_Panel 
kULLayoutNodeKind_Container 

◆ ULLayoutSizeUnit

The unit of a ULLayoutSize.

Enumerator
kULLayoutSizeUnit_Default 

Unset: the receiving field's default applies.

kULLayoutSizeUnit_Px 

Logical pixels.

kULLayoutSizeUnit_Pct 

For a size, percent of the container's free space.

For a constraint, percent of the container's content box.

kULLayoutSizeUnit_Fr 

A flex factor (sizes only).

A constraint field treats it as unset with a warning.

Go to the source code of this file.