Maul UI API reference

Generated from the public headers, which are the source of truth: 352 functions across 40 headers.

base.h

The base of the Maul UI API: the library version, the export and attribute macros, and the result codes every fallible function returns.

muiVersion muiGetVersion(void);

Returns the version of the library that was linked, which may differ from the MUI_VERSION macros a program was compiled with.

Returns: The library version.

Thread safety. Safe from any thread.

const char* muiGetResultName(muiResult result);

Returns the name of a result code, for diagnostics.

Parameters:

Returns: A static, NUL-terminated string such as "mui_errorCapacity".

Thread safety. Safe from any thread.

access.h

Accessibility: the platform-neutral accessibility tree. Every node of a root's tree is a node of it, with a role, text, flags and actions; most come from what the library already holds (rectangles, scrolling, focus, states, value ranges, virtual lists), the rest from the host. The library builds updates in the shape AccessKit uses: the nodes that changed, each sent whole, the focus with every update, the root with the first. The host hands them to the adapters, which keep their own copies, and applies on its thread the requests the adapters queued. Nothing is built until the host enables a root, as when Maul Window reports that an assistive technology asked for one.

uint64_t muiNode_GetAccessId(muiNodeId nodeId);

The accessibility id of a node.

Parameters:

Returns: Its id.

Thread safety. Safe from any thread.

muiNodeId muiGetNodeOfAccessId(uint64_t id);

The node of an accessibility id.

Parameters:

Returns: Its node.

Thread safety. Safe from any thread.

MUI_NODISCARD MUI_API muiResult muiContext_SetAccessTextFunction(muiContext* context, muiAccessTextFunction function, void* user);

