Im

Immediate mode UI system for Ceramic inspired by Dear ImGui.

Im provides a stateless, code-driven UI API that creates and manages UI elements on-the-fly. Unlike traditional retained-mode UI systems where you create and maintain UI objects, Im allows you to declare UI in a procedural way:

Im.begin();

if (Im.button("Click me!")) {
    trace("Button clicked!");
}

Im.textField("Name", namePointer);
Im.slider("Volume", volumePointer, 0, 100);

Im.end();

Key features:

• Immediate mode paradigm - UI is rebuilt every frame
• Automatic layout with rows and columns
• Built-in controls: buttons, text fields, sliders, checkboxes, etc.
• Window management with docking and tabs
• Theme support with runtime customization
• Cross-platform compatibility through Ceramic

The system uses pointers (functions that get/set values) to bind controls to data, allowing the UI to automatically reflect and modify application state.

Static Members #

Creates a directory picker field.

Shows a text field with a browse button that opens a directory selection dialog. Only available when dialogs plugin is enabled.

Creates a file picker field.

Shows a text field with a browse button that opens a file selection dialog. Only available when dialogs plugin is enabled.

Initializes the Im system if not already initialized.

This method ensures that:

• The global context view exists
• A default theme is created
• The Im system is ready for use

This is automatically called by most Im methods, but can be called manually if early initialization is needed.

Extracts the ID portion from a window key.

Window keys can contain both an ID and a title. This method extracts just the ID portion, which is used for window lookup and persistence.

Currently returns the key as-is, but may parse complex keys in the future (e.g., "id###title" format).

Extracts the title portion from a window key.

Window keys can contain both an ID and a title. This method extracts just the title portion, which is displayed in the window header.

Currently returns the key as-is, but may parse complex keys in the future (e.g., "id###title" format).

Sets the rendering depth for the entire Im UI layer.

This affects the z-order of all Im windows and controls relative to other visuals in the scene. Higher values render on top.

Must be called before any windows are created to take effect.

Gets a window by its key.

Returns the Window instance if it exists, or null if no window with the given key has been created yet.

This is useful for checking if a window is open or accessing its properties from outside the begin/end block.

Return true if any window is hitten given point.

Returns true if there is a currently focused field that uses the given scan code

Returns true if there is a currently focused field that uses the given key code

Checks if any Command (Mac) or Control (Windows/Linux) key is being used.

This is useful for detecting platform-specific modifier keys for keyboard shortcuts. Returns true if any focused field is using these keys.

Checks if any Shift key is being used.

Returns true if any focused field is using either the left or right Shift key. Useful for detecting shift-modified shortcuts.

Begins an Im window with separate key and title.

This starts the declaration of a new window or continues an existing one. All Im controls called after begin() will be added to this window until end() is called.

The key is used to identify the window across frames, while the title is displayed in the window header.

Begins a tab bar container.

Creates a horizontal tab bar where each tab() call adds a new tab. The selected tab is controlled by the StringPointer parameter.

Must be followed by one or more tab() calls and ended with endTabs().

Ends a tab bar container.

Must be called after beginTabs() and all tab() declarations. Will assert if called without a matching beginTabs() or if no tabs were declared.

Declares a tab in the current tab bar.

Uses the key as both the tab ID and display title. Must be called between beginTabs() and endTabs().

Begins a row layout for subsequent controls.

Controls added after beginRow() will be arranged horizontally in a single row until endRow() is called. The width of each control is determined by its flex value.

Nested rows are not supported - calling beginRow() while already in a row will trigger an assertion.

Im.beginRow();
Im.button("Left");    // Default flex=1
Im.flex(2);
Im.button("Middle");  // Takes up twice the space
Im.button("Right");   // Default flex=1
Im.endRow();

Ends the current row layout.

Must be called after beginRow() to complete the row. Resets the flex value to default (1) for subsequent controls.

Begins tracking changes to control values.

After calling this method, any changes to control values (text fields, sliders, checkboxes, etc.) will be tracked. Call endChangeCheck() to check if any values changed.

Change checks can be nested - each begin/end pair tracks changes independently.

Im.beginChangeCheck();
Im.textField("Name", namePointer);
Im.slider("Volume", volumePointer, 0, 100);
if (Im.endChangeCheck()) {
    trace("Settings changed!");
    saveSettings();
}

Ends change tracking and returns if any changes occurred.

Must be called after beginChangeCheck(). Returns true if any control values changed between the begin/end calls.

Sets the label position for subsequent controls.

Controls where labels appear relative to their input fields:

• LEFT: Label to the left of the field
• RIGHT: Label to the right of the field
• TOP: Label above the field
• BOTTOM: Label below the field

Sets the width of labels for subsequent controls.

Can be specified as:

• Absolute pixels: positive values
• Percentage: use ViewSize.percent()
• Auto-size: use ViewSize.auto()

Sets the text alignment for subsequent text controls.

Affects text(), labels, and other text-based controls.

Sets whether subsequent controls should be disabled.

Disabled controls are rendered with reduced opacity and don't respond to user interaction.

Sets the flex value for the next control in a row.

When in a row layout (between beginRow/endRow), flex determines the relative width of controls. A control with flex=2 will be twice as wide as a control with flex=1.

Only applies to the next control added.

Resets the text color to the default theme color.

Removes any custom text color override, allowing subsequent text to use the theme's default text color.

Resets the background color to the default theme color.

Removes any custom background color override, allowing subsequent controls to use the theme's default background color.

