nicbarker / clay

Clay, A UI Layout Library **_Clay_** (short for **C Layout**) is a high performance 2D UI layout library. Major Features • Microsecond layout performance • Flex-box like layout model for complex, responsive layouts including text wrapping, scrolling containers and aspect ratio scaling • Single ~4k LOC **clay.h** file with **zero** dependencies (including no standard library) • Wasm support: compile with clang to a 15kb uncompressed **.wasm** file for use in the browser • Static arena based memory use with no malloc / free, and low total memory overhead (e.g. ~3.5mb for 8192 layout elements). • React-like nested declarative syntax • Renderer agnostic: outputs a sorted list of rendering primitives that can be easily composited in any 3D engine, and even compiled to HTML (examples provided) Take a look at the clay website for an example of clay compiled to wasm and running in the browser, or others in the examples directory. You can also watch the introduction video for an overview of the motivation behind Clay's development and a short demo of its usage. _An example GUI application built with clay_ Quick Start Download or clone clay.h and include it after defining in one file. The above example, rendered correctly will look something like the following: In summary, the general order of steps is: • Clay_SetLayoutDimensions(dimensions) • Clay_SetPointerState(pointerPosition, isPointerDown) • Clay_UpdateScrollContainers(enableDragScrolling, scrollDelta, deltaTime) • Clay_BeginLayout() • Declare your layout with the provided Element Macros • Clay_EndLayout() • Render the results using the outputted Clay_RenderCommandArray For help starting out or to discuss clay, considering joining the discord server. Summary • High Level Documentation • Building UI Hierarchies • Configuring Layout and Styling UI Elements • Element IDs • Mouse, Touch and Pointer Interactions • Scrolling Elements • Floating Elements • Custom Elements • Retained Mode Rendering • Visibility Culling • Preprocessor Directives • Bindings • Debug Tools • API • Naming Conventions • Public Functions • Lifecycle • Clay_MinMemorySize • Clay_CreateArenaWithCapacityAndMemory • Clay_SetMeasureTextFunction • Clay_ResetMeasureTextCache • Clay_SetMaxElementCount • Clay_SetMaxMeasureTextCacheWordCount • Clay_Initialize • Clay_GetCurrentContext • Clay_SetCurrentContext • Clay_SetLayoutDimensions • Clay_SetPointerState • Clay_UpdateScrollContainers • Clay_BeginLayout • Clay_EndLayout • Clay_Hovered • Clay_OnHover • Clay_PointerOver • Clay_GetScrollContainerData • Clay_GetElementData • Clay_GetElementId • Element Macros • CLAY • CLAY_ID • CLAY_IDI • Data Structures & Defs • Clay_String • Clay_ElementId • Clay_RenderCommandArray • Clay_RenderCommand • Clay_ScrollContainerData • Clay_ErrorHandler • Clay_ErrorData High Level Documentation Building UI Hierarchies Clay UIs are built using the C macro . This macro creates a new empty element in the UI hierarchy, and supports modular customisation of layout, styling and functionality. The macro can also be _nested_, similar to other declarative UI systems like HTML. Child elements are added by opening a block: after calling the macro (exactly like you would with an statement or loop), and declaring child components inside the braces. However, unlike HTML and other declarative DSLs, this macro is just C. As a result, you can use arbitrary C code such as loops, functions and conditions inside your layout declaration code: Configuring Layout and Styling UI Elements The layout and style of clay elements is configured with the Clay_ElementDeclaration struct passed to the macro. This macro isn't magic - all it's doing is wrapping the standard designated initializer syntax. e.g. . See the Clay_ElementDeclaration API for the full list of options. A struct can be defined in file scope or elsewhere, and reused. Element IDs The Clay macro by default accepts an ID as its first argument, which is usually provided by the CLAY_ID() convenience macro. Elements can also be created with auto generated IDs, by using the CLAY_AUTO_ID() macro. Element IDs have two main use cases. Firstly, tagging an element with an ID allows you to query information about the element later, such as its mouseover state or dimensions. Secondly, IDs are visually useful when attempting to read and modify UI code, as well as when using the built-in debug tools. To avoid having to construct dynamic strings at runtime to differentiate ids in loops, clay provides the CLAY_IDI(string, index) macro to generate different ids from a single input string. Think of IDI as "**ID** + **I**ndex" This ID will be forwarded to the final for use in retained mode UIs. Using duplicate IDs may cause some functionality to misbehave (i.e. if you're trying to attach a floating container to a specific element with ID that is duplicated, it may not attach to the one you expect) Mouse, Touch and Pointer Interactions Clay provides several functions for handling mouse and pointer interactions. All pointer interactions depend on the function being called after each mouse position update and before any other clay functions. **During UI declaration** The function can be called during element construction or in the body of an element, and returns if the mouse / pointer is over the currently open element. The function allows you to attach a function pointer to the currently open element, which will be called if the mouse / pointer is over the element. **Before / After UI declaration** If you want to query mouse / pointer overlaps outside layout declarations, you can use the function , which takes an element id and returns a bool representing whether the current pointer position is within its bounding box. Note that the bounding box queried by is from the last frame. This generally shouldn't make a difference except in the case of animations that move at high speed. If this is an issue for you, performing layout twice per frame with the same data…