Sets the function host content's text comes from: a node whose content is the host's (maul-ui/layout.h's mui_contentHost) and whose value text the host did not set reads as what it returns, and as a label when the host gave it no role. NULL reads nothing.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL context; mui_errorBusy while the context is busy.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiNode_MarkAccessChanged(muiContext* context, muiNodeId nodeId);

Tells the accessibility tree what the host's text function gives for a node changed while its content did not: its selection moved. muiNode_MarkContentChanged tells it too; the text editor's functions that take a node (maul-ui/text_editor.h) tell it themselves.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL context or the null id; mui_errorBusy while the context is busy; mui_errorStale for a node that is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiNode_EnableAccess(muiContext* context, muiNodeId rootId, bool enable);

Starts or stops building updates for a root's tree. Started, the next update is whole; starting a started root makes its next update whole again, as when an adapter starts over. The first root started allocates a copy of each node as last sent and the update's buffers, and the last root stopped frees them.

Parameters:

Returns: mui_success; mui_empty when stopping a root not started; mui_errorCapacity when starting one while limits.accessRoots roots are, or when memory runs out; mui_errorInvalid for a NULL context, the null id, or starting a node with a parent; mui_errorBusy while the context is busy; mui_errorStale when starting a node that is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

bool muiNode_IsAccessEnabled(const muiContext* context, muiNodeId rootId);

Returns whether updates are built for a root's tree.

Parameters:

Returns: Whether they are; false for a NULL context or a stale id.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiNode_BuildAccessUpdate(muiContext* context, muiNodeId rootId, muiAccessUpdate* updateOut);

Builds the update for an enabled root after its layout: the nodes whose role, texts, flags, actions, bounds, transform, values or children changed since the last update, each whole.

Parameters:

Returns: mui_success; mui_empty for a root not enabled; mui_errorInvalid for a NULL argument or the null id; mui_errorBusy while the context is busy; mui_errorStale for a root that is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiContext_PerformAccessAction(muiContext* context, const muiAccessRequest* request, bool* handledOut);

Applies a request to a node that takes its action.

Parameters:

Returns: mui_success; mui_empty for a node that does not take the action, and for the text actions, which the host applies; mui_errorInvalid for a NULL context or request or an unknown action, counted as misuse; mui_errorFormat for a value or point that is not finite, counted as none, since a client sends it; mui_errorBusy while the context is busy or its event function runs; mui_errorStale for a node that is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiNode_SetAccessRole(muiContext* context, muiNodeId nodeId, muiRole role);

Sets a node's role.

Parameters:

Returns: mui_success; mui_errorCapacity when limits.accessNodes nodes have accessibility data; mui_errorInvalid for a NULL context, the null id or an unknown role; mui_errorBusy while the context is busy; mui_errorStale for a node that is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiNode_GetAccessRole(const muiContext* context, muiNodeId nodeId, muiRole* roleOut);

Reads a node's role: mui_roleGeneric for one the host gave none.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL argument or the null id; mui_errorStale for a node that is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiNode_SetAccessText(muiContext* context, muiNodeId nodeId, muiAccessTextKind kind, const char* text, size_t length);

Sets one of a node's texts; a length of 0 clears it. The text is copied.

Parameters:

Returns: mui_success; mui_errorCapacity when limits.accessNodes nodes have accessibility data or memory runs out; mui_errorInvalid for a NULL context, the null id, an unknown kind, or text that is not UTF-8 or holds a NUL; mui_errorLimit for a length past MUI_MAX_TEXT_BYTES; mui_errorBusy while the context is busy; mui_errorStale for a node that is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiNode_GetAccessText(const muiContext* context, muiNodeId nodeId, muiAccessTextKind kind, const char** textOut, size_t* lengthOut);

Reads one of a node's texts.

Parameters:

Returns: mui_success; mui_empty for none; mui_errorInvalid for a NULL argument, the null id or an unknown kind; mui_errorStale for a node that is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiNode_SetAccessFlags(muiContext* context, muiNodeId nodeId, muiAccessFlags flags);

Sets a node's flags, those the host sets.

Parameters:

Returns: mui_success; mui_errorCapacity when limits.accessNodes nodes have accessibility data; mui_errorInvalid for a NULL context, the null id or a flag outside those; mui_errorBusy while the context is busy; mui_errorStale for a node that is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiNode_GetAccessFlags(const muiContext* context, muiNodeId nodeId, muiAccessFlags* flagsOut);

Reads the flags the host set on a node.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL argument or the null id; mui_errorStale for a node that is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiNode_SetAccessRelation(muiContext* context, muiNodeId nodeId, muiAccessRelation kind, const muiNodeId* targets, uint32_t count);

Names other nodes from a node by one relation, replacing those it named by it; a count of 0 clears it. The ids are copied; a node named that is destroyed later stays named, and adapters pass over ids they do not hold.

Parameters:

Returns: mui_success; mui_errorCapacity when limits.accessNodes nodes have accessibility data or memory runs out; mui_errorInvalid for a NULL context, the null id as the node or a target or an unknown kind; mui_errorLimit for more than MUI_MAX_RELATION_TARGETS targets; mui_errorBusy while the context is busy; mui_errorStale for a node or a target that is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiNode_GetAccessRelation(const muiContext* context, muiNodeId nodeId, muiAccessRelation kind, muiNodeId* targetsOut, uint32_t capacity, uint32_t* countOut);

Reads the nodes a node names by one relation.

Parameters:

Returns: mui_success; mui_errorCapacity when they do not fit; mui_errorInvalid for a NULL argument, the null id or an unknown kind; mui_errorStale for a node that is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

muiAccessValues muiDefaultAccessValues(void);

The default values: none of them.

Returns: The values.

Thread safety. Safe from any thread.

MUI_NODISCARD MUI_API muiResult muiNode_SetAccessValues(muiContext* context, muiNodeId nodeId, const muiAccessValues* values);

Sets a node's typed values.

Parameters:

Returns: mui_success; mui_errorCapacity when limits.accessNodes nodes have accessibility data; mui_errorInvalid for a NULL argument, the null id or an enum outside its values; mui_errorBusy while the context is busy; mui_errorStale for a node that is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiNode_GetAccessValues(const muiContext* context, muiNodeId nodeId, muiAccessValues* valuesOut);

Reads the typed values the host set on a node.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL argument or the null id; mui_errorStale for a node that is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

access_android.h

The Android accessibility adapter, the component MAUL_UI_ANDROID_ACCESSIBILITY builds on Android: the accessibility tree's consumer shown to Android through maul.ui.AccessProvider (java/maul/ui/AccessProvider.java, which the host builds into its application, adding java/proguard-rules.pro to its rules when it shrinks its code), a provider whose virtual views are the shown nodes. The provider is the host view's (Maul Window's mwinWindow_RequestAccessibilityRoot gives it); clients' actions come back through a function of the host's. The header is C: the JNI's types pass as void*. An adapter is busy while one of its functions that change it runs, or its allocator or action function runs, from those or from its platform's calls: a call back into one that changes it answers mui_errorBusy, NULL or false, or does nothing where it returns no status, as the destroy does.

static inline muiAndroidAdapterDef muiDefaultAndroidAdapterDef(void);

The default def: the C library's allocation, 4096 nodes, no JNIEnv, no view, a scale of 1, no action function.

Built in the program from the headers it includes, so it carries their version (MUI_ABI_VERSION), which muiCreateAndroidAdapter checks.

Returns: The def.

Thread safety. Safe from any thread.

MUI_NODISCARD MUI_API muiResult muiCreateAndroidAdapter(const muiAndroidAdapterDef* def, muiAndroidAdapter** adapterOut);

Makes an adapter with an empty tree, and its provider: the class maul.ui.AccessProvider is found through the view's class loader, so that any thread the JNIEnv belongs to may make it.

Parameters:

Returns: mui_success; mui_errorVersion for a def built against headers of another binary interface (MUI_ABI_VERSION), before the rest of the def is read; mui_errorInvalid for a NULL argument, a def not from muiDefaultAndroidAdapterDef, a half-set allocator, no nodes, no JNIEnv, no view, no action function or a scale not above 0; mui_errorLimit for more than MUI_MAX_ACCESS_NODES nodes; mui_errorCapacity when memory runs out; mui_errorPlatform when the provider's class is not in the application or Java fails.

Thread safety. Main thread only.

void muiDestroyAndroidAdapter(muiAndroidAdapter* adapter);

Lets go of the provider, which answers nothing from then on, and destroys the adapter; NULL is ignored. Take the provider from the view first.

Parameters:

Thread safety. Main thread only.

uint64_t muiAndroidAdapter_GetMisuse(const muiAndroidAdapter* adapter);

Returns how many calls the adapter refused as invalid input (mui_errorInvalid) or as calls back in while busy (mui_errorBusy): a count release builds can watch to catch a host's bugs. Queries taking it as const count nothing.

Parameters:

Returns: The count; 0 for a NULL adapter.

Thread safety. Main thread only.

MUI_NODISCARD MUI_API muiResult muiAndroidAdapter_Apply(muiAndroidAdapter* adapter, const muiAccessUpdate* update);

Applies an update to the adapter's tree (muiAccessTree_Apply).

Parameters:

Returns: As muiAccessTree_Apply; mui_errorInvalid for a NULL adapter; mui_errorBusy while the adapter is busy.

Thread safety. Main thread only.

const muiAccessTree* muiAndroidAdapter_GetTree(const muiAndroidAdapter* adapter);

The adapter's tree.

Parameters:

Returns: The tree; NULL for a NULL adapter.

Thread safety. Main thread only.

MUI_NODISCARD MUI_API muiResult muiAndroidAdapter_SetScale(muiAndroidAdapter* adapter, float scale);

Sets the pixels per unit, as the host scales its UI.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL adapter or a scale not above 0; mui_errorBusy while the adapter is busy.

Thread safety. Main thread only.

void* muiAndroidAdapter_GetRoot(muiAndroidAdapter* adapter);

The provider (a global reference to a maul.ui.AccessProvider), for the view to give as its accessibility node provider (mwinWindow_RequestAccessibilityRoot); the adapter keeps it until destroyed.

Parameters:

Returns: The provider (a jobject), or NULL for a NULL adapter.

Thread safety. Main thread only.

access_aria.h

The ARIA adapter, the component MAUL_UI_ARIA builds for Emscripten: the accessibility tree's consumer mirrored into elements of the page, which the browser gives its accessibility clients. The elements are built in an element of the host's over the canvas (Maul Window's accessibility host, say), each placed over what it names and invisible; clients' actions come back through a function of the host's. A page cannot tell whether a screen reader runs, and the elements cost every user, so by default nothing is built until the program enables the adapter or a screen reader user presses the visually hidden button the adapter puts in the host. Every function here is used on the page's main thread. An adapter is busy while one of its functions that change it runs, or its allocator or action function runs, from those or from its platform's calls: a call back into one that changes it answers mui_errorBusy, NULL or false, or does nothing where it returns no status, as the destroy does.

static inline muiAriaAdapterDef muiDefaultAriaAdapterDef(void);

The default def: the C library's allocation, 4096 nodes, no host, a scale of 1, building deferred behind a button labelled "Enable accessibility", no action function.

Built in the program from the headers it includes, so it carries their version (MUI_ABI_VERSION), which muiCreateAriaAdapter checks.

Returns: The def.

Thread safety. Safe from any thread.

MUI_NODISCARD MUI_API muiResult muiCreateAriaAdapter(const muiAriaAdapterDef* def, muiAriaAdapter** adapterOut);

Makes an adapter with an empty tree in the host element, with the enabling button when building is deferred.

Parameters:

Returns: mui_success; mui_errorVersion for a def built against headers of another binary interface (MUI_ABI_VERSION), before the rest of the def is read; mui_errorInvalid for a NULL argument, a def not from muiDefaultAriaAdapterDef, a half-set allocator, no nodes, no host, no label, no action function or a scale not above 0; mui_errorPlatform when no element matches the host, or there is no page; mui_errorLimit for more than MUI_MAX_ACCESS_NODES nodes; mui_errorCapacity when memory runs out.

Thread safety. Main thread only.

void muiDestroyAriaAdapter(muiAriaAdapter* adapter);

Takes the adapter's elements out of the page and destroys it; NULL is ignored.

Parameters:

Thread safety. Main thread only.

uint64_t muiAriaAdapter_GetMisuse(const muiAriaAdapter* adapter);

Returns how many calls the adapter refused as invalid input (mui_errorInvalid) or as calls back in while busy (mui_errorBusy): a count release builds can watch to catch a host's bugs. Queries taking it as const count nothing.

Parameters:

Returns: The count; 0 for a NULL adapter.

Thread safety. Main thread only.

MUI_NODISCARD MUI_API muiResult muiAriaAdapter_Apply(muiAriaAdapter* adapter, const muiAccessUpdate* update);

Applies an update to the adapter's tree (muiAccessTree_Apply) and, once enabled, brings the elements to it.

Parameters:

Returns: As muiAccessTree_Apply; mui_errorInvalid for a NULL adapter; mui_errorBusy while the adapter is busy.

Thread safety. Main thread only.

const muiAccessTree* muiAriaAdapter_GetTree(const muiAriaAdapter* adapter);

The adapter's tree.

Parameters:

Returns: The tree; NULL for a NULL adapter.

Thread safety. Main thread only.

MUI_NODISCARD MUI_API muiResult muiAriaAdapter_SetScale(muiAriaAdapter* adapter, float scale);

Sets the CSS pixels per unit, as the host scales its UI, and places the elements again.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL adapter or a scale not above 0; mui_errorBusy while the adapter is busy.

Thread safety. Main thread only.

void muiAriaAdapter_Enable(muiAriaAdapter* adapter);

Builds the elements, if building was deferred and has not begun, and takes the enabling button away. The button does the same, and gives the program's focused node the DOM focus. Building is one way by design: deferring only spares a page the elements until someone asks for them, and once built they follow the tree until the adapter is destroyed, so there is no call to take them away.

Parameters:

Thread safety. Main thread only.

bool muiAriaAdapter_IsEnabled(const muiAriaAdapter* adapter);

Whether the elements are built.

Parameters:

Returns: Whether they are; false for NULL.

Thread safety. Main thread only.

access_atspi.h

The AT-SPI adapter, the component MAUL_UI_ATSPI builds on Linux: the accessibility tree's consumer shown to AT-SPI, the accessibility service of Linux desktops. An application joins the accessibility bus and registers its root, whose children are its windows; each window is an adapter owning a consumer tree, applying the core's updates. Clients' actions come back through a function of the host's. Nothing here starts a thread or waits on the bus after the application is made: the host polls the application's descriptor for reading, with its other sources, and pumps it when it is readable and once a frame. Every function here is used on the thread that made the application, which "main thread" below means. An application and its adapters are busy while one of the functions that change them runs, or their allocator or an action function runs: a call back into one answers mui_errorBusy, NULL or false, or does nothing where it returns no status, as muiAtspiApp_Pump and the destroys do.

static inline muiAtspiAppDef muiDefaultAtspiAppDef(void);

The default def: the C library's allocation, no name and 16 windows.

Built in the program from the headers it includes, so it carries their version (MUI_ABI_VERSION), which muiCreateAtspiApp checks.

Returns: The def.

Thread safety. Safe from any thread.

MUI_NODISCARD MUI_API muiResult muiCreateAtspiApp(const muiAtspiAppDef* def, muiAtspiApp** appOut);

Joins the accessibility bus (the address AT_SPI_BUS_ADDRESS names, else the one the session bus's org.a11y.Bus gives) and serves the application's root, asking the registry to embed it; the answer comes at a later pump. Waits for the buses' first answers, which a local socket gives at once.

Parameters:

Returns: mui_success; mui_errorVersion for a def built against headers of another binary interface (MUI_ABI_VERSION), before the rest of the def is read; mui_errorInvalid for a NULL argument, a def not from muiDefaultAtspiAppDef, a half-set allocator, no name or no windows; mui_errorPlatform when libdbus-1 1.12 or newer or the accessibility bus cannot be reached; mui_errorCapacity when memory runs out.

Thread safety. Main thread only.

void muiDestroyAtspiApp(muiAtspiApp* app);

Leaves the accessibility bus; NULL is ignored. Destroy its adapters first.

Parameters:

Thread safety. Main thread only.

uint64_t muiAtspiApp_GetMisuse(const muiAtspiApp* app);

Returns how many calls the application and its adapters refused as invalid input (mui_errorInvalid) or as calls back in while busy (mui_errorBusy): a count release builds can watch to catch a host's bugs. Queries taking it as const count nothing.

Parameters:

Returns: The count; 0 for a NULL application.

Thread safety. Main thread only.

int muiAtspiApp_GetDescriptor(const muiAtspiApp* app);

The descriptor to poll for reading.

Parameters:

Returns: The descriptor; -1 for a NULL application.

Thread safety. Main thread only.

void muiAtspiApp_Pump(muiAtspiApp* app);

Reads what the bus has, answers clients' calls, and writes what it can, without waiting. Call it when the descriptor is readable and once a frame, as answers wait to be written.

Parameters:

Thread safety. Main thread only.

bool muiAtspiApp_IsRegistered(const muiAtspiApp* app);

Whether the registry has embedded the application's root.

Parameters:

Returns: Whether it has; false for NULL.

Thread safety. Main thread only.

muiAtspiAdapterDef muiDefaultAtspiAdapterDef(void);

The default adapter def: 4096 nodes, a scale of 1, no action function.

Returns: The def.

Thread safety. Safe from any thread.

MUI_NODISCARD MUI_API muiResult muiCreateAtspiAdapter(muiAtspiApp* app, const muiAtspiAdapterDef* def, muiAtspiAdapter** adapterOut);

Adds a window to the application: an adapter with an empty tree, whose root becomes the application root's last child.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL argument, a def not from muiDefaultAtspiAdapterDef, no nodes, no action function or a scale not above 0; mui_errorLimit for more than MUI_MAX_ACCESS_NODES nodes; mui_errorCapacity when the application has its windows or memory runs out; mui_errorBusy while the application is busy.

Thread safety. Main thread only.

void muiDestroyAtspiAdapter(muiAtspiAdapter* adapter);

Takes a window out of the application; NULL is ignored. Its nodes answer as unknown objects from then on.

Parameters:

Thread safety. Main thread only.

MUI_NODISCARD MUI_API muiResult muiAtspiAdapter_Apply(muiAtspiAdapter* adapter, const muiAccessUpdate* update);

Applies an update to the adapter's tree (muiAccessTree_Apply).

Parameters:

Returns: As muiAccessTree_Apply; mui_errorInvalid for a NULL adapter; mui_errorBusy while the application is busy.

Thread safety. Main thread only.

const muiAccessTree* muiAtspiAdapter_GetTree(const muiAtspiAdapter* adapter);

The adapter's tree.

Parameters:

Returns: The tree; NULL for a NULL adapter.

Thread safety. Main thread only.

MUI_NODISCARD MUI_API muiResult muiAtspiAdapter_SetScale(muiAtspiAdapter* adapter, float scale);

Sets the pixels per unit, as the window's scale changes.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL adapter or a scale not above 0; mui_errorBusy while the application is busy.

Thread safety. Main thread only.

void muiAtspiAdapter_SetPlace(muiAtspiAdapter* adapter, int32_t x, int32_t y);

Sets where the window's client area is on the screen, in pixels, for clients asking in screen coordinates. Where the window system does not tell it (Wayland), leave it at 0, 0: screen coordinates are then the window's own, as GTK gives them.

Parameters:

Thread safety. Main thread only.

access_ns.h

The NSAccessibility adapter, the component MAUL_UI_NSACCESSIBILITY builds on macOS: the accessibility tree's consumer shown to AppKit's accessibility, one object a shown node that answers the NSAccessibility protocol. The window root's object is given to the view the tree lies in (Maul Window's mwinWindow_RequestAccessibilityRoot does that), whose child it is; clients' actions come back through a function of the host's. The header is C: AppKit's objects pass as void*. An adapter is busy while one of its functions that change it runs, or its allocator or action function runs, from those or from its platform's calls: a call back into one that changes it answers mui_errorBusy, NULL or false, or does nothing where it returns no status, as the destroy does.

static inline muiNsAdapterDef muiDefaultNsAdapterDef(void);

The default def: the C library's allocation, 4096 nodes, no view, a scale of 1, no action function.

Built in the program from the headers it includes, so it carries their version (MUI_ABI_VERSION), which muiCreateNsAdapter checks.

Returns: The def.

Thread safety. Safe from any thread.

MUI_NODISCARD MUI_API muiResult muiCreateNsAdapter(const muiNsAdapterDef* def, muiNsAdapter** adapterOut);

Makes an adapter with an empty tree.

Parameters:

Returns: mui_success; mui_errorVersion for a def built against headers of another binary interface (MUI_ABI_VERSION), before the rest of the def is read; mui_errorInvalid for a NULL argument, a def not from muiDefaultNsAdapterDef, a half-set allocator, no nodes, no view, no action function or a scale not above 0; mui_errorLimit for more than MUI_MAX_ACCESS_NODES nodes; mui_errorCapacity when memory runs out.

Thread safety. Main thread only.

void muiDestroyNsAdapter(muiNsAdapter* adapter);

Lets go of the adapter's objects, which answer nothing from then on, and destroys it; NULL is ignored. Take its root from the view first.

Parameters:

Thread safety. Main thread only.

uint64_t muiNsAdapter_GetMisuse(const muiNsAdapter* adapter);

Returns how many calls the adapter refused as invalid input (mui_errorInvalid) or as calls back in while busy (mui_errorBusy): a count release builds can watch to catch a host's bugs. Queries taking it as const count nothing.

Parameters:

Returns: The count; 0 for a NULL adapter.

Thread safety. Main thread only.

MUI_NODISCARD MUI_API muiResult muiNsAdapter_Apply(muiNsAdapter* adapter, const muiAccessUpdate* update);

Applies an update to the adapter's tree (muiAccessTree_Apply).

Parameters:

Returns: As muiAccessTree_Apply; mui_errorInvalid for a NULL adapter; mui_errorBusy while the adapter is busy.

Thread safety. Main thread only.

const muiAccessTree* muiNsAdapter_GetTree(const muiNsAdapter* adapter);

The adapter's tree.

Parameters:

Returns: The tree; NULL for a NULL adapter.

Thread safety. Main thread only.

MUI_NODISCARD MUI_API muiResult muiNsAdapter_SetScale(muiNsAdapter* adapter, float scale);

Sets the points per unit, as the host scales its UI.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL adapter or a scale not above 0; mui_errorBusy while the adapter is busy.

Thread safety. Main thread only.

void* muiNsAdapter_GetRoot(muiNsAdapter* adapter);

The window root's object, for the view to give as its child (mwinWindow_RequestAccessibilityRoot); the adapter keeps it while the root is the tree's.

Parameters:

Returns: The object (an NSAccessibilityElement), or NULL for an empty tree or a NULL adapter.

Thread safety. Main thread only.

access_tree.h

The accessibility tree's consumer, the component MAUL_UI_ACCESS_TREE builds: the copy of a root's accessibility tree that platform adapters read, kept from the updates muiNode_BuildAccessUpdate gives (maul-ui/access.h). Applying an update reports what it changed, so an adapter can raise its platform's events. A tree is used on one thread, the one its platform calls on: the window's, with UI Automation's COM threading on an STA thread. A tree is busy while one of its functions that change it runs or its allocator runs, from those or from its const queries: a call back into one that changes it answers mui_errorBusy, or does nothing where it returns no status.

static inline muiAccessTreeDef muiDefaultAccessTreeDef(void);

The default def: the C library's allocation, 4096 nodes, as many as a default context's.

Built in the program from the headers it includes, so it carries their version (MUI_ABI_VERSION), which muiCreateAccessTree checks.

Returns: The def.

Thread safety. Safe from any thread.

MUI_NODISCARD MUI_API muiResult muiCreateAccessTree(const muiAccessTreeDef* def, muiAccessTree** treeOut);

Creates an empty tree.

Parameters:

Returns: mui_success; mui_errorVersion for a def built against headers of another binary interface (MUI_ABI_VERSION), before the rest of the def is read; mui_errorInvalid for a NULL argument, a def not from muiDefaultAccessTreeDef, a half-set allocator or no nodes; mui_errorLimit for more than MUI_MAX_ACCESS_NODES; mui_errorCapacity when memory runs out.

Thread safety. Safe from any thread.

void muiDestroyAccessTree(muiAccessTree* tree);

Destroys a tree and all it holds; NULL is ignored.

Parameters:

Thread safety. Safe from any thread; the tree is used by one thread at a time.

uint64_t muiAccessTree_GetMisuse(const muiAccessTree* tree);

Returns how many calls the tree refused as invalid input (mui_errorInvalid) or as calls back in while busy (mui_errorBusy): a count release builds can watch to catch a host's bugs. Queries taking it as const count nothing.

Parameters:

Returns: The count; 0 for a NULL tree.

Thread safety. Safe from any thread; the tree is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiAccessTree_Apply(muiAccessTree* tree, const muiAccessUpdate* update, const muiAccessChanges* changes);

Applies an update whole, or nothing of it: the nodes sent replace those held, new ones join, and a node a parent sent no longer lists, which no other node sent lists, leaves with its subtree, as does a node sent with no parent that is not the root. A node the update both sends and lets go is told only as removed. The first update a tree takes, and any naming a new root, must be whole.

Parameters:

Returns: mui_success; mui_errorCapacity when the nodes would not fit or memory runs out, which changes nothing; mui_errorInvalid for a NULL tree or update, or an update that does not fit the tree: no root for an empty tree, a NULL node, a node with the id 0 or sent twice, children or links counted with no array, children past the update's childCount when it is not 0, a child neither held nor sent, a root, or focus, that is neither, or lists that do not leave a tree: a child listed twice, or by a node sent while a node not sent lists it, the root listed, or a node under itself; a node with a text that is not UTF-8 or holds a NUL; or a node whose marks do not fit its value text: offsets past it or inside a character, lines not ascending from 0, words out of order or empty; mui_errorLimit for a node with a text longer than MUI_MAX_TEXT_BYTES; mui_errorBusy while the tree is busy.

Thread safety. Safe from any thread; the tree is used by one thread at a time.

uint64_t muiAccessTree_GetRoot(const muiAccessTree* tree);

The root's id, or 0 for an empty tree.

Parameters:

Returns: The id.

Thread safety. Safe from any thread; the tree is used by one thread at a time.

uint64_t muiAccessTree_GetFocus(const muiAccessTree* tree);

The focused node's id, or 0 for an empty tree.

Parameters:

Returns: The id.

Thread safety. Safe from any thread; the tree is used by one thread at a time.

uint32_t muiAccessTree_GetNodeCount(const muiAccessTree* tree);

How many nodes the tree holds.

Parameters:

Returns: The count; 0 for NULL.

Thread safety. Safe from any thread; the tree is used by one thread at a time.

const muiAccessNode* muiAccessTree_Find(const muiAccessTree* tree, uint64_t id);

A node the tree holds: its texts and links are the tree's copies, valid until an update replaces or removes it; its firstChild is 0, and its children come from muiAccessTree_GetChildren.

Parameters:

Returns: The node; NULL for one not held or a NULL tree.

Thread safety. Safe from any thread; the tree is used by one thread at a time.

uint64_t muiAccessTree_GetParent(const muiAccessTree* tree, uint64_t id);

A node's parent.

Parameters:

Returns: The parent's id; 0 for the root, a node not held, or a NULL tree.

Thread safety. Safe from any thread; the tree is used by one thread at a time.

const uint64_t* muiAccessTree_GetChildren(const muiAccessTree* tree, uint64_t id, uint32_t* countOut);

A node's children, in order, valid until an update replaces it.

Parameters:

Returns: Their ids; NULL for none.

Thread safety. Safe from any thread; the tree is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiAccessTree_GetShownChildren(const muiAccessTree* tree, uint64_t id, uint64_t* childrenOut, uint32_t capacity, uint32_t* countOut);

A node's children as platforms see them, in order: generic children with no label replaced by their own, hidden ones left out with their subtrees, and under a node that clips its children, those wholly outside it left out with their subtrees unless a neighbour among them is not, so the first one past each edge can still be scrolled to. The focus is not left out for being hidden (nor what is in it), generic or clipped, though a hidden ancestor hides it; the root is always shown.

Parameters:

Returns: mui_success; mui_errorCapacity when they do not fit; mui_empty for a node not held; mui_errorInvalid for a NULL tree or count.

Thread safety. Safe from any thread; the tree is used by one thread at a time.

uint64_t muiAccessTree_GetShownParent(const muiAccessTree* tree, uint64_t id);

The nearest ancestor of a node that platforms see.

Parameters:

Returns: The ancestor's id; 0 for the root, a node not held, or a NULL tree.

Thread safety. Safe from any thread; the tree is used by one thread at a time.

bool muiAccessTree_IsShown(const muiAccessTree* tree, uint64_t id);

Whether platforms see a node: it is the root, or among its shown parent's shown children.

Parameters:

Returns: Whether it is shown; false for a node not held.

Thread safety. Safe from any thread; the tree is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiAccessTree_GetName(const muiAccessTree* tree, uint64_t id, char* bufferOut, size_t capacity, size_t* lengthOut);

A node's name: its label; else the texts of the nodes that label it (a label node's value, another's label), joined by spaces; else, for buttons, checkboxes, radio buttons, switches, links, menu items and tabs, those of the labels and images inside it, hidden subtrees left out.

Parameters:

Returns: mui_success; mui_empty for no name or a node not held; mui_errorCapacity when it does not fit, lengthOut giving the length; mui_errorInvalid for a NULL tree or length, or a NULL bufferOut with room.

Thread safety. Safe from any thread; the tree is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiAccessTree_GetBounds(const muiAccessTree* tree, uint64_t id, muiRect* boundsOut);

A node's bounds where the root is placed (the window's client area, for a root laid out in it): its bounds carried through its own transform and each ancestor's, the root's included, as the box around them.

Parameters:

Returns: mui_success; mui_empty for a node not held; mui_errorInvalid for a NULL argument.

Thread safety. Safe from any thread; the tree is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiAccessTree_GetTextRects(const muiAccessTree* tree, uint64_t id, size_t start, size_t end, muiRect* rectsOut, uint32_t capacity, uint32_t* countOut);

The rectangles of a node's value text from one byte offset up to another, where the root is placed (as muiAccessTree_GetBounds): for each line, the box around its clusters with bytes in the range, carried through the transforms. A range no cluster has bytes of (empty, or a line break alone) has none.

Parameters:

Returns: mui_success; mui_empty for a node not held or whose text has no clusters (none given), the count 0; mui_errorCapacity when there are more than capacity; mui_errorInvalid for a NULL tree or count, or NULL rectangles with a capacity.

Thread safety. Safe from any thread; the tree is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiAccessTree_GetTextOffsetAt(const muiAccessTree* tree, uint64_t id, float x, float y, size_t* offsetOut);

The character of a node's value text at a point where the root is placed: on the line whose box holds the point, or the nearest, the cluster whose edges hold it, or the nearest; a line with no clusters gives its start.

Parameters:

Returns: mui_success; mui_empty for a node not held, whose text has no clusters (none given), or whose transforms flatten it; mui_errorInvalid for a NULL argument or a point not finite.

Thread safety. Safe from any thread; the tree is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiAccessTree_Write(const muiAccessTree* tree, char* bufferOut, size_t capacity, size_t* lengthOut);

Writes the tree as text, a node a line in tree order, indented by depth: its role's name, its id's index, and its flags, actions, size, place, texts, selection and counts of lines and words where it has them. Tests compare it.

Parameters:

Returns: mui_success; mui_errorCapacity when it does not fit, lengthOut giving the length; mui_errorInvalid for a NULL tree or length, or a NULL bufferOut with room.

Thread safety. Safe from any thread; the tree is used by one thread at a time.

const char* muiGetAccessRoleName(muiRole role);

A role's name, as its constant's after mui_role with a lower-case first letter: "button" for mui_roleButton.

Parameters:

Returns: The name; "unknown" for a role past MUI_ROLE_LAST.

Thread safety. Safe from any thread.

access_uia.h

The UI Automation adapter, the component MAUL_UI_UIA builds on Windows: the accessibility tree's consumer shown to UI Automation through a provider object per node. The host hands the adapter's root to its window (mwinWindow_RequestAccessibilityRoot of Maul Window, or its own WM_GETOBJECT through muiUiaAdapter_HandleGetObject) and applies the core's updates through the adapter. Clients' actions come back through a function of the host's. An adapter lives on its window's thread, which must be in a COM single-threaded apartment (OleInitialize or CoInitializeEx with COINIT_APARTMENTTHREADED): UI Automation calls its providers there, as its window's messages are dispatched. "Main thread" below means that thread. An adapter is busy while one of its functions that change it runs, or its allocator or action function runs, from those or from its platform's calls: a call back into one that changes it answers mui_errorBusy, NULL or false, or does nothing where it returns no status, as the destroy does.

static inline muiUiaAdapterDef muiDefaultUiaAdapterDef(void);

The default def: the C library's allocation, 4096 nodes, a scale of 1, and no window or action function.

Built in the program from the headers it includes, so it carries their version (MUI_ABI_VERSION), which muiCreateUiaAdapter checks.

Returns: The def.

Thread safety. Safe from any thread.

MUI_NODISCARD MUI_API muiResult muiCreateUiaAdapter(const muiUiaAdapterDef* def, muiUiaAdapter** adapterOut);

Creates an adapter with an empty tree.

Parameters:

Returns: mui_success; mui_errorVersion for a def built against headers of another binary interface (MUI_ABI_VERSION), before the rest of the def is read; mui_errorInvalid for a NULL argument, a def not from muiDefaultUiaAdapterDef, a half-set allocator, no nodes, no window, no action function or a scale not above 0; mui_errorPlatform when the thread is not in a single-threaded apartment or UI Automation cannot be loaded; mui_errorLimit for more than MUI_MAX_ACCESS_NODES nodes; mui_errorCapacity when memory runs out.

Thread safety. Main thread only.

void muiDestroyUiaAdapter(muiUiaAdapter* adapter);

Destroys an adapter; NULL is ignored. Every provider object it gave out answers UIA_E_ELEMENTNOTAVAILABLE from then on, and UI Automation is told to let go of each. Take the root from the window first.

Parameters:

Thread safety. Main thread only.

uint64_t muiUiaAdapter_GetMisuse(const muiUiaAdapter* adapter);

Returns how many calls the adapter refused as invalid input (mui_errorInvalid) or as calls back in while busy (mui_errorBusy): a count release builds can watch to catch a host's bugs. Queries taking it as const count nothing.

Parameters:

Returns: The count; 0 for a NULL adapter.

Thread safety. Main thread only.

MUI_NODISCARD MUI_API muiResult muiUiaAdapter_Apply(muiUiaAdapter* adapter, const muiAccessUpdate* update);

Applies an update to the adapter's tree (muiAccessTree_Apply); the provider objects of nodes it removes answer UIA_E_ELEMENTNOTAVAILABLE from then on.

Parameters:

Returns: As muiAccessTree_Apply; mui_errorInvalid for a NULL adapter; mui_errorBusy while the adapter is busy.

Thread safety. Main thread only.

const muiAccessTree* muiUiaAdapter_GetTree(const muiUiaAdapter* adapter);

The adapter's tree.

Parameters:

Returns: The tree; NULL for a NULL adapter.

Thread safety. Main thread only.

void* muiUiaAdapter_GetRoot(muiUiaAdapter* adapter);

The root's provider, an IRawElementProviderSimple*, for mwinWindow_RequestAccessibilityRoot; it stands for whatever node is the tree's root, and lives while the adapter does. No reference is added for the caller.

Parameters:

Returns: The provider; NULL for a NULL adapter.

Thread safety. Main thread only.

bool muiUiaAdapter_HandleGetObject(muiUiaAdapter* adapter, uintptr_t wParam, intptr_t lParam, intptr_t* resultOut);

Answers WM_GETOBJECT for a window procedure of the host's own: for UiaRootObjectId, gives UI Automation the root.

Parameters:

Returns: Whether it answered; when not, the message goes on to DefWindowProc.

Thread safety. Main thread only.

MUI_NODISCARD MUI_API muiResult muiUiaAdapter_SetScale(muiUiaAdapter* adapter, float scale);

Sets the pixels per unit, as the window's DPI changes.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL adapter or a scale not above 0; mui_errorBusy while the adapter is busy.

Thread safety. Main thread only.

access_uikit.h

The UIAccessibility adapter, the component MAUL_UI_UIACCESSIBILITY builds on iOS: the accessibility tree's consumer shown to UIKit's accessibility, an element object a shown node, and a container object a shown node with shown children whose elements are its node's element and then its children. The root's object is given to the view the tree lies in (Maul Window's mwinWindow_RequestAccessibilityRoot does that), its container; clients' actions come back through a function of the host's. The header is C: UIKit's objects pass as void*. An adapter is busy while one of its functions that change it runs, or its allocator or action function runs, from those or from its platform's calls: a call back into one that changes it answers mui_errorBusy, NULL or false, or does nothing where it returns no status, as the destroy does.

static inline muiUikitAdapterDef muiDefaultUikitAdapterDef(void);

The default def: the C library's allocation, 4096 nodes, no view, a scale of 1, no action function.

Built in the program from the headers it includes, so it carries their version (MUI_ABI_VERSION), which muiCreateUikitAdapter checks.

Returns: The def.

Thread safety. Safe from any thread.

MUI_NODISCARD MUI_API muiResult muiCreateUikitAdapter(const muiUikitAdapterDef* def, muiUikitAdapter** adapterOut);

Makes an adapter with an empty tree.

Parameters:

Returns: mui_success; mui_errorVersion for a def built against headers of another binary interface (MUI_ABI_VERSION), before the rest of the def is read; mui_errorInvalid for a NULL argument, a def not from muiDefaultUikitAdapterDef, a half-set allocator, no nodes, no view, no action function or a scale not above 0; mui_errorLimit for more than MUI_MAX_ACCESS_NODES nodes; mui_errorCapacity when memory runs out.

Thread safety. Main thread only.

void muiDestroyUikitAdapter(muiUikitAdapter* adapter);

Lets go of the adapter's objects, which answer nothing from then on, and destroys it; NULL is ignored. Take its root from the view first.

Parameters:

Thread safety. Main thread only.

uint64_t muiUikitAdapter_GetMisuse(const muiUikitAdapter* adapter);

Returns how many calls the adapter refused as invalid input (mui_errorInvalid) or as calls back in while busy (mui_errorBusy): a count release builds can watch to catch a host's bugs. Queries taking it as const count nothing.

Parameters:

Returns: The count; 0 for a NULL adapter.

Thread safety. Main thread only.

MUI_NODISCARD MUI_API muiResult muiUikitAdapter_Apply(muiUikitAdapter* adapter, const muiAccessUpdate* update);

Applies an update to the adapter's tree (muiAccessTree_Apply).

Parameters:

Returns: As muiAccessTree_Apply; mui_errorInvalid for a NULL adapter; mui_errorBusy while the adapter is busy.

Thread safety. Main thread only.

const muiAccessTree* muiUikitAdapter_GetTree(const muiUikitAdapter* adapter);

The adapter's tree.

Parameters:

Returns: The tree; NULL for a NULL adapter.

Thread safety. Main thread only.

MUI_NODISCARD MUI_API muiResult muiUikitAdapter_SetScale(muiUikitAdapter* adapter, float scale);

Sets the points per unit, as the host scales its UI.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL adapter or a scale not above 0; mui_errorBusy while the adapter is busy.

Thread safety. Main thread only.

void* muiUikitAdapter_GetRoot(muiUikitAdapter* adapter);

The root's object, for the view to give as its element (mwinWindow_RequestAccessibilityRoot): its container when it has shown children, else its element. The adapter keeps it while it is the root's object; ask again after an update.

Parameters:

Returns: The object (a UIAccessibilityElement), or NULL for an empty tree or a NULL adapter.

Thread safety. Main thread only.

context.h

The context: the root object that owns a tree of nodes and every result computed over it. A context is busy while one of its functions that changes it runs. Host code it calls then (the measure, baseline, paint and access text functions, the allocator) may read it, and a function that changes it answers mui_errorBusy and counts one misuse; muiDestroyContext does nothing. The event function is the exception: the context is not busy while it runs, and it may call all but the functions muiEventFunction names. A text call given a muiTextHost (maul-ui/text.h) keeps the context busy in the same way while it runs.

static inline muiContextDef muiDefaultContextDef(void);

Returns the default context def: 4,096 nodes, 256 styles, 64 node types, 1,024 property sets, 64 notifications, 64 transitions, 256 running transitions, 256 tokens, 1,024 token names, 16 themes, 512 theme overrides, draw lists of 8,192 commands, 256 clips, 256 gradients, 16,384 glyphs and 64 transforms, 64 layers, 16 pointers and 64 pointer records, 256 neighbors, 64 ranges, 16 popups, 64 exits, 8 virtual lists of 16,384 estimated items together, 512 nodes with accessibility data and 4 accessibility roots, and the C library's allocator.

Built in the program from the headers it includes, so it carries their version (MUI_ABI_VERSION), which the context checks.

Returns: The def, with a valid cookie.

Thread safety. Safe from any thread.

MUI_NODISCARD MUI_API muiResult muiCreateContext(const muiContextDef* def, muiContext** contextOut);

Creates a context and reserves the memory its limits name.

Parameters:

Returns: mui_success; mui_errorVersion for a def built against headers of another binary interface (MUI_ABI_VERSION), before the rest of the def is read; mui_errorInvalid for a NULL argument, a bad cookie, a half-set allocator or a node limit of 0; mui_errorLimit for a limit past its maximum; mui_errorCapacity when the allocator cannot give the memory.

Thread safety. Safe from any thread.

void muiDestroyContext(muiContext* context);

Destroys a context, every node in it and its memory. Every id it gave out becomes meaningless. A call while the context is busy, as from host code it runs, or from its event function, destroys nothing and counts one misuse.

Parameters:

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiContext_TakeNotification(muiContext* context, muiNotification* notificationOut);

Takes the oldest notification.

Parameters:

Returns: mui_success; mui_empty when none is waiting; mui_errorInvalid for a NULL argument; mui_errorBusy while the context is busy.

Thread safety. Safe from any thread; the context is used by one thread at a time.

uint64_t muiContext_GetMisuse(const muiContext* context);

Returns how many calls the context has refused as invalid input (mui_errorInvalid) or as calls back in while it was busy (mui_errorBusy): a count release builds can watch to catch a host's bugs. Stale ids are not misuse, data another program controls (mui_errorFormat) is not, and queries taking the context as const count nothing.

Parameters:

Returns: The count; 0 for a NULL context.

Thread safety. Safe from any thread; the context is used by one thread at a time.

muiWorkCounts muiContext_GetWorkCounts(const muiContext* context);

Returns the work a context has done since it was made.

Parameters:

Returns: The counts; all 0 for a NULL context.

Thread safety. Safe from any thread; the context is used by one thread at a time.

draw.h

The draw-command list: what a renderer draws for a subtree, as fixed-size records in paint order, each with an index into a clip table and a transform table, so that a renderer evaluates clips per command and batches across them. Coordinates are logical units; colors are linear light with premultiplied alpha. Identical trees give byte-identical lists.

MUI_NODISCARD MUI_API muiResult muiDrawSink_AddGlyphRun(muiDrawSink* sink, const muiGlyphRun* run, const muiGlyph* glyphs, uint32_t glyphCount);

Adds a run of glyphs to the node being painted, after what it added before, in the clip its children are drawn in. Its color is converted to linear light and multiplied by the node's opacity; at the identity transform its baseline snaps to a device pixel.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL argument, no glyphs, a size that is not a finite number above 0, a color outside 0 to 1, or an origin or a position that is not finite; mui_errorCapacity when the list needs more commands or glyphs than the context's limits, which fails the build.

Thread safety. Safe from any thread; the sink is used by one thread at a time, and only during the call of the paint function given it.

MUI_NODISCARD MUI_API muiResult muiDrawSink_AddRect(muiDrawSink* sink, muiRect rect, muiColor color);

Adds a filled rectangle to the node being painted, after what it added before, in the clip its children are drawn in: a box command with no radii, borders or gradient. At the identity transform its edges snap to device pixels, and a side that was not empty keeps one, so a thin line never vanishes. Its color is converted as a glyph run's.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL sink, a rectangle not finite or of a negative size, or a color outside 0 to 1; mui_errorCapacity when the list needs more commands than the context's limits, which fails the build.

Thread safety. Safe from any thread; the sink is used by one thread at a time, and only during the call of the paint function given it.

MUI_NODISCARD MUI_API muiResult muiDrawSink_Fail(muiDrawSink* sink);

Tells the build that the paint function could not paint all it had to, as when memory ran out: muiNode_BuildDrawList keeps what it added and answers mui_errorCapacity, and the next build paints the node again rather than copying it.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL sink.

Thread safety. Safe from any thread; the sink is used by one thread at a time, and only during the call of the paint function given it.

MUI_NODISCARD MUI_API muiResult muiDrawSink_GetVisibleRect(const muiDrawSink* sink, muiRect* rectOut);

Gives the part of the content box's plane the paint function's content can be seen in: within the surface and every clip it is drawn in, through the scales and scroll offsets above it. Rounded corners are taken as their rectangles, so the part may be larger than what shows, never smaller. A paint function may leave out what lies outside it.

A node whose paint function asks is painted again by every build rather than copied from the last list, scrolling alone included, as what can be seen changes with it; a function that paints much gains, one that paints little need not ask.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL argument.

Thread safety. Safe from any thread; the sink is used by one thread at a time, and only during the call of the paint function given it.

MUI_NODISCARD MUI_API muiResult muiNode_BuildDrawList(muiContext* context, muiNodeId rootId, const muiDrawInput* input);

Paints a root's subtree, as its last muiNode_ComputeLayout left it, into the context's list, and clears the subtree's paint requests. When nothing below the root asked for paint since the last build of the same root, surface and scale, the list stays as it is, generation and all; otherwise subtrees nothing asked to repaint, at the origin and opacity they were painted at, copy their commands from the last list, which gives the bytes a build from nothing would. Per node, in paint order: its outer shadow, its box, its inner shadow, its image and what the paint function adds for host content, then its children, depth first; a node that clips draws its host content and its children inside its rounded border box. Opacity multiplies down the subtree into every command's colors. At the identity transform, box and image edges and clips snap to device pixels, and border widths to whole device pixels, at least one.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL argument, the null id or a scale that is not a finite number above 0; mui_errorBusy while the context is busy; mui_errorStale for a root that is gone; mui_errorCapacity when the list needs more commands, clips, gradients or glyphs than the context's limits, which leaves the list empty, or when a paint function could not paint (muiDrawSink_Fail), which leaves the rest of the list and paints that node again in the next build.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiContext_GetDrawList(const muiContext* context, muiDrawList* listOut);

Shows the context's last list.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL argument.

Thread safety. Safe from any thread; the context is used by one thread at a time.

event.h

Routed input: keys, text and navigation go to a player's focus, pointer records to their node, each along the target's ancestors, top down and then back up, through one function of the host's that says whether it handled the event. What the UI leaves unhandled is the game's.

MUI_NODISCARD MUI_API muiResult muiContext_SetEventFunction(muiContext* context, muiEventFunction function, void* user);

Sets the function routed events go to; NULL routes nothing, so every input is unhandled but for the library's defaults.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL context; mui_errorBusy while the context is busy or its event function runs.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiNode_RouteKey(muiContext* context, muiNodeId rootId, const muiKeyEvent* event, bool* handledOut);

Routes a key to the player's focus under the root (a focus a modal layer covers: the top modal layer under the root; none: the root). Unhandled, a key down does what the library does by default: Tab, with Shift or not and no other modifier, moves the focus as muiNode_MoveFocus does. Escape cancels every drag going (maul-ui/pointer.h). On a focused range (maul-ui/range.h), the unmodified keys of ARIA's slider pattern change its value: arrows along its axis a step, Page Up and Down a page, Home and End the ends. Else an arrow without modifiers, when the focus is in a scroll container along its axis (maul-ui/scroll.h), moves the focus to the candidate directional navigation finds inside it if that lies within half a scrollport of the visible part (or a link leads out), else steps the container a line while it can move, as Android's ScrollView does; otherwise it moves the focus as muiNode_MoveFocusToward does. Page Up and Down, Home and End without modifiers, and Space with Shift or not and no other modifier, step the vertical scroll container holding the focus a page or to an end. What moves is handled. A key down makes the player's next focus by code shown.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL argument, the null id or an event outside the above; mui_errorBusy while the context is busy or its event function runs; mui_errorStale for a root that is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiNode_RouteText(muiContext* context, muiNodeId rootId, const muiTextEvent* event, bool* handledOut);

Routes text to the player's focus under the root, as muiNode_RouteKey routes a key; text has no default.

Parameters:

Returns: As muiNode_RouteKey's; mui_errorLimit for a length past MUI_MAX_TEXT_BYTES; mui_errorBusy while the context is busy or its event function runs.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiNode_RouteNavigation(muiContext* context, muiNodeId rootId, const muiNavigationEvent* event, bool* handledOut);

Routes a navigation action to the player's focus under the root, as muiNode_RouteKey routes a key. Unhandled, the four directions do what arrows do, a focused range's included, next and previous move the focus as muiNode_MoveFocus does; a move is handled. Activate and cancel have no default. It makes the player's next focus by code shown.

Parameters:

Returns: As muiNode_RouteKey's; mui_errorBusy while the context is busy or its event function runs.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiNode_RouteWheel(muiContext* context, muiNodeId rootId, const muiWheelEvent* event, bool* handledOut);

Routes a wheel turn to the node under its point, as muiNode_HitTest finds it; a point over nothing is routed nowhere and not handled. Unhandled, it scrolls by the scroll rule's step a detent (maul-ui/scroll.h): the scroll container it scrolled last, while turns keep coming within the rule's latch time and the point stays over that container; otherwise the nearest scroll container from the node up that can move that way, not past the root of the node's layer. Shift turns a vertical-only turn horizontal, as on Windows. A turn a scroll container takes is handled, even at its end while latched.

Parameters:

Returns: As muiNode_RouteKey's; mui_errorBusy while the context is busy or its event function runs.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiContext_DispatchPointerRecord(muiContext* context, const muiPointerRecord* record, bool* handledOut);

Routes a pointer record (muiContext_TakePointerRecord) to its node; a record with no node, or one gone, is routed nowhere and not handled. Unhandled, a press on a range or inside it, and a drag of one or of a node inside it, change its value (maul-ui/range.h), and are handled. The host hands what is not handled and passes through to the game.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL argument; mui_errorBusy while the context is busy or its event function runs.

Thread safety. Safe from any thread; the context is used by one thread at a time.

exit.h

Exit transitions: a node the host removes plays its way out before it goes. Beginning an exit gives the node the exiting state, so its classes' exiting variants and their transitions apply; the node and its subtree leave hit testing, focus and navigation at once, and focus inside it is given up: back to what the player focused when the outermost layer around it in the subtree became one, if that can still take it. When no transition runs in the subtree any more, at a layout, mui_notificationExitFinished reports it, once; the library never destroys the node. The host destroys it then, or earlier, which ends the exit, or cancels the exit to bring it back.

MUI_NODISCARD MUI_API muiResult muiNode_BeginExit(muiContext* context, muiNodeId nodeId);

Begins a node's exit; nothing for a node already exiting.

Parameters:

Returns: mui_success; mui_errorCapacity when the context holds its limit of exits; mui_errorInvalid for a NULL context or the null id; mui_errorBusy while the context is busy; mui_errorStale for a node that is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiNode_CancelExit(muiContext* context, muiNodeId nodeId);

Cancels a node's exit: the exiting state goes, and the node and its subtree take input again; nothing for a node not exiting.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL context or the null id; mui_errorBusy while the context is busy; mui_errorStale for a node that is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

focus.h

Focus: the node each player's keys and gamepad go to, one per player slot for local multiplayer, moved by code, pointer presses and sequential navigation, and shown as the input that moved it calls for.

MUI_NODISCARD MUI_API muiResult muiContext_SetFocus(muiContext* context, uint8_t player, muiNodeId nodeId, muiFocusCause cause);

Moves a player's focus to a node, or takes it away. A node takes focus when its focus mode (as its last style resolution or direct write left it) is not mui_focusNone, it is neither disabled nor exiting, and no modal layer covers it. The node gets mui_stateFocused, and mui_stateFocusVisible when the focus is shown; a focus that moves posts mui_notificationFocusLost for the node it leaves and mui_notificationFocusGained for the one it reaches, with the player as the count.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL context, a player or cause outside the above or a node that takes no focus, which changes nothing; mui_errorBusy while the context is busy; mui_errorStale for a node that is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

muiNodeId muiContext_GetFocus(const muiContext* context, uint8_t player);

Returns the node a player focuses.

Parameters:

Returns: The node; the null id for none, a NULL context or a player past MUI_MAX_PLAYERS.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiNode_MoveFocus(muiContext* context, muiNodeId rootId, uint8_t player, bool backward);

Moves a player's focus to the next or previous node in sequential order (Tab and Shift+Tab), shown. The order runs over the nodes whose focus mode is mui_focusAll in the layer that holds the focus: a layer's subtree, or the root's subtree, without the layers in it; those with a tab order of 1 to 255 first, ascending, then the rest, ties in tree order; it wraps. With no focus under the root, or one a modal layer covers, it starts in the top modal layer under the root, or else the root's own content.

Parameters:

Returns: mui_success; mui_empty when no node there takes focus, which leaves it; mui_errorInvalid for a NULL context, the null id or a player past MUI_MAX_PLAYERS; mui_errorBusy while the context is busy; mui_errorStale for a root that is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiNode_MoveFocusToward(muiContext* context, muiNodeId rootId, uint8_t player, muiDirection direction);

Moves a player's focus toward a direction on the screen (arrow keys, a gamepad's pad or stick), shown. A link the focused node has for the direction (muiNode_SetNeighbor) to a node that takes focus wins; a link to the node itself stops the move. Otherwise the nearest node in the direction is found as Android's focus search finds it, among the nodes sequential navigation reaches in the same layer: nodes overlapping the focus across the direction first, then the least of 13 times the square of the gap along the direction plus the square of the distance between centers across it, ties to the earlier in tree order. Boxes are as the last muiNode_ComputeLayout left them. With no focus under the root, or one a modal layer covers, it moves as muiNode_MoveFocus does forward.

Parameters:

Returns: mui_success; mui_empty when nothing lies that way, which leaves the focus; mui_errorInvalid for a NULL context, the null id, a player past MUI_MAX_PLAYERS or an unknown direction; mui_errorBusy while the context is busy; mui_errorStale for a root that is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiNode_SetNeighbor(muiContext* context, muiNodeId nodeId, muiDirection direction, muiNodeId targetId);

Links a node to the node directional navigation moves to from it in a direction, over what geometry would find; the node itself stops movement that way. Links to nodes that do not take focus when the move is made leave it to geometry.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL context, the null id as the node or an unknown direction; mui_errorBusy while the context is busy; mui_errorStale for a node or target that is gone; mui_errorCapacity past the context's neighbors limit.

Thread safety. Safe from any thread; the context is used by one thread at a time.

muiNodeId muiNode_GetNeighbor(const muiContext* context, muiNodeId nodeId, muiDirection direction);

Returns the node a node links to in a direction.

Parameters:

Returns: The target, which may be gone since; the null id for no link, a NULL context, a node that is gone or an unknown direction.

Thread safety. Safe from any thread; the context is used by one thread at a time.

font.h

Fonts of a text service: TrueType and OpenType fonts and collections, from memory. Font files are hostile input: a font is validated when it is created, and compressed web fonts (WOFF, WOFF2) are refused as unsupported.

muiFontDef muiDefaultFontDef(void);

Returns the default font def: no data, face 0, copied.

Returns: The def, with a valid cookie.

Thread safety. Safe from any thread.

MUI_NODISCARD MUI_API muiResult muiCountFontFaces(const void* data, size_t size, uint32_t* countOut);

Counts the faces of a font file without reading them: 1 for a single font, the number a collection declares for a collection. Allocates nothing.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL argument; mui_errorUnsupported for a compressed web font (WOFF, WOFF2); mui_errorFormat for other data that is not a TrueType or OpenType font or collection, or a collection whose header does not fit in size.

Thread safety. Safe from any thread.

MUI_NODISCARD MUI_API muiResult muiCreateFont(muiTextService* service, const muiFontDef* def, muiFontId* fontOut);

Creates a font from a face of a font file, validating it.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL argument, a bad cookie or an unknown data mode, each counted as misuse; mui_errorFormat, counted as none, for data that is not a font the service reads (shorter than a header, longer than 2^31 - 1 bytes, or malformed), a face index past the file's faces, or a font that fails validation; mui_errorUnsupported for a compressed web font (WOFF, WOFF2); mui_errorCapacity past the font limit or when memory runs out; mui_errorBusy while the service is busy.

Thread safety. Safe from any thread; the service is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiDestroyFont(muiTextService* service, muiFontId fontId);

Destroys a font, which releases a copy of its bytes or ends the borrow of the caller's.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL service or the null id; mui_errorStale for a font that is gone; mui_errorBusy while the service is busy.

Thread safety. Safe from any thread; the service is used by one thread at a time.

bool muiFont_IsValid(const muiTextService* service, muiFontId fontId);

Tells whether an id names a font of the service that still exists.

Parameters:

Returns: true for a live font; false otherwise.

Thread safety. Safe from any thread; the service is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiFont_GetMetrics(const muiTextService* service, muiFontId fontId, muiFontMetrics* metricsOut);

Reads a font's metrics.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL argument or the null id; mui_errorStale for a font that is gone.

Thread safety. Safe from any thread; the service is used by one thread at a time.

muiFontFamilyDef muiDefaultFontFamilyDef(void);

Returns the default font family def: no faces and no fallbacks.

Returns: The def, with a valid cookie.

Thread safety. Safe from any thread.

MUI_NODISCARD MUI_API muiResult muiCreateFontFamily(muiTextService* service, const muiFontFamilyDef* def, muiFontFamilyId* familyOut);

Creates a family of fonts, which a text style names by its key (muiFontFamily_GetKey): text is laid out in the face the style's weight and slant choose, as CSS matches faces (width nearest to normal, then italic, oblique and normal faces in CSS's order for the slant, then the weight in CSS's order), then in the instance of it they make. A face destroyed later is passed over.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL argument, a bad cookie, NULL faces or fallbacks with a count, no faces, or a fallback that is no font's or family's key; mui_errorLimit for more faces or fallbacks than the maximum; mui_errorStale for a face or fallback that is gone, or the null id; mui_errorCapacity past the family limit or when memory runs out; mui_errorBusy while the service is busy.

Thread safety. Safe from any thread; the service is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiDestroyFontFamily(muiTextService* service, muiFontFamilyId familyId);

Destroys a family; its faces stay.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL service or the null id; mui_errorStale for a family that is gone; mui_errorBusy while the service is busy.

Thread safety. Safe from any thread; the service is used by one thread at a time.

bool muiFontFamily_IsValid(const muiTextService* service, muiFontFamilyId familyId);

Tells whether an id names a family of the service that still exists.

Parameters:

Returns: true for a live family; false otherwise.

Thread safety. Safe from any thread; the service is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiFontFamily_MatchFace(const muiTextService* service, muiFontFamilyId familyId, float weight, muiFontSlant slant, muiFontId* faceOut);

Finds the face of a family a weight and slant choose, as text laid out in the family is.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL argument, the null id, or a weight or slant out of range; mui_errorStale for a family that is gone or whose faces all are.

Thread safety. Safe from any thread; the service is used by one thread at a time.

glyph_atlas.h

Glyph atlases: glyph images of a text service's fonts, rendered as muiTextService_RenderGlyph, muiTextService_RenderGlyphField and muiTextService_RenderGlyphMultiField render them and packed into pages a renderer uploads as textures. An atlas's pages are of one format: one byte a pixel, holding coverage and distance fields both, four holding multi-channel fields, or four holding colour glyphs; a renderer wanting several makes an atlas of each, so their pages never share an index space. Pages are split into plots; when no plot has room, the least recently used plot that the current frame has not used is emptied and packed again. The atlas keeps the pages' pixels and tells which rectangles changed; it uses no graphics API.

muiGlyphAtlasDef muiDefaultGlyphAtlasDef(void);

Returns the default atlas def: pages of 1,024 by 1,024 in plots of 256 by 256, at most 4 pages, a byte a pixel.

Returns: The def, with a valid cookie.

Thread safety. Safe from any thread.

MUI_NODISCARD MUI_API muiResult muiCreateGlyphAtlas(muiTextService* service, const muiGlyphAtlasDef* def, muiGlyphAtlas** atlasOut);

Creates an atlas of a text service's glyphs, in the service's memory. It is destroyed before the service.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL argument, a bad cookie, plots that do not divide the pages, no pages or an unknown format; mui_errorLimit for sides, plots or pages past the bounds above; mui_errorCapacity when memory runs out; mui_errorBusy while the service is busy.

Thread safety. Safe from any thread; the service is used by one thread at a time.

void muiDestroyGlyphAtlas(muiGlyphAtlas* atlas);

Destroys an atlas and its pages. A call while the atlas is busy destroys nothing and counts one misuse on its service.

Parameters:

Thread safety. Safe from any thread; the atlas is used by one thread at a time.

void muiGlyphAtlas_BeginFrame(muiGlyphAtlas* atlas);

Starts a frame: glyphs got before it may be evicted to make room. A call while the atlas is busy does nothing and counts one misuse on its service.

Parameters:

Thread safety. Safe from any thread; the atlas is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiGlyphAtlas_GetGlyph(muiGlyphAtlas* atlas, uint64_t font, uint32_t glyph, float pixelSize, float penX, float baselineY, muiAtlasGlyph* glyphOut);

Gets a glyph's image for a pen in device pixels, rendering and packing it the first time. The pen's x is taken to the nearest quarter pixel and its baseline to the nearest pixel; the font key 0 is the default font's. The glyph's plot is kept until a later frame.

Parameters:

Returns: mui_success; mui_errorCapacity when the image is larger than a plot, every plot is in use this frame, or memory runs out; mui_errorInvalid for a NULL atlas or glyphOut, a size that is not a finite number above 0, a position that is not finite, or a glyph id the font lacks; mui_errorLimit for a size outside MUI_MIN_GLYPH_PIXEL_SIZE to MUI_MAX_GLYPH_PIXEL_SIZE, or a position past MUI_MAX_ATLAS_PEN; mui_errorUnsupported for an atlas of another format; mui_errorStale for a key that names no font; mui_errorFormat for a glyph that cannot be rendered; mui_errorBusy while the atlas is busy.

Thread safety. Safe from any thread; the atlas is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiGlyphAtlas_GetColorGlyph( muiGlyphAtlas* atlas, uint64_t font, uint32_t glyph, float pixelSize, float penX, float baselineY, uint32_t palette, muiLinearColor foreground, muiAtlasGlyph* glyphOut);

Gets a colour glyph's image from an atlas of colour glyphs for a pen in device pixels, rendering and packing it the first time, as muiTextService_RenderColorGlyph renders it and muiGlyphAtlas_GetGlyph places coverage. The text's colour is kept as 8-bit sRGB with straight alpha, and the glyph is rendered with it so kept: each palette and text colour is an image of its own. A glyph without colour layers gives mui_empty, to be drawn as coverage; a font without a COLR table gives it without looking.

Parameters:

Returns: As muiGlyphAtlas_GetGlyph, with mui_empty for a glyph without colour layers; mui_errorBusy while the atlas is busy.

Thread safety. Safe from any thread; the atlas is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiGlyphAtlas_GetGlyphField(muiGlyphAtlas* atlas, uint64_t font, uint32_t glyph, float pixelSize, uint32_t spread, muiAtlasGlyph* glyphOut);

Gets a glyph's distance field, rendering and packing it the first time, as muiTextService_RenderGlyphField renders it; the font key 0 is the default font's. A renderer draws it at any size s by scaling the image and its place, x and y from the pen and baseline, by s / pixelSize. The glyph's plot is kept until a later frame.

Parameters:

Returns: As muiGlyphAtlas_GetGlyph, with mui_errorLimit for a spread out of range; mui_errorBusy while the atlas is busy.

Thread safety. Safe from any thread; the atlas is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiGlyphAtlas_GetGlyphMultiField(muiGlyphAtlas* atlas, uint64_t font, uint32_t glyph, float pixelSize, uint32_t spread, muiAtlasGlyph* glyphOut);

Gets a glyph's multi-channel distance field from an atlas of four channels, rendering and packing it the first time, as muiTextService_RenderGlyphMultiField renders it; the font key 0 is the default font's. It is placed and drawn as muiGlyphAtlas_GetGlyphField's fields are, from the median of its red, green and blue, or from its alpha as a one-channel field. The glyph's plot is kept until a later frame.

Parameters:

Returns: As muiGlyphAtlas_GetGlyphField; mui_errorBusy while the atlas is busy.

Thread safety. Safe from any thread; the atlas is used by one thread at a time.

uint32_t muiGlyphAtlas_GetPageCount(const muiGlyphAtlas* atlas);

Returns how many pages the atlas has made.

Parameters:

Returns: The page count; pages are numbered from 0.

Thread safety. Safe from any thread; the atlas is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiGlyphAtlas_GetPage(const muiGlyphAtlas* atlas, uint32_t page, muiAtlasPage* pageOut);

Reads a page's pixels, which stay valid until the atlas is destroyed and change only in calls to muiGlyphAtlas_GetGlyph.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL argument or a page not made.

Thread safety. Safe from any thread; the atlas is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiGlyphAtlas_TakeUpdates(muiGlyphAtlas* atlas, muiAtlasUpdate* updatesOut, uint32_t capacity, uint32_t* countOut);

Takes the rectangles of pages that changed since the last call, a plot's changes as one rectangle, for the renderer to copy from the pages' pixels.

Parameters:

Returns: mui_success, taking them; mui_errorCapacity when updatesOut holds fewer, taking none; mui_errorInvalid for a NULL atlas or countOut, or NULL updatesOut with a capacity; mui_errorBusy while the atlas is busy.

Thread safety. Safe from any thread; the atlas is used by one thread at a time.

glyph_image.h

Glyph images: a glyph of a text service's font rendered for a renderer to draw, as 8-bit coverage or as a signed distance field that scales. Outlines are rendered unhinted, as text is laid out, so an image sits where its glyph run places it at every size; images are the same on every platform.

MUI_NODISCARD MUI_API muiResult muiTextService_RenderGlyph( muiTextService* service, uint64_t font, uint32_t glyph, float pixelSize, float offsetX, muiGlyphImage* imageOut, unsigned char* pixelsOut, size_t capacity);

Renders a glyph as coverage: a byte per pixel, rows from the top, 0 outside the outline to 255 inside, linear in the area covered (a renderer applies any gamma). A glyph with no outline, such as a space or any glyph of a font of bitmaps alone, has an empty image. A glyph run's glyph at (x, y) from its origin, drawn at a scale, has its pen at (originX + x) * scale and its baseline at (originY + y) * scale, y rounded to a pixel; its em is the run's size times the scale.

Parameters:

Returns: mui_success; mui_errorCapacity when pixelsOut holds fewer bytes than imageOut asks for, or memory runs out; mui_errorInvalid for a NULL service or imageOut, NULL pixelsOut with a capacity, a size that is not a finite number above 0, an offset outside the above, or a glyph id the font does not have; mui_errorLimit for a size outside the above; mui_errorStale for a key that names no font; mui_errorFormat for a glyph whose outline cannot be read or is too large to render; mui_errorBusy while the service is busy.

Thread safety. Safe from any thread; the service is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiTextService_RenderColorGlyph( muiTextService* service, uint64_t font, uint32_t glyph, float pixelSize, float offsetX, uint32_t palette, muiLinearColor foreground, muiGlyphImage* imageOut, unsigned char* pixelsOut, size_t capacity);

Renders a colour glyph (COLR, with its CPAL palettes) at a size, placed as muiTextService_RenderGlyph places coverage: four bytes a pixel, rows from the top, red, green, blue and alpha. A version 1 glyph's paint graph is drawn where the glyph has one: its layers, solid fills, gradients, glyph outlines, other colour glyphs, transforms, composites and clip box. A version 0 glyph's layers are each another glyph's outline filled with its palette entry. Entry 0xFFFF is the text's colour, and everything is composited in premultiplied linear light; the pixels are stored as an sRGB texture holds premultiplied colour, red, green and blue encoded with sRGB's transfer function and alpha linear. A glyph without COLR colour is drawn from its colour bitmap where the font has one (CBLC and CBDT, or sbix), from the strike that suits the size, scaled to it. A glyph without colour gives mui_empty and an empty image, to be drawn as coverage.

Parameters:

Returns: mui_success; mui_empty for a glyph without colour, as one whose CBLC index or CBDT record is malformed is; mui_errorFormat for a paint graph more than 64 paints deep, as one that paints itself is, a transform that places a glyph's box past where an outline may reach, a clip box whose maximum is below its minimum, a bitmap of 2^28 pixels or more, as 16384 by 16384 is, or a bitmap's PNG that does not decode, as one failing a checksum does; otherwise as muiTextService_RenderGlyph; mui_errorBusy while the service is busy.

Thread safety. Safe from any thread; the service is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiTextService_RenderGlyphField( muiTextService* service, uint64_t font, uint32_t glyph, float pixelSize, uint32_t spread, muiGlyphImage* imageOut, unsigned char* pixelsOut, size_t capacity);

Renders a glyph as a signed distance field, which a renderer scales to any size: a byte per pixel, rows from the top, 128 at the outline, and 128 / spread more for each pixel inside and less for each pixel outside, up to 255 and down to 0. The image reaches spread pixels past the outline on every side; drawn at a scale, it covers where a sample is 128 or more. Glyphs whose contours overlap, as variable fonts' and composite glyphs' may, are rendered as their union.

Parameters:

Returns: mui_success; mui_errorCapacity when pixelsOut holds fewer bytes than imageOut asks for, or memory runs out; mui_errorInvalid for a NULL service or imageOut, NULL pixelsOut with a capacity, a size that is not a finite number above 0, or a glyph id the font does not have; mui_errorLimit for a size or spread outside the above; mui_errorStale for a key that names no font; mui_errorFormat for a glyph whose outline cannot be read or is too large to render; mui_errorBusy while the service is busy.

Thread safety. Safe from any thread; the service is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiTextService_RenderGlyphMultiField( muiTextService* service, uint64_t font, uint32_t glyph, float pixelSize, uint32_t spread, muiGlyphImage* imageOut, unsigned char* pixelsOut, size_t capacity);

Renders a glyph's multi-channel signed distance field (MTSDF) for a renderer that scales it: four bytes a pixel. Red, green and blue are three distances, each to the outline's edges of one colour, and their median is the distance with the outline's corners kept sharp at any scale (Chlumský's method, as msdfgen's); alpha is the field muiTextService_RenderGlyphField renders, byte for byte, for outlines, glows and shadows. Each channel is 128 at its distance's 0 and 128 / spread more for each pixel inside, less outside, held within 0 and 255. The image is placed and sized as muiTextService_RenderGlyphField places it, and overlapping contours are their union.

Parameters:

Returns: As muiTextService_RenderGlyphField; mui_errorBusy while the service is busy.

Thread safety. Safe from any thread; the service is used by one thread at a time.

interaction.h

Interaction properties and hit testing: whether a node and its children are hit by a point, whether input it leaves unused passes through to what lies behind the UI, whether it roots a layer, and which node is topmost at a point, in reverse paint order.

muiInteractionStyle muiDefaultInteractionStyle(void);

Returns the default interaction values: hit in full, blocking, no layer, taking no focus.

Returns: The values.

Thread safety. Safe from any thread.

MUI_NODISCARD MUI_API muiResult muiStyle_SetInteractionValues(muiContext* context, muiStyleId styleId, muiVariant variant, const muiInteractionStyle* values, muiPropertyMask mask);

Sets interaction values of one variant of a class, as muiStyle_SetLayoutValues does layout ones.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL argument, the null id, an unknown variant or property bit or a value outside the above, which changes nothing; mui_errorBusy while the context is busy; mui_errorStale for an id whose class is gone; mui_errorCapacity when the variant had no values and the context's limit of property sets is reached.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiStyle_GetInteractionValues(const muiContext* context, muiStyleId styleId, muiVariant variant, muiInteractionStyle* valuesOut, muiPropertyMask* maskOut);

Reads the interaction values one variant of a class sets.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL argument, the null id or an unknown variant; mui_errorStale for an id whose class is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiNode_SetInteractionValues(muiContext* context, muiNodeId nodeId, const muiInteractionStyle* values, muiPropertyMask mask);

Writes interaction properties of a node directly, as muiNode_SetLayoutValues does layout ones; neither its layout nor its paint is redone.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL argument, the null id, an unknown property bit or a value outside the above, which changes nothing; mui_errorBusy while the context is busy; mui_errorStale for a node that is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiNode_GetInteractionStyle(const muiContext* context, muiNodeId nodeId, muiInteractionStyle* valuesOut);

Reads a node's resolved interaction values: its direct writes, and for the other properties what its classes and states gave at the last muiNode_ComputeLayout that reached it.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL argument or the null id; mui_errorStale for an id whose node is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiNode_HitTest(const muiContext* context, muiNodeId rootId, float x, float y, muiHit* hitOut);

Finds the topmost node of a root's subtree at a point, as its last muiNode_ComputeLayout left it: the last in paint order whose rounded border box holds the point, inside the rounded clips of every ancestor that clips and of no node whose hit mode leaves it out. Layers are tried from the top down, then the content they are not in; a point a modal layer's subtree misses hits the modal layer's root, blocked, and nothing below it. Opacity does not matter, as in CSS. Positions are those painting gives, the root at its own rectangle, through local scales: a node scaled to nothing on an axis is hit nowhere.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL argument, the null id or a point not finite; mui_errorStale for a root that is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiNode_RaiseLayer(muiContext* context, muiNodeId nodeId);

Raises a layer above the others of its band, as activating a window brings it to the front: it becomes the latest activated.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL context, the null id or a node that roots no layer; mui_errorBusy while the context is busy; mui_errorStale for a node that is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

layout.h

Layout: the authored values that size and place a node, the solver that computes rectangles from them (CSS Flexbox), and the rectangles it publishes. Lengths are logical units; a node's rectangle is relative to its parent's border box, and a root's rectangle starts at 0, 0.

muiLayoutStyle muiDefaultLayoutStyle(void);

Returns the default layout style: CSS's initial values (row, one line, no grow, shrink 1, automatic basis and sizes, stretched items and lines, start), no margins, borders or padding, and no content.

Returns: The style.

Thread safety. Safe from any thread.

MUI_NODISCARD MUI_API muiResult muiNode_GetLayoutStyle(const muiContext* context, muiNodeId nodeId, muiLayoutStyle* styleOut);

Reads a node's resolved layout values: its direct writes, and for the other properties what its classes and states gave at the last muiNode_ComputeLayout that reached it.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL argument or the null id; mui_errorStale for an id whose node is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

bool muiNode_IsRightToLeft(const muiContext* context, muiNodeId nodeId);

Whether a node's content runs right to left: the direction its own resolved layout values give, else the nearest ancestor's that gives one, else left to right. It reads the values as they are at the call, so a measure function sees the direction layout uses.

Parameters:

Returns: true for right to left; false for left to right, a NULL context, the null id or a node that is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiNode_MarkContentChanged(muiContext* context, muiNodeId nodeId);

Tells the solver a node's host content changed size, so it is measured again at the next muiNode_ComputeLayout.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL context or the null id; mui_errorBusy while the context is busy; mui_errorStale for an id whose node is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiNode_ComputeLayout(muiContext* context, muiNodeId rootId, const muiLayoutInput* input);

Lays out a root and its subtree in the given space. Subtrees that did not change since the last call are not visited.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL argument, the null id, a node with a parent or a negative or non-finite space; mui_errorBusy while the context is busy; mui_errorStale for an id whose node is gone; mui_errorCapacity when host content could not be measured (muiMeasureFunction), which is laid out as empty and measured again by the next call.

Thread safety. Safe from any thread; the context is used by one thread at a time.

bool muiNode_IsUpdatePending(const muiContext* context, muiNodeId rootId);

Returns whether muiNode_ComputeLayout on a root has work to do: an edit below it since its last run, a node whose conditions read a size or direction that run changed, which a following run styles again, a transition running below it, or a scroll step easing below it (maul-ui/scroll.h).

Parameters:

Returns: Whether work is pending; false for a stale id or a NULL context.

Thread safety. Safe from any thread; the context is used by one thread at a time.

muiRect muiNode_GetRect(const muiContext* context, muiNodeId nodeId);

Returns a node's border box from the last muiNode_ComputeLayout that reached it, relative to its parent's border box.

Parameters:

Returns: The rectangle; all zero before any layout, for a stale id or a NULL context.

Thread safety. Safe from any thread; the context is used by one thread at a time.

muiRect muiNode_GetContentRect(const muiContext* context, muiNodeId nodeId);

Returns a node's content box from the last muiNode_ComputeLayout that reached it, relative to its border box: inside its border and padding, the start's on the right in a right-to-left node, as its paint function and its text's carets are given it.

Parameters:

Returns: The rectangle; all zero before any layout, for a stale id or a NULL context.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiNode_MapToRoot(const muiContext* context, muiNodeId nodeId, float x, float y, float* xOut, float* yOut);

Carries a point of a node's border box into the space its topmost ancestor's rectangle is in, where pointer events are given, through its own and its ancestors' places, local scales and scroll containers' offsets as the last muiNode_ComputeLayout, styling and scrolling left them: so a host places a window's candidate box at a caret, or its own popup beside a node.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL argument or a point not finite; mui_errorStale for a node that is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

node.h

Nodes: the retained tree a host builds and edits through ids. A node without a parent is a root; each root is a separate tree.

muiNodeDef muiDefaultNodeDef(void);

Returns the default node def: host key 0.

Returns: The def, with a valid cookie.

Thread safety. Safe from any thread.

MUI_NODISCARD MUI_API muiResult muiCreateNode(muiContext* context, const muiNodeDef* def, muiNodeId* nodeOut);

Creates a node, a root until it is inserted into a parent.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL argument or a bad cookie; mui_errorCapacity when the context's node limit is reached; mui_errorBusy while the context is busy.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiDestroyNode(muiContext* context, muiNodeId nodeId);

Destroys a node and its whole subtree, detaching it from its parent first. The ids of every destroyed node become stale. A player's focus inside goes back to what the player focused when the outermost layer around it in the subtree became one, if that can still take it.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL context or the null id; mui_errorStale for an id whose node is gone; mui_errorBusy while the context is busy.

Thread safety. Safe from any thread; the context is used by one thread at a time.

bool muiNode_IsValid(const muiContext* context, muiNodeId nodeId);

Returns whether an id names a live node. A stale id is not misuse.

Parameters:

Returns: True for a live node; false otherwise and for a NULL context.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiNode_InsertChild(muiContext* context, muiNodeId parentId, muiNodeId childId, muiNodeId beforeId);

Inserts a root into a parent, before one of the parent's children or last.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL context, a null parent or child, a child that has a parent, a child that is the parent or one of its ancestors, or a before id that is not the parent's child; mui_errorStale for an id whose node is gone; mui_errorBusy while the context is busy.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiNode_Detach(muiContext* context, muiNodeId nodeId);

Detaches a node from its parent, making it a root with its subtree. A root stays as it is.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL context or the null id; mui_errorStale for an id whose node is gone; mui_errorBusy while the context is busy.

Thread safety. Safe from any thread; the context is used by one thread at a time.

muiNodeId muiNode_GetParent(const muiContext* context, muiNodeId nodeId);

Returns a node's parent.

Parameters:

Returns: The parent; the null id for a root, a stale id or a NULL context.

Thread safety. Safe from any thread; the context is used by one thread at a time.

muiNodeId muiNode_GetFirstChild(const muiContext* context, muiNodeId nodeId);

Returns a node's first child.

Parameters:

Returns: The first child; the null id for none, a stale id or a NULL context.

Thread safety. Safe from any thread; the context is used by one thread at a time.

muiNodeId muiNode_GetLastChild(const muiContext* context, muiNodeId nodeId);

Returns a node's last child.

Parameters:

Returns: The last child; the null id for none, a stale id or a NULL context.

Thread safety. Safe from any thread; the context is used by one thread at a time.

muiNodeId muiNode_GetNextSibling(const muiContext* context, muiNodeId nodeId);

Returns the child after a node in its parent's order.

Parameters:

Returns: The next sibling; the null id for the last child, a root, a stale id or a NULL context.

Thread safety. Safe from any thread; the context is used by one thread at a time.

muiNodeId muiNode_GetPreviousSibling(const muiContext* context, muiNodeId nodeId);

Returns the child before a node in its parent's order.

Parameters:

Returns: The previous sibling; the null id for the first child, a root, a stale id or a NULL context.

Thread safety. Safe from any thread; the context is used by one thread at a time.

uint32_t muiNode_GetChildCount(const muiContext* context, muiNodeId nodeId);

Returns how many children a node has.

Parameters:

Returns: The count; 0 for a stale id or a NULL context.

Thread safety. Safe from any thread; the context is used by one thread at a time.

uint64_t muiNode_GetHostKey(const muiContext* context, muiNodeId nodeId);

Returns the host key a node was created with.

Parameters:

Returns: The key; 0 for a stale id or a NULL context.

Thread safety. Safe from any thread; the context is used by one thread at a time.

pointer.h

Pointer input: the host's pointer events become hover and press states for styling, pointer capture, and records of presses, releases, clicks and cancels the host takes after each call.

MUI_NODISCARD MUI_API muiResult muiNode_RoutePointer(muiContext* context, muiNodeId rootId, const muiPointerEvent* event);

Takes a pointer event. Hit testing finds the node at the point, as muiNode_HitTest does, unless the pointer is captured; then the pointer's hover is updated, and so is its press and capture, and records are posted for muiContext_TakePointerRecord.

A node is in mui_stateHovered while a pointer's topmost node is it or one of its descendants, as CSS's :hover, and in mui_statePressed while a pointer that pressed it or a descendant holds a button, wherever the pointer went since, as :active; both join the states the host sets, and the node is styled again at the next muiNode_ComputeLayout. A touch hovers only in contact. Hover reads the last layout: after one, a move to the same point updates it.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL argument, the null id or an event outside the above, which changes nothing; mui_errorBusy while the context is busy or its event function runs; mui_errorStale for a root that is gone; mui_errorCapacity for a new pointer past the context's pointers limit.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiContext_TakePointerRecord(muiContext* context, muiPointerRecord* recordOut);

Takes the oldest pointer record.

Parameters:

Returns: mui_success; mui_empty when none is waiting; mui_errorInvalid for a NULL argument; mui_errorBusy while the context is busy.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiNode_CapturePointer(muiContext* context, muiNodeId nodeId, uint32_t pointer);

Sends every later event of a pointer that holds a button to a node, wherever it is, until its last button is released, it is cancelled, the capture is released or the node is destroyed. It hovers the node's chain from the next event on. A node that had the capture gets a capture-lost record.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL context, the null id, a pointer the context does not know or that holds no button; mui_errorBusy while the context is busy; mui_errorStale for a node that is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiContext_ReleasePointerCapture(muiContext* context, uint32_t pointer);

Releases a pointer's capture, with a capture-lost record; its next event hit tests again.

Parameters:

Returns: mui_success, also when it was not captured; mui_errorInvalid for a NULL context or a pointer the context does not know; mui_errorBusy while the context is busy.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiContext_GetPointerState(const muiContext* context, uint32_t pointer, muiPointerState* stateOut);

Reads a pointer's state.

Parameters:

Returns: mui_success; mui_empty for a pointer the context does not know (it left, lifted or was cancelled); mui_errorInvalid for a NULL argument.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiContext_SetClickRule(muiContext* context, uint64_t intervalNs, float distance);

Sets when presses count as one series (a double click): a press of the same button within intervalNs of the last and within distance of it on each axis. The defaults are 500 ms and 2, Windows's; hosts pass the platform's setting.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL context or a distance outside the above; mui_errorBusy while the context is busy.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiContext_OfferDrop(muiContext* context, uint32_t pointer, muiDropKinds kind, uint64_t key);

Offers a thing to drop for a dragging pointer, from its drag start on: a kind, one or more of the application's bits, and the host's key for it. From then the drag looks for a target under the pointer, the nearest node from the one hit up whose accepts mask (maul-ui/interaction.h) shares a bit with the kind, and posts drop enter and leave records as it changes, and a drop record when the drag ends over one; a cancelled drag only leaves. A second offer replaces the first.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL context, a pointer not dragging or a kind of 0; mui_errorBusy while the context is busy.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiContext_SetDragThreshold(muiContext* context, float mouse, float touch);

Sets how far a press moves before it becomes a drag, on either axis: for a mouse, and for touch and pens. The defaults are 4, Windows's, and 8, Android's touch slop; hosts pass the platform's.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL context or a distance outside the above; mui_errorBusy while the context is busy.

Thread safety. Safe from any thread; the context is used by one thread at a time.

popup.h

Popups: a node placed beside an anchor node after each layout. Its layer kind (maul-ui/interaction.h) says how it paints, usually mui_layerOverlay; this says where. From the anchor's border box on the surface, through scrolling, the popup's border box goes to the side asked, aligned along it, then on each axis flips to the opposite side when it overflows the root's box and the other side has more room, and is clamped into the root's box, its start edge kept when it cannot fit. Layout gives its size; an absolutely placed popup takes no room where it sits in the tree. A popup record stands for an open popup: the host sets it when it opens one and clears it, or destroys the node, when it closes. Light dismissal, as HTML's popovers have it, reports when one should close (mui_notificationPopupDismissed, the reason in its count); the host closes it, with whatever exit it likes. A popup anchored inside another nests under it. A pointer press dismisses every popup that neither holds the pressed node nor has its anchor holding it, nested ones first, and keeps the popups those nest under; an Escape no handler takes dismisses the popup set last; focus moved by code or navigation to a node outside a popup and its anchor dismisses it. Each is reported once, until the popup is set anew.

muiPopup muiDefaultPopup(void);

The default popup: below the null anchor, start edges aligned, no gap or margin, dismissed lightly.

Returns: The popup.

Thread safety. Safe from any thread.

MUI_NODISCARD MUI_API muiResult muiNode_SetPopup(muiContext* context, muiNodeId nodeId, const muiPopup* popup);

Makes a node a popup, or sets its popup anew; placed at the next layout, and dismissible again.

Parameters:

Returns: mui_success; mui_errorCapacity when the context holds its limit of popups; mui_errorInvalid for a NULL argument, the null id or a popup outside the above; mui_errorBusy while the context is busy; mui_errorStale for a node or anchor that is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiNode_GetPopup(const muiContext* context, muiNodeId nodeId, muiPopup* popupOut);

Reads a node's popup.

Parameters:

Returns: mui_success; mui_empty for a node that is not a popup; mui_errorInvalid for a NULL argument or the null id; mui_errorStale for a node that is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiNode_GetPopupSide(const muiContext* context, muiNodeId nodeId, muiPopupSide* sideOut);

Reads the side a popup went to at the last layout that placed it, after flipping, so an arrow can point at the anchor.

Parameters:

Returns: mui_success; mui_empty for a node that is not a popup or has not been placed since it was set; mui_errorInvalid for a NULL argument or the null id; mui_errorStale for a node that is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiNode_ClearPopup(muiContext* context, muiNodeId nodeId);

Makes a node no longer a popup; it keeps its last place until layout places it again.

Parameters:

Returns: mui_success, whether or not it was one; mui_errorInvalid for a NULL context or the null id; mui_errorBusy while the context is busy; mui_errorStale for a node that is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

range.h

Range values: a value between a minimum and a maximum on a node, as a slider, a scrollbar or a volume control holds one. Unhandled input changes it by default: keys by ARIA's slider pattern along the range's axis (muiNode_RouteKey, muiNode_RouteNavigation), and pointer records a host dispatches (muiContext_DispatchPointerRecord): a press on the track pages toward the point, and a drag of the range (its node takes drags, maul-ui/interaction.h) moves the value with the pointer, keeping where the thumb was grabbed. A change made so is reported by mui_notificationRangeChanged; a change by code is not.

muiValueRange muiDefaultValueRange(void);

The default range: 0 to 100 by steps of 1, a page of 10, horizontal, at 0, without a thumb.

Returns: The range.

Thread safety. Safe from any thread.

MUI_NODISCARD MUI_API muiResult muiNode_SetValueRange(muiContext* context, muiNodeId nodeId, const muiValueRange* range);

Makes a node a range, or sets its range anew; the value is kept within the minimum and maximum and on a step.

Parameters:

Returns: mui_success; mui_errorCapacity when the context holds its limit of ranges; mui_errorInvalid for a NULL argument, the null id or a range outside the above; mui_errorBusy while the context is busy; mui_errorStale for a node or thumb that is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiNode_GetValueRange(const muiContext* context, muiNodeId nodeId, muiValueRange* rangeOut);

Reads a node's range.

Parameters:

Returns: mui_success; mui_empty for a node that is not a range; mui_errorInvalid for a NULL argument or the null id; mui_errorStale for a node that is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiNode_SetRangeValue(muiContext* context, muiNodeId nodeId, float value);

Sets a range's value, kept within its minimum and maximum and on a step.

Parameters:

Returns: mui_success; mui_empty for a node that is not a range; mui_errorInvalid for a NULL context, the null id or a value not finite; mui_errorBusy while the context is busy; mui_errorStale for a node that is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiNode_ClearValueRange(muiContext* context, muiNodeId nodeId);

Makes a node no longer a range.

Parameters:

Returns: mui_success, whether or not it was one; mui_errorInvalid for a NULL context or the null id; mui_errorBusy while the context is busy; mui_errorStale for a node that is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

scroll.h

Scrolling: a scroll container's offset (layout.h's scrollAxes) and the extent its children reach. Offsets are logical: x runs from the inline start, so under right to left it grows leftward. Painting moves the children by the offset through a transform, and hit testing and navigation follow them.

MUI_NODISCARD MUI_API muiResult muiNode_SetScroll(muiContext* context, muiNodeId nodeId, float x, float y);

Scrolls a node to an offset at once, stopping any step easing it: within 0 and its extent less its padding box along each axis it scrolls (0 along any other), as its last muiNode_ComputeLayout measured them; layout keeps it within them as sizes change. The next draw list moves the children.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL context, the null id or an offset not finite; mui_errorBusy while the context is busy; mui_errorStale for a node that is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiNode_GetScroll(const muiContext* context, muiNodeId nodeId, float* xOut, float* yOut);

Reads a node's scroll offset; 0 along an axis it does not scroll, as a node that stops scrolling along one drops its offset there.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL argument or the null id; mui_errorStale for a node that is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiNode_GetScrollExtent(const muiContext* context, muiNodeId nodeId, muiSize* extentOut);

Reads the extent a scroll container's children reach, as its last muiNode_ComputeLayout measured it: from its padding box's start to the furthest end of its in-flow children's margin boxes plus its end padding, or of any border box below it with an area that no nested scroll container clips, at least its padding box, as CSS's scrollable overflow; for a scrollbar, the padding box over the extent is the thumb's share.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL argument or the null id; mui_errorStale for a node that is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiNode_ScrollIntoView(muiContext* context, muiNodeId nodeId);

Scrolls each scrolling ancestor of a node at once, the nearest first, stopping steps easing them: the least that brings the node's border box into its padding box, as CSSOM View's scrollIntoView with "nearest" does per axis. A node already inside stays; one past the start edge and no larger than the box aligns its start, one past the end its end; a larger one past either edge aligns the other, and one past both stays. Directional and sequential navigation does this to the node it focuses.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL context or the null id; mui_errorBusy while the context is busy; mui_errorStale for a node that is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

muiScrollRule muiDefaultScrollRule(void);

The default scroll rule: 100 a detent, Chrome's on Windows; 40 a line and 0.875 of the scrollport a page, Chrome's; a latch of 500 ms; steps easing out over 150 ms; flings keeping 0.998 of their speed a millisecond, iOS's normal rate; no overscroll. Hosts pass the platform's steps where it has them.

Returns: The rule.

Thread safety. Safe from any thread.

MUI_NODISCARD MUI_API muiResult muiContext_SetScrollRule(muiContext* context, const muiScrollRule* rule);

Sets the context's scroll rule.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL argument or a rule outside the above; mui_errorBusy while the context is busy.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiNode_GetScrollThumb(const muiContext* context, muiNodeId nodeId, muiAxis axis, float track, float minimum, muiScrollThumb* thumbOut);

Places a scrollbar thumb for a node along an axis, as its last muiNode_ComputeLayout and its offset leave it: the track times the padding box over the extent, at least minimum (at most the track), and placed as the offset is between 0 and its limit. A node that cannot scroll that way fills the track.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL argument, the null id, an unknown axis or a length outside the above; mui_errorStale for a node that is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

style.h

Style: classes of typed property values, the node types and node states that pick them, and a node's direct writes. A node's values resolve in fixed layers, each later one winning: the defaults, every class's base values in order, the state variants (the states in the order of muiState, weakest first, and the classes in order within each), the conditions that hold (classes in order, then each class's conditions in order), and the node's direct writes. A node's classes are its type's, then its own.

