API Reference

MicroUI.jl - A Julia implementation of an immediate mode GUI library

This module provides a complete immediate mode GUI (IMGUI) implementation in Julia, inspired by the microui C library. Immediate mode GUIs rebuild the entire interface each frame, making them simpler to reason about and integrate into applications.

Key concepts:

• No persistent widget state - everything is recreated each frame
• Direct integration with rendering backends
• Minimal memory allocations during runtime
• Command-based rendering system for backend independence

Maximum depth of clipping rectangle stack for nested clipping regions

Size of the command buffer in bytes - stores all rendering commands for a frame

Size of the container pool for efficient container reuse

Maximum depth of nested containers (windows, panels, etc.)

Default visual style with dark theme colors Provides sensible defaults for all UI elements

Hash constant for ID generation

Maximum depth of ID stack for hierarchical widget identification

Maximum depth of layout stack for nested layout contexts

Maximum length for number format strings

Maximum number of columns in a layout row

Default format string for real number display

Layout positioning modes

Maximum number of root containers (windows) that can be active simultaneously

Default format string for slider values

Size of the treenode pool for efficient treenode state management

Unclipped rectangle for resetting clipping state

Current version of the MicroUI library

Base header present in all command types Contains type information and size for command buffer traversal

Clipping command to set the active clipping rectangle All subsequent rendering will be clipped to this region

Clipping test results when checking if a rectangle is visible within the clip region

• CLIP_NONE: Rectangle is fully visible, no clipping needed
• CLIP_PART: Rectangle is partially visible, clipping required
• CLIP_ALL: Rectangle is completely outside clip region, skip rendering

RGBA color with 8 bits per channel All color values in the library use this format

Predefined color IDs for different UI elements These indices map to colors in the style's color array

Abstract base type for all rendering commands

Iterator for traversing the command buffer Handles jump commands automatically for proper Z-order rendering

Command buffer that stores all rendering commands for a frame Manages both binary command data and string storage

Pointer/index into the command buffer for command linking

Types of rendering commands that can be stored in the command buffer Each command type corresponds to a specific rendering operation

Container represents a window, panel, or other widget grouping Maintains its own command buffer region and layout state

Main context structure containing all UI state This is the primary object that applications interact with

Create new context with default settings Applications should call init! after creation

Font handle - can be any type depending on rendering backend

Icon drawing command for built-in symbols Icons are simple geometric shapes drawn at specified rectangles

Built-in icon identifiers for common UI symbols Icons are drawn as simple geometric shapes

Unique identifier for widgets and containers, generated from strings

Jump command for non-linear command buffer traversal Used to implement container Z-ordering and command list linking

Keyboard key flags for modifier keys and special keys Can be combined to check for key combinations

Layout state for a container or layout context Manages positioning, sizing, and flow of widgets within a region

Mouse button flags that can be combined with bitwise operations Multiple buttons can be pressed simultaneously

Option flags for controlling widget and container behavior These flags can be combined using bitwise OR operations

Pool item for efficient resource management Tracks when resources were last used for automatic cleanup

Floating point type used for numeric values throughout the library

Rectangle defined by position and size Forms the basis for all layout and clipping operations

Rectangle drawing command for filled rectangles Used for backgrounds, borders, and solid color areas

Result flags returned by interactive widgets Indicate what actions occurred during the last frame

Generic stack data structure with overflow protection Used for managing nested contexts (containers, clips, layouts, etc.)

Visual style configuration for the UI Contains colors, sizes, and other visual parameters

Text rendering command for drawing strings Includes position, color, and string data

2D integer vector for positions, sizes, and offsets Used extensively for layout calculations and positioning

Scale vector by scalar

Add two vectors

Subtract two vectors

Check if stack is empty

Begin a new frame of UI processing Must be called before any widgets or containers

Simple panel widget

Begin panel container Creates nested container within current layout

Begin popup window Creates auto-sizing popup with no title bar or resize controls

