|
Ultralight C API 2.0.0
|
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:
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().
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.
Layout handles manage references independently of the tree:
Layout handles track identity rather than lifetime:
Layout and window events use individual callback setters:
This example tracks a container's bounds to resize an external drawing viewport:
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. | |
| ULContainer ulContainerAddColumn | ( | ULContainer | container, |
| const ULContainerDesc * | desc, | ||
| ULLayoutNode | insert_before ) |
Create a child column container (children arranged vertically).
| container | The receiving container. |
| desc | The new container's options (may be NULL for all defaults). |
| insert_before | The direct child to insert before (may be NULL to append at the end). |
| ULPanel ulContainerAddPanel | ( | ULContainer | container, |
| const ULPanelDesc * | desc, | ||
| ULViewConfig | view_config, | ||
| ULLayoutNode | insert_before ) |
Create a panel in a container.
| container | The receiving container. |
| desc | The panel's options (may be NULL for all defaults). |
| view_config | Configuration 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_before | The 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. |
| ULContainer ulContainerAddRow | ( | ULContainer | container, |
| const ULContainerDesc * | desc, | ||
| ULLayoutNode | insert_before ) |
Create a child row container (children arranged horizontally).
| container | The receiving container. |
| desc | The new container's options (may be NULL for all defaults). |
| insert_before | The direct child to insert before (may be NULL to append at the end). |
| 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.
| container | The receiving container. |
| desc | The panel's options (may be NULL for all defaults). |
| view | The View to adopt. Must not be NULL. |
| insert_before | The direct child to insert before (may be NULL to append at the end). |
| ULLayoutNode ulContainerAsLayoutNode | ( | ULContainer | container | ) |
Get a container's base layout-node handle.
| ULLayoutNode ulContainerFind | ( | ULContainer | container, |
| const char * | key ) |
Find a descendant by key.
| ULContainer ulContainerFindContainer | ( | ULContainer | container, |
| const char * | key ) |
Find a descendant container by key.
| ULPanel ulContainerFindPanel | ( | ULContainer | container, |
| const char * | key ) |
Find a descendant panel by key.
| ULLayoutNode ulContainerGetChildAt | ( | ULContainer | container, |
| int | index ) |
Get the child at an index.
| int ulContainerGetChildCount | ( | ULContainer | container | ) |
Get the number of children.
| bool ulContainerHasLayoutOverride | ( | ULContainer | container | ) |
Whether or not a container has a layout delegate installed.
| bool ulContainerIsAlive | ( | ULContainer | container | ) |
Whether or not the container is still part of a live window's tree.
| 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.
| container | The container holding the child. |
| node | The direct child to move. |
| move_before | The direct child to move node before (may be NULL to move to the end). |
| 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.
| void ulContainerRemoveAll | ( | ULContainer | container | ) |
Remove every child.
Equivalent to ulContainerRemove() on each child in turn.
| 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.
| container | The container whose dividers to style. |
| style | The style desc, or NULL to clear the override back to the window style. A zeroed desc clears it too. |
| 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.
| ULContainer ulCreateContainerRef | ( | ULContainer | container | ) |
Duplicate a container handle.
| ULForeground ulCreateForegroundRef | ( | ULForeground | foreground | ) |
Duplicate a foreground handle.
| ULLayoutNode ulCreateLayoutNodeRef | ( | ULLayoutNode | node | ) |
Duplicate a layout-node handle.
Duplicate a panel handle.
| void ulDestroyContainer | ( | ULContainer | container | ) |
Destroy a container handle.
Destroying a handle never removes the container from its tree (see ulContainerRemove()).
| void ulDestroyForeground | ( | ULForeground | foreground | ) |
Destroy a foreground handle.
Destroying a handle never affects the foreground layer or its floating panels.
| void ulDestroyLayoutNode | ( | ULLayoutNode | node | ) |
Destroy a layout-node handle.
Destroying a handle never removes the node from its tree (see ulContainerRemove()).
| void ulDestroyPanel | ( | ULPanel | panel | ) |
Destroy a panel handle.
Destroying a handle never removes the panel from its tree (see ulContainerRemove()).
| 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.
| foreground | The window's foreground layer. |
| desc | The panel's options, or NULL for an unkeyed full-window floating panel. |
| view_config | The 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. |
| 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.
| foreground | The window's foreground layer. |
| desc | The panel's options, or NULL for an unkeyed full-window floating panel. |
| view | The View to adopt. Must not be NULL. |
| ULPanel ulForegroundFindPanel | ( | ULForeground | foreground, |
| const char * | key ) |
Find a floating panel by key.
| ULPanel ulForegroundGetPanelAt | ( | ULForeground | foreground, |
| int | index ) |
Get the floating panel at an index in current z-order, bottom-most first.
| int ulForegroundGetPanelCount | ( | ULForeground | foreground | ) |
Get the number of floating panels (hidden panels included).
| bool ulForegroundIsAlive | ( | ULForeground | foreground | ) |
Whether or not the foreground still belongs to a live window.
| 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.
| ULContainer ulLayoutNodeAsContainer | ( | ULLayoutNode | node | ) |
Get a node as a container.
| ULPanel ulLayoutNodeAsPanel | ( | ULLayoutNode | node | ) |
Get a node as a panel.
| 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.
| 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.
| int ulLayoutNodeGetIndex | ( | ULLayoutNode | node | ) |
Get the node's index within its parent.
| ULString ulLayoutNodeGetKey | ( | ULLayoutNode | node | ) |
Get the node's key (empty if unkeyed).
| ULLayoutNodeKind ulLayoutNodeGetKind | ( | ULLayoutNode | node | ) |
Get the kind of a layout node.
| ULContainer ulLayoutNodeGetParent | ( | ULLayoutNode | node | ) |
Get the node's parent container.
| 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.
| bool ulLayoutNodeIsAlive | ( | ULLayoutNode | node | ) |
Whether or not the node is still part of a live window's tree.
| 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.
| 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.
| void ulLayoutNodeSetBounds | ( | ULLayoutNode | node, |
| ULLayoutRect | bounds ) |
Place the node manually, in container-local logical pixels.
| 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.
| 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).
| 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 ulLayoutNodeSetSize | ( | ULLayoutNode | node, |
| ULLayoutSize | size ) |
Set the node's declared size along its container's axis.
| 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.
| void ulLayoutNodeShow | ( | ULLayoutNode | node | ) |
Show the node again, restoring its remembered size exactly.
| ULLayoutNode ulPanelAsLayoutNode | ( | ULPanel | panel | ) |
Get a panel's base layout-node handle.
| 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.
| 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.
Get the panel's hosted View.
| bool ulPanelIsAlive | ( | ULPanel | panel | ) |
Whether or not the panel is still part of a live window's tree.
| 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.
| 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.
| window | The window to add the panel to. |
| desc | The panel's options (may be NULL for all defaults). |
| view_config | Configuration for the panel's new View (may be NULL for window defaults, see ulContainerAddPanel()). |
| 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().
| 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.
| window | The window whose root container to configure. |
| desc | The root's options, or NULL to reset the root to defaults. |
Find a panel by key anywhere in the window: the tiled layout first, then the foreground layer.
Get the panel holding keyboard focus.
| 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.
| 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.
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.
| a | The first window handle (can be NULL). |
| b | The second window handle (can be NULL). |
| 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.
| window | The window whose dividers to style. |
| style | The style desc, or NULL to restore the built-in defaults. A zeroed desc restores them too. |
| 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.
| 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 struct C_Container* ULContainer |
Opaque handle to a container (a row or column of child nodes).
| typedef void(*) ULEditableStateCallback(void *user_data, ULWindow window, ULPanel panel, ULEditableState state) |
The callback invoked when the focused panel's editable state changes.
| window | The window reporting the change. Borrowed, with the same rules as ULFocusChangeCallback's window. |
| panel | The panel the state describes, or NULL when no panel holds focus. Borrowed. Call ulCreatePanelRef() to keep it beyond the call. |
| state | The new editable state (see ULEditableState in <Ultralight/CAPI/CAPI_Editor.h>). |
The callback invoked when a window's focused panel changes.
| window | The 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 ==. |
| focused | The panel that now holds focus, or NULL when no panel does. Borrowed. Call ulCreatePanelRef() to keep it beyond the call. |
| typedef struct C_Foreground* ULForeground |
Opaque handle to a window's foreground layer (floating panels composited above the tiled layout).
| typedef struct C_LayoutNode* ULLayoutNode |
Opaque handle to a layout node, the shared base of panels and containers.
| typedef void(*) ULLayoutNodeCallback(void *user_data, ULLayoutNode node) |
The callback invoked for a layout node event.
| node | The node the event is about. Borrowed. Call ulCreateLayoutNodeRef() to keep it beyond the call. |
| typedef void(*) ULLayoutOverrideCallback(void *user_data, ULContainer container, ULLayoutRect content_box) |
The callback invoked to lay out a container's children manually.
| container | The container being laid out. Borrowed. Call ulCreateContainerRef() to keep it beyond the call. |
| content_box | The container's content box, in container-local logical pixels. |
| typedef struct C_Panel* ULPanel |
Opaque handle to a panel (a layout node hosting a View).
| typedef void(*) ULPanelCallback(void *user_data, ULPanel panel) |
The callback invoked for a panel event.
| panel | The panel the event is about. Borrowed. Call ulCreatePanelRef() to keep it beyond the call. |
| enum ULAnchorAlign |
| enum ULAnchorCorner |
| enum ULAnchorFit |
| enum ULAnchorKind |
The placement form of a ULAnchorDesc.
| enum 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). |
| enum ULLayoutFlags |
Flags for the desc structs' flags field.
| enum ULLayoutNodeKind |
The kind of a layout node.
| Enumerator | |
|---|---|
| kULLayoutNodeKind_None | NULL or invalid handle. |
| kULLayoutNodeKind_Panel | |
| kULLayoutNodeKind_Container | |
| enum ULLayoutSizeUnit |
The unit of a ULLayoutSize.