muiCondition muiDefaultCondition(void);

Returns the condition that always holds.

Returns: The condition.

Thread safety. Safe from any thread.

muiEnvironment muiDefaultEnvironment(void);

Returns the environment of a new context: a medium viewport, a pointer, a text scale of 1 and full motion.

Returns: The environment.

Thread safety. Safe from any thread.

MUI_NODISCARD MUI_API muiResult muiContext_SetEnvironment(muiContext* context, const muiEnvironment* environment);

Sets the environment conditions read. Every node is styled again at the next muiNode_ComputeLayout when it changes.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL argument or a value outside the above; mui_errorBusy while the context is busy.

Thread safety. Safe from any thread; the context is used by one thread at a time.

muiEnvironment muiContext_GetEnvironment(const muiContext* context);

Returns the environment conditions read.

Parameters:

Returns: The environment; muiDefaultEnvironment's for a NULL context.

Thread safety. Safe from any thread; the context is used by one thread at a time.

muiStyleDef muiDefaultStyleDef(void);

Returns the default style class def.

Returns: The def, with a valid cookie.

Thread safety. Safe from any thread.

MUI_NODISCARD MUI_API muiResult muiCreateStyle(muiContext* context, const muiStyleDef* def, muiStyleId* styleOut);

Creates a style class with no values set.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL argument or a bad cookie; mui_errorBusy while the context is busy; mui_errorCapacity when the context's style limit is reached.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiDestroyStyle(muiContext* context, muiStyleId styleId);