Initialize root container for rendering Sets up command buffer region and hover detection

Simple treenode widget

Begin collapsible treenode section Returns RES_ACTIVE if expanded

Simple window widget

Begin window with full customization options Creates moveable, resizable window with title bar and optional controls

Bring container to front by updating its Z-index Higher Z-index containers are rendered on top

Simple button widget with label Default button with center-aligned text

Button widget with full customization options Returns RES_SUBMIT flag when clicked

Test if rectangle is visible within current clipping region Returns clipping result for optimization decisions

Checkbox widget for boolean values Returns RES_CHANGE when toggled

Clamp value between minimum and maximum bounds

Compare containers by Z-index for sorting

Default frame drawing function Draws a filled rectangle with optional border

Draw rectangle outline (border) Draws four separate rectangles for top, bottom, left, and right edges

Draw control frame with state-dependent styling Automatically selects color based on focus and hover state

Draw control text with proper alignment and clipping Handles text positioning within widget rectangles

Draw built-in icon with automatic clipping Icons are simple geometric shapes rendered by the backend

Draw filled rectangle with clipping Only draws visible portions of the rectangle

Draw scrollbar for given axis Handles scrollbar interaction and thumb positioning

Draw text string with automatic clipping handling Sets up clipping if needed and creates text command

End current frame and prepare command buffer for rendering Handles container sorting, scrolling, and focus management

End panel container

End popup window

Finalize root container Sets up command buffer tail and cleans up stacks

End treenode section

End window and clean up

Expand rectangle by given amount in all directions Useful for creating borders and padding

Expand rectangle by n pixels in all directions

Format real numbers for display in widgets Provides consistent number formatting throughout the UI

Get current clipping rectangle

Convenience function to get container by name

Get or create container with given ID Uses pool for efficient container reuse

Get current container from container stack

Generate unique ID from string data Uses FNV-1a hash algorithm for consistent ID generation

Get current layout context from stack

Retrieve a string from the string table by index Used when processing text commands during rendering

Simple header widget

Header widget for grouping content

Implementation for header and treenode widgets Handles expand/collapse state and visual styling

Check if current container stack contains the hover root Used to determine if widgets should respond to mouse input

Initialize or reset context to default state Should be called before first use and when resetting UI state

Handle key press event

Handle key release event

Convenience overload for Int32 coordinates

Handle mouse button press event

Update mouse position

Convenience overload for Int32 coordinates

Handle mouse button release event

Handle mouse scroll wheel input

Add text input for current frame

Calculate intersection of two rectangles Returns rectangle representing overlapping area

Simple text label widget Displays single line of text within widget rectangle

Start column layout context within current layout

End column layout and merge extents with parent Updates parent layout's position and maximum extents

Set default height for next widget

Calculate and return rectangle for next widget Handles both manual positioning and automatic layout flow

Set up new layout row with specified items and dimensions Controls how widgets are positioned horizontally

Manually set rectangle for next widget Can be relative to current position or absolute

Set default width for next widget

Test if mouse is over widget rectangle Considers clipping and hover root for proper interaction

Advance iterator to next command, handling jumps automatically Returns (hascommand, commandtype, command_offset)

Simple number widget Default number input with standard step and formatting

Number input widget with drag adjustment Allows precise number input and mouse drag adjustment

Number editing textbox for slider/number widgets Handles special number editing mode with shift+click

Open popup window at mouse position Sets up popup to appear at current mouse location

Find pool item by ID Returns index if found, -1 if not found

Initialize pool item with given ID Finds least recently used slot and assigns it to the ID

Update pool item's last access time to current frame

Pop item from stack with underflow checking

Remove current clipping rectangle from stack

Pop container and update its content size Called when exiting containers to finalize layout

Pop ID scope from stack

Push item onto stack with overflow checking

Push new clipping rectangle onto stack

Add command to command buffer Returns offset where command was written