Resets the tint color to default (no tint).

Removes any color tinting applied to subsequent controls, returning them to their original theme colors.

Sets whether subsequent text should be rendered in bold.

Affects text(), labels, and other text-based controls. The actual bold rendering depends on the font's bold variant being available.

Sets the asset manager to use for loading images and other resources.

When set, Im will use this asset manager for loading images referenced by asset ID. If not set, Im will use the default asset manager.

Sets the theme to use for subsequent controls.

The theme controls colors, fonts, and other visual properties of Im controls. Pass null to revert to the default theme.

Changes to the theme affect all controls created after this call within the current frame.

Sets the position of the current window.

Positions the window at the specified coordinates with optional anchor points. The window becomes non-movable when positioned manually.

Must be called between begin() and end().

Sets the scrollbar visibility for the current window.

Controls when scrollbars appear in the window:

• AUTO: Show when content overflows
• ALWAYS: Always visible
• NEVER: Never show scrollbars

Must be called between begin() and end().

Requests focus for the current window.

The window will be brought to front and receive input focus. Must be called between begin() and end().

Marks the current window as expanded.

Expanded windows start maximized and cannot be collapsed. Must be called between begin() and end().

Sets whether the current window should display a header.

The header contains the window title and optional close button. Windows without headers cannot be dragged by the title bar.

Makes the window display with a modal overlay.

An overlay darkens the background and blocks interaction with other windows. Returns true if the overlay (outside the window) was clicked this frame.

Sets the alignment of the window title in the header.

Only applies to windows with headers enabled.

Makes the window closable with a close button.

Adds a close button to the window header. If an isOpen pointer is provided, it will be set to false when the window is closed.

Creates a list view with standard-sized items.

Displays a scrollable list of items with optional features:

• Selection tracking through the selected pointer
• Drag-and-drop sorting
• Item locking/unlocking
• Item deletion
• Item duplication

Creates a checkbox control.

Displays a checkbox that toggles a boolean value. The checkbox shows a checkmark when true and is empty when false.

Creates a color picker field.

Shows a color preview that opens a color picker dialog when clicked. The color value is stored as an integer in ARGB format.

Creates a text input field.

Supports single-line or multi-line text editing with optional placeholder text and autocomplete suggestions.

Creates an integer input field.

Allows numeric input with optional min/max constraints. Non-numeric input is automatically filtered out.

Creates a float input field.

Allows decimal numeric input with optional min/max constraints and rounding precision.

Creates an integer slider control.

Provides a draggable slider for selecting integer values within a specified range. More intuitive than text input for ranges.

Creates a float slider control.

Provides a draggable slider for selecting float values within a specified range with configurable precision.

Displays a custom visual element.

Embeds any Ceramic Visual object within the Im layout. The visual can be scaled to fit within constraints or displayed at its natural size.

Displays an image from a texture tile.

Shows a TextureTile (sub-region of a texture) within the Im layout.

Adds a standard margin space.

Inserts negative spacing to reduce the gap between form items. Useful for tightening layouts.

Adds vertical spacing.

Inserts empty vertical space between controls. Use negative values to reduce spacing. Default uses theme spacing.

Adds a horizontal line separator.

Draws a horizontal line to visually separate sections. The line color is determined by the current theme.

Creates a button with explicit enabled state.

Sets the font point size for subsequent text.

Affects text(), labels, and all text-based controls until changed again or the frame ends.

Sets the pre-rendered font size for bitmap fonts.

When using bitmap fonts, this specifies which pre-rendered size to use. Set to -1 to use automatic size selection.

Displays static text.

Renders a text label using the current theme settings. The text is not selectable or editable.

Ends the current window declaration.

Must be called after begin() and all window content has been added. This finalizes the window layout and renders all controls.

Will assert if called without a matching begin().

Gets the currently focused Im window.

Returns the Window that currently has input focus, or null if no Im window is focused. Useful for checking if the Im UI is capturing input.

Allows events from a specific entity owner.

When Im windows are focused, they block events from other entities by default. Use this to whitelist specific entities whose events should still be processed. The entity is automatically removed from the allowed list when destroyed.

Removes an entity from the allowed owners list.

Events from this entity will be blocked again when Im windows are focused. Also removes the destroy listener if the entity still exists.

Shows a confirmation dialog (synchronous version).

Displays a modal dialog with Yes/No buttons. The dialog can be canceled by clicking outside if cancelable is true.

This version returns immediately with the current status. Use the returned ConfirmStatus to check if the user made a choice.

Shows an information dialog (synchronous version).

Displays a modal dialog with an OK button. The dialog can be canceled by clicking outside if cancelable is true.

This version returns immediately with the current status. Use the returned InfoStatus to check if the user clicked OK.

Shows a text input dialog (synchronous version).

Displays a modal dialog with a text field and OK/Cancel buttons. The dialog can be canceled by clicking outside if cancelable is true.

This version returns immediately with the current status. The text value is read from and written to the provided StringPointer.

Shows a multiple choice dialog (synchronous version).

Displays a modal dialog with multiple buttons for each choice. The dialog can be canceled by clicking outside if cancelable is true.

This version returns immediately with the current status. Use the returned ChoiceStatus to check which choice was selected.

Generates a unique handle for storing values.

Handles provide a way to store values that persist across frames without explicitly creating pointers. The handle is unique per source location and occurrence within a frame.

Used internally by the pointer macros (Im.bool(), Im.int(), etc.) to create implicit storage locations.

Private Members #