Destroys a style class. Nodes and node types that list it skip it, and every node is styled again at the next muiNode_ComputeLayout.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL context or the null id; mui_errorBusy while the context is busy; mui_errorStale for an id whose class is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiStyle_SetLayoutValues(muiContext* context, muiStyleId styleId, muiVariant variant, const muiLayoutStyle* values, muiPropertyMask mask);

Sets layout properties in one variant of a class from the fields of values. Every node is styled again at the next muiNode_ComputeLayout.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL argument, the null id, an unknown variant or property bit, a value outside the above or a property the variant's condition reads (its axis's sizes and limits, the aspect ratio or the text direction), which changes nothing; mui_errorBusy while the context is busy; mui_errorStale for an id whose class is gone; mui_errorCapacity when the variant had no values and the context's limit of property sets is reached.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiStyle_ResetProperties(muiContext* context, muiStyleId styleId, muiVariant variant, muiPropertyGroup group, muiPropertyMask mask);

Unsets properties in one variant of a class: their values and the tokens named for them. Every node is styled again at the next muiNode_ComputeLayout.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL context, the null id, an unknown variant, group or property bit; mui_errorBusy while the context is busy; mui_errorStale for an id whose class is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiStyle_GetLayoutValues(const muiContext* context, muiStyleId styleId, muiVariant variant, muiLayoutStyle* valuesOut, muiPropertyMask* maskOut);