Set up container body with scrollbars and layout Prepares container for content rendering

Push new ID scope onto ID stack Creates hierarchical namespace for widget IDs

Add jump command for non-linear command buffer traversal Used to implement container Z-ordering

Create new layout context with given body rectangle and scroll offset Used when entering containers or column layouts

Add text rendering command with string data Handles string storage and creates complete text command

Read a command from the buffer at the specified offset Type parameter specifies which command type to read

Test if point is inside rectangle Used for hit testing and mouse interaction

Handle scrollbars for container Adjusts body rectangle to make room for scrollbars

Set clipping rectangle for subsequent rendering commands

Set keyboard focus to specific widget Widget will receive keyboard input and be highlighted

Simple slider widget Default slider with standard formatting

Slider widget with full customization Allows dragging to adjust value within specified range

Multi-line text display widget Automatically handles word wrapping and line breaks

Simple textbox widget Default textbox with no special options

Textbox widget with options Provides text input with specified buffer size

Raw textbox implementation with full control Handles text input, editing, and cursor display

Get top item from stack without removing it

Update widget interaction state Handles hover, focus, and click detection for interactive widgets

Write a command to the command buffer Returns the offset where the command was written

Store a string in the command list and return its index Used by text commands to reference their string data

Global registry of all widget states, keyed by window ID

Widget state container that persists between frames. Stores variables, refs for stateful widgets, event handlers, and window state.

Clear all widget states (useful for testing and cleanup)

Convert to proper vector type for layout.

Convert to Real (Float32) for MicroUI consistency.

Get or create widget state for a given window ID. Returns the same instance for the same window across multiple frames.

Parse assignment expressions like 'var = value'. Returns (variablename, valueexpression) tuple.

Button widget. Usage: @button name = "text"

Checkbox widget with bulletproof type handling. Usage: @checkbox name = true/false

Close window macro. Usage: @close_window "Window Title"

Column layout. Usage: @column begin ... end

Context management macro for MicroUI.

Creates and manages a MicroUI context with proper frame lifecycle. All windows and UI elements must be inside a @context block.

Usage:

ctx = @context begin
    @window "My Window" begin
        @var message = "Hello World"
    end
end

Returns the MicroUI Context with all rendering commands.

Debug macro to check types of widget state values. Usage: @debugtypes windowname

Loop for dynamic widgets. Usage: @foreach i in 1:5 begin ... end

Helper macro for maxlength with proper types. Usage: maxlength(256) -> Int value

Number widget macro for precise numeric input. Usage: @number num_name = 10.0 step(1.0)

Click event handler. Usage: @onclick widget_name begin ... end

Open window macro. Usage: @open_window "Window Title"

Panel macro for grouped widgets. Usage: @panel "Title" begin ... end

Popup message. Usage: @popup "message"

Helper macro for creating ranges with proper types. Usage: range(0.0, 1.0) -> tuple of Real values

Reactive computation using window state variables. Usage: @reactive result = windowstate.variables[:var1] + windowstate.variables[:var2] Or use helper: @reactive result = @v(var1) + @v(var2)

Row layout with proper integer types. Usage: @row [100, 200, -1] begin ... end

Simple label widget. Usage: @simple_label name = "text"

Slider widget with bulletproof type handling. Usage: @slider name = initial_value range(low, high)

Variable access helper for reactive expressions. Usage: @state(variable_name) -> gets value from window state

Helper macro for steps with proper types. Usage: step(1.0) -> Real value

Text display widget. Usage: @text name = "content"

Textbox widget macro for text input. Usage: @textbox text_name = "default text" maxlength(256)

Variable assignment - stores in state only. Usage: @var name = value

Conditional rendering macro. Usage: @when condition begin ... end

Window macro for use within @context blocks.

Creates a window with automatic state management. Must be used inside a @context block. The window state persists between frames for stateful widgets.

Usage:

@context begin
    @window "Window Title" begin
        @var message = "Hello"
    end
end