Reads the values one variant of a class sets.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL argument, the null id or an unknown variant; mui_errorStale for an id whose class is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiStyle_AddCondition(muiContext* context, muiStyleId styleId, const muiCondition* condition, muiVariant* variantOut);

Adds a condition to a class, after its others. Its values are then set through the variant it gives. Every node is styled again at the next muiNode_ComputeLayout.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL argument, the null id or a condition outside the above; mui_errorBusy while the context is busy; mui_errorStale for an id whose class is gone; mui_errorLimit when the class has MUI_MAX_CONDITIONS.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiStyle_SetCondition(muiContext* context, muiStyleId styleId, muiVariant variant, const muiCondition* condition);

Replaces one of a class's conditions, keeping its values. Every node is styled again at the next muiNode_ComputeLayout.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL argument, the null id, a variant that is not one of the class's conditions or a condition outside the above; mui_errorBusy while the context is busy; mui_errorStale for an id whose class is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiStyle_GetCondition(const muiContext* context, muiStyleId styleId, muiVariant variant, muiCondition* conditionOut);

Reads one of a class's conditions.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL argument, the null id or a variant that is not one of the class's conditions; mui_errorStale for an id whose class is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiStyle_ClearConditions(muiContext* context, muiStyleId styleId);

Removes every condition of a class and its values. Every node is styled again at the next muiNode_ComputeLayout.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL context or the null id; mui_errorBusy while the context is busy; mui_errorStale for an id whose class is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

muiNodeTypeDef muiDefaultNodeTypeDef(void);

Returns the default node type def: no classes.

Returns: The def, with a valid cookie.

Thread safety. Safe from any thread.

MUI_NODISCARD MUI_API muiResult muiCreateNodeType(muiContext* context, const muiNodeTypeDef* def, muiNodeTypeId* typeOut);

Creates a node type with an ordered list of classes.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL argument, a bad cookie or classes NULL with a count; mui_errorLimit for more than MUI_MAX_CLASSES classes; mui_errorBusy while the context is busy; mui_errorCapacity when the context's node type limit is reached.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiDestroyNodeType(muiContext* context, muiNodeTypeId typeId);

Destroys a node type. Its nodes are left with no type, and every node is styled again at the next muiNode_ComputeLayout.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL context or the null id; mui_errorBusy while the context is busy; mui_errorStale for an id whose type is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiNodeType_SetClasses(muiContext* context, muiNodeTypeId typeId, const muiStyleId* classes, uint32_t count);

Replaces a node type's classes. Every node is styled again at the next muiNode_ComputeLayout.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL context, the null id or NULL classes with a count; mui_errorLimit for a count over MUI_MAX_CLASSES; mui_errorBusy while the context is busy; mui_errorStale for an id whose type is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiNode_SetType(muiContext* context, muiNodeId nodeId, muiNodeTypeId typeId);

Sets a node's type. The node is styled again at the next muiNode_ComputeLayout.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL context or the null node id; mui_errorBusy while the context is busy; mui_errorStale for a node or a type that is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiNode_SetClasses(muiContext* context, muiNodeId nodeId, const muiStyleId* classes, uint32_t count);

Replaces a node's own classes, which follow its type's. The node is styled again at the next muiNode_ComputeLayout.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL context, the null id or NULL classes with a count; mui_errorLimit for a count over MUI_MAX_CLASSES; mui_errorBusy while the context is busy; mui_errorStale for a node that is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiNode_SetStates(muiContext* context, muiNodeId nodeId, muiState states);

Sets the states a node is in. The node is styled again at the next muiNode_ComputeLayout when they change. Pointer input's hover and press, and the players' focus, join them, apart: setting states leaves those. The exiting bit is the exits' (maul-ui/exit.h): setting states keeps it as it is.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL context, the null id or a bit that names no state; mui_errorBusy while the context is busy; mui_errorStale for a node that is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

muiState muiNode_GetStates(const muiContext* context, muiNodeId nodeId);

Returns the states a node is in: those the host set, hover and press from pointer input (muiNode_RoutePointer), and focus and its showing from the players' focus (muiContext_SetFocus).

Parameters:

Returns: Its muiState bits; 0 for a stale id or a NULL context.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiNode_SetLayoutValues(muiContext* context, muiNodeId nodeId, const muiLayoutStyle* values, muiPropertyMask mask);

Writes layout properties of a node directly from the fields of values: they win over every class until reset, at once. The node and its parent are laid out again at the next muiNode_ComputeLayout. MUI_LAYOUT_PROPERTIES as the mask writes every layout property.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL argument, the null id, an unknown property bit or a value outside the above, which changes nothing; mui_errorBusy while the context is busy; mui_errorStale for a node that is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiNode_ResetProperties(muiContext* context, muiNodeId nodeId, muiPropertyGroup group, muiPropertyMask mask);

Ends direct writes of a node's properties: they take their classes' values again at the next muiNode_ComputeLayout.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL context, the null id or an unknown group or property bit; mui_errorBusy while the context is busy; mui_errorStale for a node that is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

muiPropertyMask muiNode_GetDirectProperties(const muiContext* context, muiNodeId nodeId, muiPropertyGroup group);

Returns which properties of a group a node writes directly.

Parameters:

Returns: The properties; 0 for a stale id, a NULL context or an unknown group.

Thread safety. Safe from any thread; the context is used by one thread at a time.

text.h

The text service: fonts, shaping and paragraphs, in the library when it is built with its text component (MAUL_UI_TEXT). The core reaches text only through host content, so a host may use another text stack instead. A service is busy while one of its functions that use it runs, those given a muiTextHost among them, and an atlas while one of its functions that change it runs. Host code they call then (the allocator, FreeType's memory through it, the clipboard writer) calls none of those: one answers mui_errorBusy, or an empty answer where it returns no status, and counts one misuse. A call given a muiTextHost also keeps the host's context busy (maul-ui/context.h): host code it calls may read the context, and a change to it is refused with mui_errorBusy and one misuse counted on the context.

static inline muiTextServiceDef muiDefaultTextServiceDef(void);

Returns the default service def: 64 fonts, 1,024 text blocks, 16 font families and the C library's allocator.

Built in the program from the headers it includes, so it carries their version (MUI_ABI_VERSION), which the service checks.

Returns: The def, with a valid cookie.

Thread safety. Safe from any thread.

MUI_NODISCARD MUI_API muiResult muiCreateTextService(const muiTextServiceDef* def, muiTextService** serviceOut);

Creates a text service.

Parameters:

Returns: mui_success; mui_errorVersion for a def built against headers of another binary interface (MUI_ABI_VERSION), before the rest of the def is read; mui_errorInvalid for a NULL argument, a bad cookie, a half-set allocator or a font limit of 0; mui_errorLimit for a limit past its maximum; mui_errorCapacity when memory runs out.

Thread safety. Safe from any thread.

void muiDestroyTextService(muiTextService* service);

Destroys a service and every font in it. Every id it gave out becomes meaningless. A call while the service is busy destroys nothing and counts one misuse.

Parameters:

Thread safety. Safe from any thread; the service is used by one thread at a time.

uint64_t muiTextService_GetMisuse(const muiTextService* service);

Returns how many calls the service has refused as invalid input (mui_errorInvalid) or as calls back in while busy (mui_errorBusy), its glyph atlases' and text editing's among them: a count release builds can watch to catch a host's bugs. Stale ids are not misuse, and queries taking the service as const count nothing.

Parameters:

Returns: The count; 0 for a NULL service.

Thread safety. Safe from any thread; the service is used by one thread at a time.

text_block.h

Text blocks: UTF-8 text the text service lays out as a node's host content. A node whose host key is a block's key, and whose content is the host's, is measured by muiMeasureText and painted by muiPaintText in its computed text style: lines broken where Unicode allows (UAX #14), runs ordered by the Unicode bidirectional algorithm (UAX #9), glyphs shaped by HarfBuzz. White space is kept as written, line breaks in the text end lines, and spaces ending a wrapped line hang past it.

muiTextBlockDef muiDefaultTextBlockDef(void);

Returns the default text block def: no text.

Returns: The def, with a valid cookie.

Thread safety. Safe from any thread.

MUI_NODISCARD MUI_API muiResult muiCreateTextBlock(muiTextService* service, const muiTextBlockDef* def, muiTextBlockId* blockOut);

Creates a text block holding a copy of a def's text.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL argument, a bad cookie or text NULL with a length; mui_errorLimit for a length past MUI_MAX_TEXT_BYTES; mui_errorCapacity when the service's limit of blocks is reached or memory runs out; mui_errorBusy while the service is busy.

Thread safety. Safe from any thread; the service is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiDestroyTextBlock(muiTextService* service, muiTextBlockId blockId);

Destroys a text block.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL service or the null id; mui_errorStale for a block that is gone; mui_errorBusy while the service is busy.

Thread safety. Safe from any thread; the service is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiTextBlock_SetText(muiTextService* service, muiTextBlockId blockId, const char* text, size_t length);

Replaces a block's text with a copy of other UTF-8 text. Nodes that show it are measured again once the host calls muiNode_MarkContentChanged for them.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL service, the null id or a NULL text with a length; mui_errorLimit for a length past MUI_MAX_TEXT_BYTES; mui_errorStale for a block that is gone; mui_errorCapacity when memory runs out, which keeps the old text; mui_errorBusy while the service is busy.

Thread safety. Safe from any thread; the service is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiTextBlock_Replace(muiTextService* service, muiTextBlockId blockId, size_t start, size_t end, const char* text, size_t length);

Replaces the bytes of a block's text from start up to end with a text, as editing does; its nodes are measured and painted anew once marked changed. Offsets inside a UTF-8 sequence leave bytes that read as U+FFFD; muiTextBlock_FindDeletion and muiNode_MoveTextPosition give offsets on grapheme cluster boundaries.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL service, the null id, a NULL text with a length, start after end, or end past the text; mui_errorLimit for a result past MUI_MAX_TEXT_BYTES; mui_errorStale for a block that is gone; mui_errorCapacity when memory runs out, which keeps the old text; mui_errorBusy while the service is busy.

Thread safety. Safe from any thread; the service is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiTextBlock_SetSpans(muiTextService* service, muiTextBlockId blockId, const muiTextSpan* spans, uint32_t count);

Sets the spans of a block's text, copied, replacing the ones it had; later ones win where they overlap, as a stack of styles does. Spans set the text color, the decoration and its color, and the font, size, weight and slant their runs are shaped in, the node's synthesis kept: a size is against the node's, as a child's text is against its parent's, and a line is as tall as the runs on it reach. A block takes up to 31 run styles apart from the node's; a span making more is shaped in the style under it. Setting the text drops them; replacing a range moves those after it, a span growing with text put strictly inside it; a span start inside the range goes to the new text's end, a span end inside it to the range's start, and a span left empty is dropped. Mark the nodes showing the block changed (muiNode_MarkContentChanged).

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL service, the null id, NULL spans with a count, a span empty, past the text or with an edge inside a UTF-8 sequence, a mask naming another property, or a value not valid for its property; mui_errorLimit for more than MUI_MAX_TEXT_SPANS; mui_errorStale for a block that is gone; mui_errorCapacity when memory runs out, which keeps the old spans; mui_errorBusy while the service is busy.

Thread safety. Safe from any thread; the service is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiTextBlock_GetSpans(const muiTextService* service, muiTextBlockId blockId, const muiTextSpan** spansOut, uint32_t* countOut);

Reads a block's spans, as moved by the edits since they were set: what a host saves of a block's rich text.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL argument or the null id; mui_errorStale for a block that is gone.

Thread safety. Safe from any thread; the service is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiTextBlock_GetText(const muiTextService* service, muiTextBlockId blockId, const char** textOut, size_t* lengthOut);

Reads a block's text.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL argument or the null id; mui_errorStale for a block that is gone.

Thread safety. Safe from any thread; the service is used by one thread at a time.

uint64_t muiTextBlock_GetKey(muiTextBlockId blockId);

Returns a block's key, for a node's host key: never 0.

Parameters:

Returns: The key.

Thread safety. Safe from any thread.

uint64_t muiFont_GetKey(muiFontId fontId);

Returns a font's key, for a text style's font: never 0, which names the service's default font. Text laid out in it draws glyph runs whose keys name an instance of the font as well: the axes and the bold or oblique the style's weight, slant and size make of it, which glyph images and atlases rebuild from the key. A null id's key is 0.

Parameters:

Returns: The key.

Thread safety. Safe from any thread.

uint64_t muiFontFamily_GetKey(muiFontFamilyId familyId);

Returns a font family's key, for a text style's font: never 0, and apart from every font's key.

Parameters:

Returns: The key; 0 for the null id.

Thread safety. Safe from any thread.

MUI_NODISCARD MUI_API muiResult muiTextService_SetDefaultFont(muiTextService* service, muiFontId fontId);

Sets the font a text style's font key 0 names; the null id sets none, and text in font 0 then draws nothing.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL service; mui_errorStale for a font that is gone; mui_errorBusy while the service is busy.

Thread safety. Safe from any thread; the service is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiTextService_SetFallbackFonts(muiTextService* service, const uint64_t* keys, uint32_t count);

Sets the fonts tried, in order, for characters a style's font or family, and its family's fallbacks, lack: each grapheme cluster is drawn in the first that has all its characters, characters of no one script staying in the font before them when it has them. Lines keep the metrics of the style's own font.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL service, NULL keys with a count or a key that is no font's or family's; mui_errorLimit for more than MUI_MAX_FALLBACKS; mui_errorStale for one that is gone. On failure the fallbacks stay as they were; mui_errorBusy while the service is busy.

Thread safety. Safe from any thread; the service is used by one thread at a time.

uint64_t muiTextService_GetLayoutFailureCount(const muiTextService* service);

Counts the times a block could not be laid out for want of memory, or because a password's bullets would pass MUI_MAX_TEXT_BYTES. Its measure then answers NaN and its painting calls muiDrawSink_Fail, so that layout and the next build ask again.

Parameters:

Returns: The count.

Thread safety. Safe from any thread; the service is used by one thread at a time.

muiSize muiMeasureText(void* user, muiNodeId nodeId, uint64_t hostKey, muiMeasureAxis width, muiMeasureAxis height);

Measures a text block's lines, as a muiMeasureFunction: user is a muiTextHost, and hostKey a block's key. The width breaks lines: exact and at-most sizes wrap them to it, max-content keeps only the text's own line breaks, min-content breaks at every opportunity. The height is the lines' heights. A key that names no block, a font key that names no font, or a node whose text does not wrap measure as their lines allow; none of them is an error.

Parameters:

Returns: The content box size; NaN by NaN when memory runs out, or when a password's bullets would pass MUI_MAX_TEXT_BYTES, which layout measures again (muiMeasureFunction); 0 by 0, with one misuse counted, while the service is busy.

Thread safety. Safe from any thread; the service and context are used by one thread at a time.

void muiPaintText(void* user, muiNodeId nodeId, uint64_t hostKey, float width, float height, muiDrawSink* sink);

Paints a text block's lines into a draw list, as a muiPaintFunction: user is a muiTextHost, and hostKey a block's key. Lines break to the content box's width, are ordered for display and aligned by the text style, and are drawn as glyph runs.

Parameters:

Thread safety. Safe from any thread; the service and context are used by one thread at a time.

bool muiReadAccessText(void* user, muiNodeId nodeId, uint64_t hostKey, const muiRect* shown, muiAccessContent* contentOut);

Reads a text block's text for accessibility, as a maul-ui/access.h's muiAccessTextFunction: user is a muiTextHost, and hostKey a block's key. The block's text, which the record leaves out when it is not well-formed UTF-8; for an editing password (maul-ui/text_editor.h), a bullet per character, as it is shown. An editing block gives its selection; given shown, its lines as painting breaks them at the node's content box's width, with their grapheme clusters for the lines within a shown height of shown (at most 16,384 clusters, the nearest lines first), and its words, a password none.

Parameters:

Returns: Whether the key names a block; false, too, when memory for a password's bullets runs out, for a NULL contentOut or while the service is busy, which counts one misuse. Lines and words are given whole or not at all: when any line, or its clusters, cannot be read for want of memory or a font, no lines are given, and when any word cannot, no words; the text is given still.

Thread safety. Safe from any thread; the service and context are used by one thread at a time.

float muiMeasureTextBaseline(void* user, muiNodeId nodeId, uint64_t hostKey, float width, float height);

muiBaselineFunction: user is a muiTextHost, and hostKey a block's key. Lines are a line height apart from the content box's top, so the first baseline does not depend on the width.

Parameters:

Returns: The baseline's distance down from the content box's top; NaN for empty text, which has no lines, where muiMeasureText measures nothing, and while the service is busy, which counts one misuse; +infinity when memory runs out, which layout asks again (muiBaselineFunction).

Thread safety. Safe from any thread; the service and context are used by one thread at a time.

text_edit.h

Editing primitives over laid-out text: positions in a node's text, from points, to carets and moved by cluster, word or line, the rectangles a range of it covers, the text laid out as muiPaintText paints it, what a deletion removes, and an input method's composition held in a block. maul-ui/text_editor.h builds selection and undo on them.

MUI_NODISCARD MUI_API muiResult muiNode_HitTestText(const muiTextHost* host, muiNodeId nodeId, float width, float x, float y, muiTextPosition* positionOut);

Finds the position nearest a point of a node's text: the line at the point's y (the first above the text, the last below it), then the edge of the grapheme cluster nearer the point's x (the right one at the middle), a cluster several clusters share a glyph with taking an equal share of it; past a line's ends, that end, before any white space hanging past it. The position keeps to the cluster the point is on. Negative letter spacing can draw a cluster over the one before it; the point then finds the first, left to right.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL argument, a width not finite or negative, or a point not finite; mui_errorStale for a node, block or font that is gone; mui_errorCapacity when memory runs out; mui_errorBusy while the service is busy.

Thread safety. Safe from any thread; the host's context and service are used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiNode_GetTextCaret(const muiTextHost* host, muiNodeId nodeId, float width, muiTextPosition position, muiTextCaret* caretOut);

Finds where the caret of a position is drawn: at the leading edge of the cluster after it for downstream, the trailing edge of the cluster before it for upstream, on the line the affinity picks where a line wraps; an offset in white space hanging past a line's end sits at that end, and an offset inside a cluster at its start.

Parameters:

Returns: As muiNode_HitTestText, mui_errorInvalid also for an affinity out of range; mui_errorBusy while the service is busy.

Thread safety. Safe from any thread; the host's context and service are used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiNode_GetTextRangeRects(const muiTextHost* host, muiNodeId nodeId, float width, size_t start, size_t end, muiRect* rectsOut, uint32_t capacity, uint32_t* countOut);

Finds the rectangles a range of a node's text covers: on each line, one for each stretch of side by side clusters in the range, left to right, lines from the top; clusters on both sides of the range's ends are not covered.

Parameters:

Returns: mui_success; mui_errorCapacity when rectsOut holds fewer, writing those that fit, or memory runs out; otherwise as muiNode_HitTestText; mui_errorBusy while the service is busy.

Thread safety. Safe from any thread; the host's context and service are used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiNode_MoveTextPosition( const muiTextHost* host, muiNodeId nodeId, float width, muiTextPosition from, muiTextMovement movement, float preferredX, muiTextPosition* positionOut);

Moves a position through a node's text, laid out as muiPaintText paints it. Positions moved to are on grapheme cluster boundaries; one that cannot move (the text's start moving back) stays.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL argument, a width not finite or negative, a movement or an affinity out of range; mui_errorStale for a node, block or font that is gone; mui_errorCapacity when memory runs out; mui_errorBusy while the service is busy.

Thread safety. Safe from any thread; the host's context and service are used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiTextBlock_FindDeletion(const muiTextService* service, muiTextBlockId blockId, size_t offset, muiTextDeletion deletion, size_t* startOut, size_t* endOut);

Finds the bytes a deletion from an offset of a block's text removes, for muiTextBlock_Replace; words are deleted by moving with muiNode_MoveTextPosition and replacing what lies between. Nothing at the text's start going back or its end going forward.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL argument, the null id or a deletion out of range; mui_errorStale for a block that is gone.

Thread safety. Safe from any thread; the service is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiTextBlock_SetComposition( muiTextService* service, muiTextBlockId blockId, size_t offset, const char* text, size_t length, const muiCompositionSegment* segments, uint32_t segmentCount);

Sets a block's input method composition, the text being composed before it is committed: the text replaces the composition there is, or goes in at offset when there is none, and painting underlines it by its segments (all of it thin when there are none). An empty text removes the composition and ends it. While it lasts, muiTextBlock_Replace before or after it moves it, and one that overlaps it, or muiTextBlock_SetText, ends it.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL service, the null id, a NULL text or segments with a count, a segment past the text or of an unknown style; mui_errorLimit for more than MUI_MAX_COMPOSITION_SEGMENTS segments, or a text past MUI_MAX_TEXT_BYTES alone or with the block's; mui_errorStale for a block that is gone; mui_errorCapacity when memory runs out, which keeps the old text and composition; mui_errorBusy while the service is busy.

Thread safety. Safe from any thread; the service is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiTextBlock_EndComposition(muiTextService* service, muiTextBlockId blockId);

Ends a block's composition, keeping its text as typed text: what an input method that commits the composition as it is asks. Nothing without one. For an editing block the kept text is a change made outside the editor, which empties its undo history; to commit text undo can take back, take the composition out with muiTextBlock_Compose and type what the method commits.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL service or the null id; mui_errorStale for a block that is gone; mui_errorBusy while the service is busy.

Thread safety. Safe from any thread; the service is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiTextBlock_GetComposition(const muiTextService* service, muiTextBlockId blockId, size_t* startOut, size_t* lengthOut);

Reads where a block's composition is.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL argument or the null id; mui_errorStale for a block that is gone.

Thread safety. Safe from any thread; the service is used by one thread at a time.

text_editor.h

Text editing: a block opted into editing keeps a selection, an undo history and its field's rules, and takes typing, pastes, deletions, undo and redo; moves, presses and drags place the selection through a node's laid-out text. muiNode_HandleEditEvent maps a platform's keys, typed text and the pointer onto these; the clipboard and focus stay the host's. An editing block's text scrolls in its node's content box to keep the caret in view, back as far as the text allows; muiPaintText draws it scrolled (a node that clips keeps it inside), and the editing primitives (maul-ui/text_edit.h) take and give points as drawn.

muiTextEditRules muiDefaultTextEditRules(void);

Returns a single-line field's rules: no filter, plain text, no limit, and 100 edits to undo.

Returns: The rules.

Thread safety. Safe from any thread.

MUI_NODISCARD MUI_API muiResult muiTextBlock_SetEditing(muiTextService* service, muiTextBlockId blockId, const muiTextEditRules* rules);

Opts a block into editing with a field's rules, or sets an editing block's rules anew. Either way the history empties and the caret goes to the text's end. Changing the text otherwise (muiTextBlock_SetText, muiTextBlock_Replace, a composition) empties the history too, the selection kept within the text.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL argument, the null id, or a flag, filter or purpose out of range; mui_errorStale for a block that is gone; mui_errorBusy while the service is busy.

Thread safety. Safe from any thread; the service is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiTextBlock_ClearEditing(muiTextService* service, muiTextBlockId blockId);

Opts a block out of editing: its selection and history go, and the memory its history held is freed.

Parameters:

Returns: mui_success, whether or not it was editing; mui_errorInvalid for a NULL service or the null id; mui_errorStale for a block that is gone; mui_errorBusy while the service is busy.

Thread safety. Safe from any thread; the service is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiTextBlock_GetSelection(const muiTextService* service, muiTextBlockId blockId, muiTextSelection* selectionOut);

Reads an editing block's selection.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL argument or the null id; mui_errorState for a block not editing; mui_errorStale for a block that is gone.

Thread safety. Safe from any thread; the service is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiTextBlock_Select(muiTextService* service, muiTextBlockId blockId, muiTextSelection selection);

Sets an editing block's selection, which ends a run of typing undone together.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL service, the null id or an offset out of place; mui_errorState for a block not editing; mui_errorStale for a block that is gone; mui_errorBusy while the service is busy.

Thread safety. Safe from any thread; the service is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiTextBlock_Type(muiTextService* service, muiTextBlockId blockId, const char* text, size_t length, bool* changedOut);

Types text over an editing block's selection, under its rules, the caret after it. Typing undoes word by word: a run of it continuing where the last ended is one edit until a word starts after white space.

Parameters:

Returns: mui_success, changed or not (read-only, filtered out, at the limit); mui_errorInvalid for a NULL service or text, the null id; mui_errorState for a block not editing; mui_errorLimit for a text that would take the block past MUI_MAX_TEXT_BYTES; mui_errorStale for a block that is gone; mui_errorCapacity when memory runs out, which changes nothing; mui_errorBusy while the service is busy.

Thread safety. Safe from any thread; the service is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiTextBlock_Paste(muiTextService* service, muiTextBlockId blockId, const char* text, size_t length, bool* changedOut);

Pastes text over an editing block's selection, as muiTextBlock_Type but undone alone.

Parameters:

Returns: As muiTextBlock_Type; mui_errorBusy while the service is busy.

Thread safety. Safe from any thread; the service is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiTextBlock_Erase(muiTextService* service, muiTextBlockId blockId, muiTextDeletion deletion, bool* changedOut);

Deletes an editing block's selection, or with none, what the deletion removes beside the caret (muiTextBlock_FindDeletion). A run of deletions one way, each where the last left the caret, is undone together.

Parameters:

Returns: As muiTextBlock_Type; mui_errorInvalid for a deletion out of range; mui_errorBusy while the service is busy.

Thread safety. Safe from any thread; the service is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiTextBlock_EraseTo(muiTextService* service, muiTextBlockId blockId, size_t offset, bool* changedOut);

Deletes an editing block's selection, or with none, the text from the caret to an offset: a word or a line, found with muiNode_MoveTextPosition.

Parameters:

Returns: As muiTextBlock_Type; mui_errorInvalid for an offset inside a character; mui_errorBusy while the service is busy.

Thread safety. Safe from any thread; the service is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiTextBlock_GetSelectedText(const muiTextService* service, muiTextBlockId blockId, const char** textOut, size_t* lengthOut);

Reads the selected text of an editing block, for the host's clipboard: a cut is this, then muiTextBlock_Erase. A password's is empty.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL argument or the null id; mui_errorState for a block not editing; mui_errorStale for a block that is gone.

Thread safety. Safe from any thread; the service is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiTextBlock_Undo(muiTextService* service, muiTextBlockId blockId, bool* changedOut);

Undoes an editing block's last edit, the selection back as it was before it; nothing on a read-only block or during a composition.

Parameters:

Returns: As muiTextBlock_Type; mui_errorBusy while the service is busy.

Thread safety. Safe from any thread; the service is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiTextBlock_Redo(muiTextService* service, muiTextBlockId blockId, bool* changedOut);

Redoes an editing block's last undone edit, the selection as it was after it; as muiTextBlock_Undo otherwise. An edit made after an undo drops what was undone.

Parameters:

Returns: As muiTextBlock_Type; mui_errorBusy while the service is busy.

Thread safety. Safe from any thread; the service is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiTextBlock_GetInputPurpose(const muiTextService* service, muiTextBlockId blockId, muiInputPurpose* purposeOut);

Reads what an editing block's field takes, for an on-screen keyboard: a password's purpose for a password, a number's for a number filter, else the one its rules give.

Parameters:

Returns: As muiTextBlock_GetSelection.

Thread safety. Safe from any thread; the service is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiTextBlock_GetUndoState(const muiTextService* service, muiTextBlockId blockId, bool* undoOut, bool* redoOut);

Reads whether an editing block has an edit to undo and one to redo.

Parameters:

Returns: As muiTextBlock_GetSelection.

Thread safety. Safe from any thread; the service is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiTextBlock_Compose(muiTextService* service, muiTextBlockId blockId, const char* text, size_t length, size_t caret, const muiCompositionSegment* segments, uint32_t segmentCount, bool* changedOut);

Shows an input method's composition in an editing block at its caret, replacing the one shown; one starting over a selection deletes it first, as an edit undo takes back. Empty text takes the composition out, the caret where it began: what the method commits comes after as typing (muiTextBlock_Type), which also takes out a composition still shown. Undo waits until it ends.

Parameters:

Returns: As muiTextBlock_Type; mui_errorInvalid for a caret out of place or segments out of the text; mui_errorBusy while the service is busy.

Thread safety. Safe from any thread; the service is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiNode_HandleEditEvent(const muiTextHost* host, muiNodeId nodeId, const muiEvent* event, const muiTextEditInput* input, muiTextEditOutcome* outcomeOut);

Takes an event for a node's editing block, as its listener would: typed text is typed; keys move, select, delete, undo and copy by the keymap's shortcuts; a press of the first button places the selection by its click count, and a drag's records extend it (the node takes drags, maul-ui/interaction.h).

The shortcuts, with Shift extending each move: arrows by cluster and line, up and down on a single line to its ends; words with Control (PC) or Option (Mac); line ends with Home and End (PC) or Command and the arrows (Mac), the text's ends with Control and Home and End (PC) or Command and up and down (Mac); Backspace and Delete by cluster, a word with Control (PC) or Option (Mac), back to the line's start with Command (Mac); Enter's line break on many lines; select all, copy, cut, paste, undo and redo with Control or Command and A, C, X, V, Z and Shift and Z, also Y (PC), Control and Insert and Shift and Insert (PC). Letters are read from the key's meaning under the layout, the rest from the physical key.

Parameters:

Returns: As muiNode_MoveEditCaret; mui_errorInvalid also for a text event with NULL text and a length; mui_errorBusy while the service is busy.

Thread safety. Safe from any thread; the host's context and service are used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiNode_MoveEditCaret(const muiTextHost* host, muiNodeId nodeId, muiTextMovement movement, bool extend);

Moves the caret of a node's editing block through its laid-out text (muiNode_MoveTextPosition), extending the selection or collapsing it there; lines up and down keep the x the first of them started from.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL argument, a movement out of range; mui_errorState for a block not editing; mui_errorStale for a node, block or font that is gone; mui_errorCapacity when memory runs out; mui_errorBusy while the service is busy.

Thread safety. Safe from any thread; the host's context and service are used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiNode_HandleEditPress(const muiTextHost* host, muiNodeId nodeId, float x, float y, uint32_t clickCount, bool extend);

Places the caret of a node's editing block where a press is: one click at the point, two selecting the word there, three the paragraph; with extend, the selection grows to it from the anchor. Drags then extend by the same unit.

Parameters:

Returns: As muiNode_MoveEditCaret; mui_errorInvalid for a point not finite or a click count of 0; mui_errorBusy while the service is busy.

Thread safety. Safe from any thread; the host's context and service are used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiNode_HandleEditDrag(const muiTextHost* host, muiNodeId nodeId, float x, float y);

Extends the selection of a node's editing block to where a drag is, by the unit its press selected, keeping what the press selected.

Parameters:

Returns: As muiNode_HandleEditPress; mui_errorBusy while the service is busy.

Thread safety. Safe from any thread; the host's context and service are used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiPerformTextAccessAction(const muiTextHost* host, const muiAccessRequest* request, muiTextEditOutcome* outcomeOut);

Applies what assistive technology asks of a node's editing block: its selection set (mui_actionSetSelection) or a range of its text replaced (mui_actionReplaceText, maul-ui/access.h), in offsets of the text as accessibility reads it (a password's mask), at the starts of characters. Text replaced goes in as a paste does, under the block's rules, the caret after it; a read-only block keeps its text. The host tells the accessibility tree what changed, as after muiNode_HandleEditEvent.

Parameters:

Returns: mui_success; mui_empty for another action; mui_errorInvalid for a NULL argument or a NULL text with a length, counted as misuse; mui_errorFormat for a block not editing or an offset past the text or inside a character, counted as none, since the offsets are a client's and the text may have changed since its adapter's update; mui_errorStale for a node or block that is gone; mui_errorCapacity when memory runs out; mui_errorBusy while the service is busy.

Thread safety. Safe from any thread; the host's context and service are used by one thread at a time.

text_style.h

Text style: the values a text service reads to lay out and draw a node's text, set through the same classes, variants, conditions, tokens, themes, transitions and direct writes as every property. They are inherited as CSS inherits them: a property no layer gives a node takes its parent's value, and a root the defaults. The core draws no text; a change marks a node with host content to be measured or painted again.

muiTextStyle muiDefaultTextStyle(void);

Returns the default text style: opaque black, font 0, 16 logical units, the font's own line height, no letter spacing, weight 400, upright, at the start, wrapping, with no decoration, whose color is the text's, bold and oblique made where a font has none. A root takes these for what no layer gives it.

Returns: The style.

Thread safety. Safe from any thread.

MUI_NODISCARD MUI_API muiResult muiStyle_SetTextValues(muiContext* context, muiStyleId styleId, muiVariant variant, const muiTextStyle* values, muiPropertyMask mask);

Sets text values in one variant of a class, as muiStyle_SetLayoutValues sets layout ones.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL argument, the null id, an unknown variant or property bit or a value outside the above, which changes nothing; mui_errorBusy while the context is busy; mui_errorStale for an id whose class is gone; mui_errorCapacity when the variant had no values and the context's limit of property sets is reached.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiStyle_GetTextValues(const muiContext* context, muiStyleId styleId, muiVariant variant, muiTextStyle* valuesOut, muiPropertyMask* maskOut);

Reads the text values one variant of a class sets.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL argument, the null id or an unknown variant; mui_errorStale for an id whose class is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiNode_SetTextValues(muiContext* context, muiNodeId nodeId, const muiTextStyle* values, muiPropertyMask mask);

Writes text values to a node directly, over its classes, as muiNode_SetLayoutValues writes layout ones. Its children inherit them at the next muiNode_ComputeLayout.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL argument, the null id, an unknown property bit or a value outside the above, which changes nothing; mui_errorBusy while the context is busy; mui_errorStale for a node that is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiNode_GetTextStyle(const muiContext* context, muiNodeId nodeId, muiComputedTextStyle* styleOut);

Reads a node's computed text style, as of its last muiNode_ComputeLayout; a measure or paint function may read it.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL argument or the null id; mui_errorStale for a node that is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

theme.h

Themes: sets of token values that override the context's tokens for the subtree a theme is set on. A node reads a token from the nearest theme above it, itself included, that overrides it, then the next one out, then the context; an alias read in a subtree is read there too. Editing a theme restyles every node; setting one on a node restyles the nodes whose themes it changes.

muiThemeDef muiDefaultThemeDef(void);

Returns the default theme def.

Returns: The def, with a valid cookie.

Thread safety. Safe from any thread.

MUI_NODISCARD MUI_API muiResult muiCreateTheme(muiContext* context, const muiThemeDef* def, muiThemeId* themeOut);

Creates a theme that overrides no token.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL argument or a bad cookie; mui_errorBusy while the context is busy; mui_errorCapacity when the context's theme limit is reached.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiDestroyTheme(muiContext* context, muiThemeId themeId);

Destroys a theme and its overrides. Nodes it was set on read through no theme of their own, and every node is restyled.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL context or the null id; mui_errorBusy while the context is busy; mui_errorStale for an id whose theme is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiTheme_SetTokenValue(muiContext* context, muiThemeId themeId, muiTokenId tokenId, const muiTokenValue* value);

Overrides a token in a theme with a literal value.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL argument, a null id, a value of another type or outside muiCreateToken's; mui_errorLimit for a gradient of more than MUI_MAX_GRADIENT_STOPS stops; mui_errorBusy while the context is busy; mui_errorStale for a theme or a token that is gone; mui_errorCapacity when the token was not overridden and the context's limit of theme overrides is reached.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiTheme_SetTokenAlias(muiContext* context, muiThemeId themeId, muiTokenId tokenId, muiTokenId target);

Overrides a token in a theme with an alias of another token of its type, read in the subtree that reads the theme.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL context, a null id, a target of another type or an alias that would lead back to the token through the aliases of the context and of any themes, this one included; mui_errorBusy while the context is busy; mui_errorStale for a theme, token or target that is gone; mui_errorCapacity as muiTheme_SetTokenValue.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiTheme_ResetToken(muiContext* context, muiThemeId themeId, muiTokenId tokenId);

Ends a theme's override of a token.

Parameters:

Returns: mui_success, also when the theme did not override it; mui_errorInvalid for a NULL context or a null id; mui_errorBusy while the context is busy; mui_errorStale for a theme or a token that is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiTheme_GetToken(const muiContext* context, muiThemeId themeId, muiTokenId tokenId, muiTokenValue* valueOut, muiTokenId* aliasOut);

Reads a theme's override of a token.

Parameters:

Returns: mui_success; mui_empty when the theme does not override the token; mui_errorInvalid for a NULL context or value, or a null id; mui_errorStale for a theme or a token that is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiNode_SetTheme(muiContext* context, muiNodeId nodeId, muiThemeId themeId);

Sets the theme a node and its subtree read; the null id sets none.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL context or the null node id; mui_errorBusy while the context is busy; mui_errorStale for a node or a theme that is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiNode_GetTheme(const muiContext* context, muiNodeId nodeId, muiThemeId* themeOut);

Reads the theme set on a node.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL argument or the null id; mui_errorStale for an id whose node is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiNode_GetTokenValue(const muiContext* context, muiNodeId nodeId, muiTokenId tokenId, muiTokenValue* valueOut);

Reads a token's value as a node reads it, through the themes above it as of the last muiNode_ComputeLayout that styled it.

Parameters:

Returns: mui_success; mui_empty when the token gives the node no value (an alias to a token that is gone); mui_errorInvalid for a NULL context or value, or a null id; mui_errorStale for a node or a token that is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

token.h

Tokens: typed values that class variants name in place of a property's value, so that a theme is a change of token values. A token holds a literal of its type, or an alias to another token of that type; the aliases of the context and of every theme, taken together, never form a cycle, so none forms under any nesting of themes. Changing a token restyles every node, as a class edit does, and named transitions move the change.

muiTokenDef muiDefaultTokenDef(void);

Returns the default token def: the number 0.

Returns: The def, with a valid cookie.

Thread safety. Safe from any thread.

MUI_NODISCARD MUI_API muiResult muiCreateToken(muiContext* context, const muiTokenDef* def, muiTokenId* tokenOut);

Creates a token holding a value.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL argument, a bad cookie or a value outside the def's; mui_errorLimit for a gradient of more than MUI_MAX_GRADIENT_STOPS stops; mui_errorBusy while the context is busy; mui_errorCapacity when the context's token limit is reached.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiDestroyToken(muiContext* context, muiTokenId tokenId);

Destroys a token. Variants that name it, and tokens that alias it, then give no value through it, and every node is restyled.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL context or the null id; mui_errorBusy while the context is busy; mui_errorStale for an id whose token is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiToken_SetValue(muiContext* context, muiTokenId tokenId, const muiTokenValue* value);

Gives a token a literal value, ending any alias, and restyles every node.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL argument, the null id, a value of another type or outside muiCreateToken's; mui_errorLimit for a gradient of more than MUI_MAX_GRADIENT_STOPS stops; mui_errorBusy while the context is busy; mui_errorStale for an id whose token is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiToken_SetAlias(muiContext* context, muiTokenId tokenId, muiTokenId target);

Makes a token an alias of another of its type, so that it gives that token's value, and restyles every node.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL context, a null id, a target of another type or an alias that would lead back to the token through the aliases of the context and of any themes; mui_errorBusy while the context is busy; mui_errorStale for a token or a target that is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiToken_GetValue(const muiContext* context, muiTokenId tokenId, muiTokenValue* valueOut, muiTokenId* aliasOut);

Reads a token's value, through its aliases, and what it aliases.

Parameters:

Returns: mui_success; mui_empty when an alias leads to a token that is gone; mui_errorInvalid for a NULL context or value, or the null id; mui_errorStale for an id whose token is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiStyle_SetToken(muiContext* context, muiStyleId styleId, muiVariant variant, muiProperty property, muiTokenId tokenId);

Names a token for a property in one variant of a class, in place of a value: resolution reads the token there. A value the property does not allow, or no value, leaves that layer silent for the property. Setting a value for the property with muiStyle_SetLayoutValues or muiStyle_SetVisualValues ends the name, and this ends the value; the null id ends the name alone.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL context, the null class id, an unknown variant or property, a property of no token type or another type than the token's or one the variant's condition reads; mui_errorBusy while the context is busy; mui_errorStale for a class or a token that is gone; mui_errorCapacity when the context's limit of token names, or of property sets for a variant with nothing set, is reached.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiStyle_GetToken(const muiContext* context, muiStyleId styleId, muiVariant variant, muiProperty property, muiTokenId* tokenOut);

Reads the token one variant of a class names for a property.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL argument, the null id, an unknown variant or property; mui_errorStale for an id whose class is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

transition.h

Transitions: specs of how a property moves to a new value (timed with an easing, or a spring), shared by the classes whose variants name them, and run against the time the host passes to muiNode_ComputeLayout. The spec for a change is resolved through the same layers as values, from the state after the change. Numbers, insets, dimensions and radii that are Scale+Offset on both sides, colors (in premultiplied Oklab) and shadows move, ending exactly on their target; enumerators, flags, image keys, gradients, changes to or from automatic, direct writes, and every change under reduced motion apply at once.

muiTransitionDef muiDefaultTransitionDef(void);

Returns the default transition def: timed, 250 ms, ease, no delay; as a spring, 2 Hz and critically damped.

Returns: The def, with a valid cookie.

Thread safety. Safe from any thread.

MUI_NODISCARD MUI_API muiResult muiCreateTransition(muiContext* context, const muiTransitionDef* def, muiTransitionId* transitionOut);

Creates a transition spec.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL argument or a def outside the above; mui_errorBusy while the context is busy; mui_errorCapacity when the context's transition limit is reached.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiDestroyTransition(muiContext* context, muiTransitionId transitionId);

Destroys a transition spec. Variants that name it name none, and transitions it started run to their end.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL context or the null id; mui_errorBusy while the context is busy; mui_errorStale for an id whose spec is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiStyle_SetTransition(muiContext* context, muiStyleId styleId, muiVariant variant, muiTransitionId transitionId, muiPropertyGroup group, muiPropertyMask mask);

Names the spec one variant of a class gives properties; the null id takes the variant's spec away from them.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL context, the null class id, an unknown variant, group or property bit; mui_errorBusy while the context is busy; mui_errorStale for a class or a spec that is gone; mui_errorLimit when the variant already names MUI_MAX_VARIANT_TRANSITIONS specs; mui_errorCapacity when it has no values yet and the context's limit of property sets is reached.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiStyle_GetTransition(const muiContext* context, muiStyleId styleId, muiVariant variant, muiProperty property, muiTransitionId* transitionOut);

Reads the spec one variant of a class gives a property.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL argument, the null id, an unknown variant or property; mui_errorStale for an id whose class is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

bool muiNode_IsTransitioning(const muiContext* context, muiNodeId nodeId, muiProperty property);

Returns whether a property of a node is moving.

Parameters:

Returns: Whether a transition of it runs; false for a stale id or a NULL context.

Thread safety. Safe from any thread; the context is used by one thread at a time.

virtual.h

Virtualization: a scroll container that stands for many items of which only those near its viewport exist as nodes. The library keeps every item's extent, fixed or estimated until measured, works out after each layout the window of items that should exist (the viewport plus overscan on each side), and reports it by mui_notificationWindowChanged when it changes. The host realizes the window: it creates or reuses a child node of the list for each index in it, binds it (muiNode_BindVirtualItem), and destroys or pools the rest, resetting a reused node so nothing of one key outlives it. The library places bound items at their offsets along the axis, out of the flex flow and stretched across the list's content box, sizes the content to all the items so the scroll limits hold, and measures bound items into their extents.

muiVirtualList muiDefaultVirtualList(void);

The default list: no items, vertical, estimated at 40 a piece, no gap, an overscan of 200.

Returns: The list.

Thread safety. Safe from any thread.

MUI_NODISCARD MUI_API muiResult muiNode_SetVirtualList(muiContext* context, muiNodeId nodeId, const muiVirtualList* list);

Makes a node a virtual list, or sets it anew, every estimated extent back to the estimate; its window is reported at the next layout. Set anew, as after its data was replaced, it keeps the item it showed first where it was, if the host binds that item's node again before the next layout, wherever the item now is.

Parameters:

Returns: mui_success; mui_errorCapacity when the context holds its limit of lists, or the items of an estimated list do not fit what its limit of items leaves; mui_errorInvalid for a NULL argument, the null id or a list outside the above; mui_errorLimit for more than MUI_MAX_VIRTUAL_ITEMS items; mui_errorBusy while the context is busy; mui_errorStale for a node that is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiNode_ClearVirtualList(muiContext* context, muiNodeId nodeId);

Makes a node no longer a virtual list; its items stay bound.

Parameters:

Returns: mui_success, whether or not it was one; mui_errorInvalid for a NULL context or the null id; mui_errorBusy while the context is busy; mui_errorStale for a node that is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiNode_GetVirtualWindow(const muiContext* context, muiNodeId nodeId, uint32_t* firstOut, uint32_t* endOut);

Reads the window of a list's items that should exist, as the last layout found it: indices from first up to end, end excluded.

Parameters:

Returns: mui_success; mui_empty for a node that is not a list or has not been laid out since it was set; mui_errorInvalid for a NULL argument or the null id; mui_errorStale for a node that is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiNode_GetVirtualItem(const muiContext* context, muiNodeId nodeId, uint32_t index, float* offsetOut, float* extentOut);

Reads where an item of a list begins along its axis, from the start of the list's content box, and its extent, as last known.

Parameters:

Returns: mui_success; mui_empty for a node that is not a list; mui_errorInvalid for a NULL argument, the null id or an index past the count; mui_errorStale for a node that is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiNode_BindVirtualItem(muiContext* context, muiNodeId nodeId, uint32_t index);

Binds a child of a list to an item: the next layouts place it at the item's offset and measure it into the item's extent.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL context, the null id, a node whose parent is not a list or an index past the list's count; mui_errorBusy while the context is busy; mui_errorStale for a node that is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiNode_UnbindVirtualItem(muiContext* context, muiNodeId nodeId);

Unbinds a node from its item; it joins its parent's flow again.

Parameters:

Returns: mui_success, whether or not it was bound; mui_errorInvalid for a NULL context or the null id; mui_errorBusy while the context is busy; mui_errorStale for a node that is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiNode_GetBoundVirtualItem(const muiContext* context, muiNodeId nodeId, uint32_t* indexOut);

Reads the item a node is bound to.

Parameters:

Returns: mui_success; mui_empty for a node bound to none, or to an item since removed; mui_errorInvalid for a NULL argument or the null id; mui_errorStale for a node that is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiNode_InsertVirtualItems(muiContext* context, muiNodeId nodeId, uint32_t index, uint32_t count);

Inserts items into a list before index, estimated; the items after keep their extents, and nodes bound to them follow them. Inserted above the viewport, they move the offset along, so what is shown stays put.

Parameters:

Returns: mui_success; mui_empty for a node that is not a list; mui_errorCapacity when an estimated list's items no longer fit its limit; mui_errorInvalid for a NULL context, the null id, an index past the count or no items; mui_errorLimit for more than MUI_MAX_VIRTUAL_ITEMS in all; mui_errorBusy while the context is busy; mui_errorStale for a node that is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiNode_RemoveVirtualItems(muiContext* context, muiNodeId nodeId, uint32_t index, uint32_t count);

Removes items from a list; nodes bound to them stay out of the flow, placed nowhere, until the host destroys or binds them (muiNode_GetBoundVirtualItem reports them empty), and the rest follow their items. Removed above the viewport, they move the offset back.

Parameters:

Returns: mui_success; mui_empty for a node that is not a list; mui_errorInvalid for a NULL context, the null id, a range outside the list or empty; mui_errorBusy while the context is busy; mui_errorStale for a node that is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiNode_MoveVirtualItem(muiContext* context, muiNodeId nodeId, uint32_t from, uint32_t to);

Moves an item of a list to another index, its extent with it; its node, bound, follows it, as do those between. What is shown stays put when the item crosses the viewport's start.

Parameters:

Returns: mui_success; mui_empty for a node that is not a list; mui_errorInvalid for a NULL context, the null id or an index past the count; mui_errorBusy while the context is busy; mui_errorStale for a node that is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

visual.h

Visual values: what the draw-command list paints for a node, set through the same classes, variants, conditions, transitions and direct writes as layout values. A change to one marks the node's paint, never its layout.

muiVisualStyle muiDefaultVisualStyle(void);

Returns the default visual style: clear background, no gradient, square corners, opaque black border colors, no shadows or image, a white tint that does not mirror, opacity 1, no clipping and a scale of 1 about the centre.

Returns: The values.

Thread safety. Safe from any thread.

MUI_NODISCARD MUI_API muiResult muiStyle_SetVisualValues(muiContext* context, muiStyleId styleId, muiVariant variant, const muiVisualStyle* values, muiPropertyMask mask);

Sets visual properties in one variant of a class from the fields of values, as muiStyle_SetLayoutValues does layout ones.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL argument, the null id, an unknown variant or property bit or a value outside the above, which changes nothing; mui_errorLimit for a gradient of more than MUI_MAX_GRADIENT_STOPS stops; mui_errorBusy while the context is busy; mui_errorStale for an id whose class is gone; mui_errorCapacity when the variant had no values and the context's limit of property sets is reached.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiStyle_GetVisualValues(const muiContext* context, muiStyleId styleId, muiVariant variant, muiVisualStyle* valuesOut, muiPropertyMask* maskOut);

Reads the visual values one variant of a class sets.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL argument, the null id or an unknown variant; mui_errorStale for an id whose class is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiNode_SetVisualValues(muiContext* context, muiNodeId nodeId, const muiVisualStyle* values, muiPropertyMask mask);

Writes visual properties of a node directly, as muiNode_SetLayoutValues does layout ones; the node's paint, not its layout, is redone.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL argument, the null id, an unknown property bit or a value outside the above, which changes nothing; mui_errorLimit for a gradient of more than MUI_MAX_GRADIENT_STOPS stops; mui_errorBusy while the context is busy; mui_errorStale for a node that is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

MUI_NODISCARD MUI_API muiResult muiNode_GetVisualStyle(const muiContext* context, muiNodeId nodeId, muiVisualStyle* valuesOut);

Reads a node's resolved visual values: its direct writes, and for the other properties what its classes and states gave at the last muiNode_ComputeLayout that reached it, where its transitions have them.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL argument or the null id; mui_errorStale for an id whose node is gone.

Thread safety. Safe from any thread; the context is used by one thread at a time.

The maul-ui-rhi part

renderer.h

The reference renderer, the optional target maul-ui-rhi: a draw list drawn with Maul RHI, every command an instance of one pipeline whose fragment shader evaluates it. Each frame, while the host builds it, muiRhiRenderer_AddPasses adds the renderer's upload and draw passes into the host's target; after mrhiDevice_CompileFrame, muiRhiRenderer_Record records them. The core and the text component never depend on it; it is a static library, whose functions MUI_RHI_API marks.

muiRhiRendererDef muiDefaultRhiRendererDef(void);

The default def: the C library's allocation, no device, an sRGB RGBA8 target, room for 1024 instances, no depth and a less-or-equal depth test.

Returns: The def.

Thread safety. Safe from any thread.

MUI_NODISCARD MUI_RHI_API muiResult muiCreateRhiRenderer(const muiRhiRendererDef* def, muiRhiRenderer** rendererOut);

Makes a renderer: its shader, its pipeline, whose creation finishes later (muiRhiRenderer_GetPipelineRequest), and its instance buffer.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL argument, a def not from muiDefaultRhiRendererDef, a half-set allocator, no device or instances, an upload share above the device's frameUploadBytes, or a text service where Maul UI was built without text; mui_errorCapacity when memory runs out; mui_errorPlatform when the device refuses the shader, the pipeline, a buffer or a texture.

Thread safety. Safe from any thread; the renderer and its device are used by one thread at a time.

void muiDestroyRhiRenderer(muiRhiRenderer* renderer);

Destroys a renderer and its device objects, which the device retires after the frames that used them; NULL is ignored.

Parameters:

Thread safety. Safe from any thread; the renderer and its device are used by one thread at a time.

mrhiRequestId muiRhiRenderer_GetPipelineRequest(const muiRhiRenderer* renderer);

The request its pipeline's creation answers on the device's notification queue (mrhi_devicePipelineReady).

Parameters:

Returns: The request; a null one for a NULL renderer.

Thread safety. Safe from any thread; the renderer and its device are used by one thread at a time.

bool muiRhiRenderer_Notify(muiRhiRenderer* renderer, const mrhiDeviceNotification* notification);

Hands the renderer a notification the host took from the device's queue (mrhiDevice_TakeNotification): the one answering its pipeline makes it ready, or failed.

Parameters:

Returns: Whether the notification was the renderer's.

Thread safety. Safe from any thread; the renderer and its device are used by one thread at a time.

bool muiRhiRenderer_IsReady(const muiRhiRenderer* renderer);

Whether its pipelines are ready, so that frames draw: one, and a second testing depth when the def names a depth format.

Parameters:

Returns: Whether it is ready; false for a NULL renderer.

Thread safety. Safe from any thread; the renderer and its device are used by one thread at a time.

MUI_NODISCARD MUI_RHI_API muiResult muiRhiRenderer_AddPasses(muiRhiRenderer* renderer, const muiDrawList* list, const muiRhiTarget* target);

Adds the renderer's passes to the frame the device is building: one uploading what changed of the list's instances and the glyph images the atlas changed, one drawing them into the target. The list is read now; it may change after the call.

Parameters:

Returns: mui_success; mui_empty when its pipelines are not ready yet, nothing added; mui_errorInvalid for a NULL argument, a target of no size, or a depth texture without a projection or a def's depth format; mui_errorCapacity when memory runs out, or the frame's uploads would not fit the renderer's upload budget, nothing added; mui_errorPlatform when the device refuses a pass, a buffer or a texture.

Thread safety. Safe from any thread; the renderer and its device are used by one thread at a time.

MUI_NODISCARD MUI_RHI_API muiResult muiRhiRenderer_Record(muiRhiRenderer* renderer);

Records the passes muiRhiRenderer_AddPasses added, after the frame is compiled; nothing when it added none.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL renderer; mui_errorPlatform when the device refuses a command.

Thread safety. Safe from any thread; the renderer and its device are used by one thread at a time.

void muiRhiRenderer_Forget(muiRhiRenderer* renderer);

Forgets what the last recorded frame uploaded, after the host dropped that frame instead of submitting it: the next frame uploads every record and the glyph images that frame wrote.

Parameters:

Thread safety. Safe from any thread; the renderer is used by one thread at a time.

The maul-ui-window part

access.h

Accessibility through the Maul Window glue, in maul-ui-window where Maul UI builds its accessibility tree's consumer: one access a glue makes the adapter built for its window's platform over the window's native handles, feeds it the root's updates and hands its root to the window (mwinWindow_RequestAccessibilityRoot) as it changes. A window of a platform with no adapter built, or of Maul Window's test backend, keeps the tree alone, so a program can check what its clients would be told without them.

muiWindowAccessDef muiDefaultWindowAccessDef(void);

Returns the default access def: no glue, 4096 nodes, no AT-SPI application, on the web the elements waiting for a button labelled "Enable accessibility" (as muiDefaultAriaAdapterDef), the context doing what clients ask.

Returns: The def, with a valid cookie.

Thread safety. Safe from any thread.

MUI_NODISCARD MUI_WINDOW_API muiResult muiCreateWindowAccess(const muiWindowAccessDef* def, muiWindowAccess** accessOut);

Makes a glue's access: enables the root's updates (muiNode_EnableAccess) and makes the adapter for the window's platform (UI Automation on Win32, NSAccessibility on macOS, UIAccessibility on iOS, Android's over the activity's view, ARIA in the element Maul Window keeps over the canvas, AT-SPI on X11 and Wayland with an application), or a tree alone. A program may make it once mwin_eventAccessibilityRequested arrives, to build no tree before a client asks where the platform says so.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL argument or a def outside the above, or a window with no surface; mui_errorCapacity when the context has its limit of enabled roots, the AT-SPI application its windows, or memory runs out; as the adapter's creation otherwise.

Thread safety. Main thread only. The adapters are too.

void muiDestroyWindowAccess(muiWindowAccess* access);

Destroys an access: hands the window no root, lets the adapter go and stops the root's updates (muiNode_EnableAccess).

Parameters:

Thread safety. Main thread only.

MUI_NODISCARD MUI_WINDOW_API muiResult muiWindowAccess_Update(muiWindowAccess* access);

Sends the root's changes since the last call (muiNode_BuildAccessUpdate) to the adapter, and hands the window the adapter's root if it changed. The program calls it each frame after layout.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL access, or a root request Maul Window refuses; as muiNode_BuildAccessUpdate and the adapter's update otherwise.

Thread safety. Main thread only.

MUI_NODISCARD MUI_WINDOW_API muiResult muiWindowAccess_HandleEvent(muiWindowAccess* access, const mwinEvent* event);

Takes a record the host drained: a scale change of the window rescales the adapter's bounds where they are in pixels (UI Automation, Android, AT-SPI), and a move places an AT-SPI window on the screen. Others it leaves.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL argument.

Thread safety. Main thread only.

const muiAccessTree* muiWindowAccess_GetTree(const muiWindowAccess* access);

Returns the tree the access holds, the adapter's or its own.

Parameters:

Returns: The tree; NULL for a NULL access.

Thread safety. Safe from any thread; the access is used by one thread at a time.

bool muiWindowAccess_IsAdapterCreated(const muiWindowAccess* access);

Returns whether the access made a platform's adapter, rather than keeping a tree alone.

Parameters:

Returns: Whether it did; false for a NULL access.

Thread safety. Safe from any thread; the access is used by one thread at a time.

clipboard.h

The clipboard of the Maul Window glue for text editing, in maul-ui-window where Maul UI has its text component: copies and cuts written to the window's clipboard, and a paste asked of it and taken into an editing block when the window answers, as Maul Window reads the clipboard by request.

void muiWriteWindowClipboard(void* glue, const char* text, size_t length);

Writes text to the glue's window's clipboard, as a muiClipboardWriteFunction whose user is the glue (muiTextEditInput). A write the window refuses (text past its clipboard limit, too many requests) is dropped, as a failed copy is on every platform.

Parameters:

Thread safety. Main thread only. Maul Window's requests are too.

MUI_NODISCARD MUI_WINDOW_API muiResult muiWindowGlue_RequestPaste(muiWindowGlue* glue);

Asks the window for its clipboard's text, for a paste muiNode_HandleEditEvent asked for (outcome.paste); muiTextBlock_PasteFromWindow takes the answer.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL glue or a request the window refuses.

Thread safety. Main thread only. Maul Window's requests are too.

MUI_NODISCARD MUI_WINDOW_API muiResult muiTextBlock_PasteFromWindow(muiWindowGlue* glue, muiTextService* service, muiTextBlockId blockId, const mwinEvent* event, bool* changedOut);

Pastes the clipboard's text into an editing block when an event answers a clipboard read with it (mwin_eventRequestCompleted, a read done, whose text no later read replaced); other events pass.

Parameters:

Returns: mui_success for a paste, changed or not; mui_empty for another event or a read a later one replaced; mui_errorInvalid for a NULL argument; mui_errorCapacity when memory for the text runs out; or as muiTextBlock_Paste.

Thread safety. Main thread only. Maul Window's calls are too.

composition.h

Compositions and carets of the Maul Window glue, in maul-ui-window where Maul UI has its text component: an input method's preedit set into a text block, and the candidate window placed at a position of a node's text. Maul Window's preedit styles and segment limit are Maul UI's composition styles and limit. An editing block takes a preedit through muiTextBlock_ShowPreedit, and its field's purpose picks the on-screen keyboard (muiNode_RequestWindowKeyboard).

MUI_NODISCARD MUI_WINDOW_API muiResult muiTextBlock_SetPreedit(muiTextService* service, muiTextBlockId blockId, size_t offset, const mwinPreeditEvent* preedit, size_t* caretOut);

Sets a block's composition from an input method's preedit (muiTextBlock_SetComposition): its text, and its segments as they come; an empty preedit removes the composition and ends it, the committed text arriving as text input after it.

Parameters:

Returns: As muiTextBlock_SetComposition, with mui_errorInvalid for a NULL preedit, or a caret neither -1 nor a character boundary of its text, which leaves the block.

Thread safety. Safe from any thread; the service is used by one thread at a time.

MUI_NODISCARD MUI_WINDOW_API muiResult muiTextBlock_ShowPreedit(muiTextService* service, muiTextBlockId blockId, const mwinPreeditEvent* preedit, bool* changedOut);

Shows an input method's preedit in an editing block (muiTextBlock_Compose): its text, its caret, at the end where the method hides it, and its segments as they come; an empty preedit takes the composition out, the committed text arriving as text input after it. A window shows no composition after its mwin_eventInputStateReset, so at a reset of the block's own window give the block an empty preedit too: the input method's next preedit shows its composition again. A reset of another window, or a gamepad's (the null window), leaves the composition.

Parameters:

Returns: As muiTextBlock_Compose, with mui_errorInvalid for a NULL preedit, or a caret neither -1 nor a character boundary of its text.

Thread safety. Safe from any thread; the service is used by one thread at a time.

MUI_NODISCARD MUI_WINDOW_API muiResult muiNode_SetWindowTextCaret(muiWindowGlue* glue, const muiTextHost* host, muiNodeId nodeId, muiTextPosition position, mwinRect* placedOut);

Asks the window to accept text with its caret at a position of a node's text (muiNode_GetTextCaret in the node's content box, then muiNode_SetWindowCaret), the caret a rectangle as tall as its line and of no width.

Parameters:

Returns: As muiNode_GetTextCaret and muiNode_SetWindowCaret.

Thread safety. Main thread only. Maul Window's requests are too.

MUI_NODISCARD MUI_WINDOW_API muiResult muiNode_RequestWindowKeyboard(muiWindowGlue* glue, const muiTextHost* host, muiNodeId nodeId);

Asks for the window's on-screen keyboard, where the platform has one, laid out for what a node's editing block takes (muiTextBlock_GetInputPurpose; plain text for a block not editing), or, with the null id, to hide it (mwinWindow_RequestVirtualKeyboard). Ask as the focus enters and leaves a field.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL argument, a host without a context, or a request Maul Window refuses; mui_errorStale for a node that is gone.

Thread safety. Main thread only. Maul Window's requests are too.

glue.h

The Maul Window glue, the optional target maul-ui-window: one glue a window feeds the records the host drains from Maul Window to a Maul UI context, keeping what Maul Window does not (the cursor's place, the buttons held) and saying of each record whether the UI handled it, so that the host hands the rest to its game. Keys and text pass as they come, the codes, meanings and modifiers being the same; the cursor is a mouse pointer, a touch a touch pointer and the pen a pen pointer, their records dispatched at once; the wheel turns at the cursor's last place; a reset or a lost focus cancels every pointer. The core and the text component never depend on it; it is a static library, whose functions MUI_WINDOW_API marks.

muiWindowGlueDef muiDefaultWindowGlueDef(void);

Returns the default glue def: no window, context or root, player 0, no gamepads, and the defaults above for those who take them.

Returns: The def, with a valid cookie.

Thread safety. Safe from any thread.

MUI_NODISCARD MUI_WINDOW_API muiResult muiCreateWindowGlue(const muiWindowGlueDef* def, muiWindowGlue** glueOut);

Makes a glue for a window.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL argument or a def outside the above; mui_errorCapacity when memory runs out.

Thread safety. Safe from any thread.

void muiDestroyWindowGlue(muiWindowGlue* glue);

Destroys a glue.

Parameters:

Thread safety. Safe from any thread; the glue is used by one thread at a time.

MUI_NODISCARD MUI_WINDOW_API muiResult muiWindowGlue_HandleEvent(muiWindowGlue* glue, const mwinEvent* event, bool* handledOut);

Takes a record the host drained from Maul Window. A record of its window goes to the context: a key or text to the player's focus (muiNode_RouteKey, muiNode_RouteText); the cursor as the player's mouse (muiNode_RoutePointer, its records dispatched with muiContext_DispatchPointerRecord), Maul Window's button b its index b - 1; a touch as a touch pointer holding the primary button while in contact; the pen as a pen pointer, its tip in contact the primary button or button 5 while it erases, its barrel the secondary, as the W3C's Pointer Events number them; the wheel at the cursor's last place (muiNode_RouteWheel); a reset or a lost focus as a cancel of every pointer holding a button. A pointer's records are the UI's when a record it posts is handled, while the UI holds the pointer (pressed or captured), or where the point hits a node that does not pass input through (muiNode_HitTest); a key, text or wheel is the UI's when routing handles it. A glue that takes gamepads takes their records, which have no window, as navigation for the player the host names (muiNode_RouteNavigation): the d-pad, and the left stick past its threshold, the four directions; the south face activate and the east cancel, or the other way with confirmEast; the left and right shoulders previous and next. Records of other windows and of other kinds are not the UI's.

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL argument, a call from a measure, paint or event function, or a record Maul UI refuses (its own checks pass it on); mui_errorStale for a root that is gone; mui_errorCapacity for a pointer past the context's limit.

Thread safety. Safe from any thread; the glue and its context are used by one thread at a time.

MUI_NODISCARD MUI_WINDOW_API muiResult muiWindowGlue_Tick(muiWindowGlue* glue, uint64_t nowNs, bool* handledOut);

Continues the directions gamepads hold, for a glue that takes gamepads: each direction held past the repeat delay navigates again (muiNode_RouteNavigation) at the repeat interval, one direction a call. The host calls it each frame with the time on the records' clock.

Parameters:

Returns: As muiWindowGlue_HandleEvent.

Thread safety. Safe from any thread; the glue and its context are used by one thread at a time.

MUI_NODISCARD MUI_WINDOW_API muiResult muiNode_SetWindowCaret(muiWindowGlue* glue, muiNodeId nodeId, muiRect caret, mwinRect* placedOut);

Asks the window to accept text with its caret at a rectangle of a node's border box, carried into the window (muiNode_MapToRoot), so the platform places its candidate window there (mwinWindow_RequestTextInputCaret, then mwinWindow_RequestTextInput); or, with the null id, to stop, the window keeping its caret. Ask again as the caret moves, or as layout or scrolling moves the node. mwin_eventImePreedit records then report what an input method composes; they are not the UI's, and the host hands them to its text field (maul-ui-window/composition.h).

Parameters:

Returns: mui_success; mui_errorInvalid for a NULL glue, a caret not finite or of a negative size, or a request Maul Window refuses; mui_errorStale for a node that is gone.

Thread safety. Main thread only. Maul Window's requests are too.