ImGui¶

The ImGui class provides bindings for Dear ImGui, enabling immediate-mode graphical user interfaces.

Synopsis¶

Static Methods¶

Widgets¶

Text¶

ImGui.text(text)

Main¶

ImGui.button(label[, width, height])
ImGui.checkbox(label, state)

Images¶

ImGui.image(image, width, height[, uv0x, uv0y, uv1x, uv1y])

Regular Sliders¶

ImGui.slider_float(label, state[, v_min, v_max, format, flags])

Input with Keyboard¶

ImGui.input_text(label, state[, flags])

Tooltips¶

ImGui.set_tooltip(text)

Item/Widgets Utilities and Query Functions¶

ImGui.is_item_hovered([flags])
ImGui.is_any_item_active()

Inputs Utilities: Mouse¶

ImGui.set_next_frame_want_capture_mouse([value])

ImGuiIO¶

Input Functions¶

ImGui.io_add_key_event(key, down)
ImGui.io_add_mouse_pos_event(x, y)
ImGui.io_add_mouse_button_event(button, down)
ImGui.io_add_mouse_wheel_event(wheel_x, wheel_y)
ImGui.io_add_input_character(c)
ImGui.io_get(key)
ImGui.io_set(key, val)

Static Members¶

ImGui.FltMax

Static Methods¶

Context creation and access¶

`ImGui.create_context()`¶

Creates a new ImGui context associated with the active window and renderer.

Only for offscreen rendering

Each Nutshell window already has an ImGui context.

This function is only needed when you want to render an ImGui interface to an offscreen target.

Returns: userpointer: A pointer to the created ImGui context.

`ImGui.destroy_context(ctx)`¶

Destroys a given ImGui context.

Only for offscreen rendering

This function is only needed to destroy a context created with create_context().

Parameters:

Parameter	Type	Required	Description
`ctx`	`userpointer`	Yes	The ImGui context to destroy.

`ImGui.get_context()`¶

Returns the current active ImGui context pointer.

Returns: userpointer: The current ImGui context.

`ImGui.set_context(ctx)`¶

Sets the current active ImGui context.

Window activation

When you activate a window with window.activate(), the ImGui context is automatically switched!

Parameters:

Parameter	Type	Required	Description
`ctx`	`userpointer`	Yes	The ImGui context to activate.

Main¶

`ImGui.new_frame()`¶

Starts a new Dear ImGui frame.

Only for offscreen rendering

Each Nutshell window already has an ImGui frame started.

This function is only needed when you want to render an ImGui interface to an offscreen target.

`ImGui.render()`¶

Finalizes the current Dear ImGui frame and submits draw data to the render queue.

Only for offscreen rendering

Each Nutshell window already has an automatic rendering pass running at the end of each Nutshell frame.

This function is only needed when you want to render an ImGui interface to an offscreen target.

Demo, Debug, Information¶

`ImGui.show_demo_window([state])`¶

Display the official Dear ImGui demo window showcasing most features and widgets.

Parameters:

Parameter	Type	Required	Description
`state`	`table`	No	State table containing an `open` boolean field.

Windows¶

`ImGui.begin(title[, state[, flags]])`¶

Starts a new ImGui window scope.

Parameters:

Parameter	Type	Required	Description
`title`	`string`	Yes	The window title.
`state`	`table`	No	A state table containing an `open` boolean field.
`flags`	`int`	No	Window flags. Default: `0`.

Returns: bool: true if the window is open and visible.

`ImGui.end()`¶

Ends the current ImGui window scope. Must be called once for every matching ImGui.begin() that returned true.

Other layout functions¶

`ImGui.separator()`¶

Adds a horizontal (or vertical inside horizontal layout mode) separator line.

`ImGui.same_line([offset_from_start_x[, spacing]])`¶

Places the next control on the same horizontal line as the previous item.

Parameters:

Parameter	Type	Required	Description
`offset_from_start_x`	`float`	No	X position offset from start. Default: `0`.
`spacing`	`float`	No	Spacing width. Default: `-1.0`.

Widgets¶

Text¶

`ImGui.text(text)`¶

Renders plain, unformatted text.

Parameters:

Parameter	Type	Required	Description
`text`	`string`	Yes	Text string to render.

Main¶

`ImGui.button(label[, width, height])`¶

Renders a button with optional explicit dimensions.

Parameters:

Parameter	Type	Required	Description
`label`	`string`	Yes	Text label displayed on the button.
`width`	`float`	No	Explicit button width. Default: `0` (auto).
`height`	`float`	No	Explicit button height. Default: `0` (auto).

Returns: bool: true if the button was clicked during the current frame.

`ImGui.checkbox(label, state)`¶

Renders a checkbox linked to a state table.

Parameters:

Parameter	Type	Required	Description
`label`	`string`	Yes	Checkbox label.
`state`	`table`	Yes	State table containing a `value` boolean field.

Returns: bool: true if the value changed during the current frame.

Images¶

`ImGui.image(image, width, height[, uv0x, uv0y, uv1x, uv1y])`¶

Renders an image widget.

Parameters:

Parameter	Type	Required	Description
`image`	`instance`	Yes	The Image instance to render.
`width`	`float`	Yes	Display width.
`height`	`float`	Yes	Display height.
`uv0x`	`float`	No	UV coordinates top-left X. Default: `0`.
`uv0y`	`float`	No	UV coordinates top-left Y. Default: `0`.
`uv1x`	`float`	No	UV coordinates bottom-right X. Default: `1`.
`uv1y`	`float`	No	UV coordinates bottom-right Y. Default: `1`.

Regular Sliders¶

`ImGui.slider_float(label, state[, v_min, v_max, format, flags])`¶

Renders a floating-point slider control linked to a state table.

Parameters:

Parameter	Type	Required	Description
`label`	`string`	Yes	Slider label.
`state`	`table`	Yes	State table containing a `value` float field.
`v_min`	`float`	No	Minimum value boundary. Default: `0.0`.
`v_max`	`float`	No	Maximum value boundary. Default: `1.0`.
`format`	`string`	No	Display format string. Default: `"%.3f"`.
`flags`	`int`	No	Slider flags. Default: `0`.

Returns: bool: true if the slider value was modified.

Input with Keyboard¶

`ImGui.input_text(label, state[, flags])`¶

Renders an interactive text input field.

Parameters:

Parameter	Type	Required	Description
`label`	`string`	Yes	Input field label.
`state`	`table`	Yes	State table containing a `text` string field.
`flags`	`int`	No	Input text flags. Default: `0`.

Returns: bool: true if the text content was modified.

Color Editor/Picker¶

`ImGui.color_edit3(label, state)`¶

Renders an RGB color picker/editor linked to a state table.

Parameters:

Parameter	Type	Required	Description
`label`	`string`	Yes	Color editor label.
`state`	`table`	Yes	State table containing `r`, `g`, and `b` float fields.

Returns: bool: true if any color component was modified.

`ImGui.color_edit4(label, state)`¶

Renders an RGBA color picker/editor linked to a state table.

Parameters:

Parameter	Type	Required	Description
`label`	`string`	Yes	Color editor label.
`state`	`table`	Yes	State table containing `r`, `g`, `b` and `a` float fields.

Returns: bool: true if any color component was modified.

Tooltips¶

`ImGui.set_tooltip(text)`¶

Sets a text-only tooltip for the previously hovered item.

Parameters:

Parameter	Type	Required	Description
`text`	`string`	Yes	Tooltip text content.

Item/Widgets Utilities and Query Functions¶

`ImGui.is_item_hovered([flags])`¶

Checks whether the last rendered widget item is hovered.

Parameters:

Parameter	Type	Required	Description
`flags`	`int`	No	Hovered flags. Default: `0`.

Returns: bool: true if the item is hovered.

`ImGui.is_any_item_active()`¶

Checks whether any ImGui item is currently active.

Returns: bool: true if an item is active.

Inputs Utilities: Mouse¶

`ImGui.set_next_frame_want_capture_mouse([value])`¶

Overrides the io.WantCaptureMouse flag for the next frame.

Parameters:

Parameter	Type	Required	Description
`value`	`bool`	No	Capture mouse flag state. Default: `false`.

ImGuiIO¶

Input Functions¶

`ImGui.io_add_key_event(key, down)`¶

Queues a key down or up event.

Parameters:

Parameter	Type	Required	Description
`key`	`int`	Yes	Key code.
`down`	`bool`	Yes	`true` if key is pressed down, `false` otherwise.

`ImGui.io_add_mouse_pos_event(x, y)`¶

Queues a mouse position update.

Parameters:

Parameter	Type	Required	Description
`x`	`float`	Yes	Mouse X coordinate.
`y`	`float`	Yes	Mouse Y coordinate.

`ImGui.io_add_mouse_button_event(button, down)`¶

Queues a mouse button state change.

Parameters:

Parameter	Type	Required	Description
`button`	`int`	Yes	Mouse button index (e.g., `0` for left click).
`down`	`bool`	Yes	`true` if pressed, `false` if released.

`ImGui.io_add_mouse_wheel_event(wheel_x, wheel_y)`¶

Queues a mouse wheel scroll update.

Parameters:

Parameter	Type	Required	Description
`wheel_x`	`float`	Yes	Horizontal scroll amount.
`wheel_y`	`float`	Yes	Vertical scroll amount.

`ImGui.io_add_input_character(c)`¶

Queues a new character input event.

Parameters:

Parameter	Type	Required	Description
`c`	`int`	Yes	Character code point.

`ImGui.io_get(key)`¶

Reads a configuration or state value from the ImGui IO structure.

Parameters:

Parameter	Type	Required	Description
`key`	`string`	Yes	IO property name (e.g., `"want_capture_mouse"`).

Returns: mixed: The value of the IO property.

`ImGui.io_set(key, val)`¶

Sets a configuration or state value in the ImGui IO structure.

Parameters:

Parameter	Type	Required	Description
`key`	`string`	Yes	IO property name.
`val`	`mixed`	Yes	Value to assign.

Static Members¶

`ImGui.FltMax`¶

Type: float

The maximum positive finite value for a 32-bit float.

Examples¶

local window = Window.active()
window.set_title("ImGui Demo")

local acorn = Image("res://assets/Images/acorn.png")
local scaleState = { value = 1.0 }
local rotation = 0.0

local helloTarget = Image.create_render_target(Canvas.width() / 1.5, Canvas.height() / 1.5)
local helloCtx = null

function update(dt) {
    rotation = (rotation + dt * 45.0) % 360.0
}

function draw(dt) {
    if (helloCtx == null) {
        helloCtx = ImGui.create_context()
    }

    local mainWantsMouse = ImGui.io_get("WantCaptureMouse")

    local globalMouseX = Input.mouse_x()
    local globalMouseY = Input.mouse_y()

    // Offscreen rendering
    local targetX = 10.0
    local targetY = 10.0
    Canvas.push_render_target(helloTarget)
    // fmt: off
    Canvas.clear()
        Canvas.fill_rect(0, 0, helloTarget.width(), helloTarget.height(), { color = "#0000FF77"})
        ImGui.set_context(helloCtx)

        ImGui.io_set("DisplaySizeX", helloTarget.width())
        ImGui.io_set("DisplaySizeY", helloTarget.height())
        ImGui.io_set("Deltatime", dt)

        // Map mouse coordinates relative to the offscreen target bounds
        local localMouseX = globalMouseX - targetX
        local localMouseY = globalMouseY - targetY

        if (!mainWantsMouse
            && localMouseX >= 0
            && localMouseX < helloTarget.width()
            && localMouseY >= 0
            && localMouseY < helloTarget.height())
        {
            ImGui.io_add_mouse_pos_event(localMouseX, localMouseY)
            ImGui.io_add_mouse_button_event(0, Input.mouse_down(Input.MouseLeft))
        } else {
            ImGui.io_add_mouse_pos_event(-ImGui.FltMax, -ImGui.FltMax)
            ImGui.io_add_mouse_button_event(0, false)
        }

        ImGui.new_frame()
        if (ImGui.begin("Hello there")) {
            ImGui.text("I'm rendered *behind* the acorn!")
        }
        ImGui.end()
        ImGui.render()
    // fmt: on
    Canvas.pop_render_target()

    // Switch back to the main window context
    window.activate()

    // Draw the "Hello there" ImGui window texture first
    helloTarget.draw(targetX, targetY)

    // Draw the acorn over it
    acorn.draw(Canvas.width() / 2, Canvas.height() / 2, {
        scale = scaleState.value,
        angle = rotation,
        centered = true
    })

    // Now use main window's automated context
    if (ImGui.begin("Acorn Controls")) {
        ImGui.text("Manage the acorn properties below:")

        ImGui.slider_float("Scale", scaleState, 0.4, 3.0)
        if (ImGui.is_item_hovered()) {
            ImGui.set_tooltip("Drag to adjust the acorn size smoothly.")
        }

        if (ImGui.button("Reset Scale")) {
            scaleState.value = 1.0
        }

        ImGui.text("Current Scale: " + scaleState.value)
    }
    ImGui.end()
}

Additional example code available here.

ImGui¶

Synopsis¶

Static Methods¶

Context creation and access¶

Main¶

Demo, Debug, Information¶

Windows¶

Other layout functions¶

Widgets¶

Text¶

Main¶

Images¶

Regular Sliders¶

Input with Keyboard¶

Color Editor/Picker¶

Tooltips¶

Item/Widgets Utilities and Query Functions¶

Inputs Utilities: Mouse¶

ImGuiIO¶

Input Functions¶

Static Members¶

Static Methods¶

Context creation and access¶

ImGui.create_context()¶

ImGui.destroy_context(ctx)¶

ImGui.get_context()¶

ImGui.set_context(ctx)¶

Main¶

ImGui.new_frame()¶

ImGui.render()¶

Demo, Debug, Information¶

ImGui.show_demo_window([state])¶

Windows¶

ImGui.begin(title[, state[, flags]])¶

ImGui.end()¶

Other layout functions¶

ImGui.separator()¶

ImGui.same_line([offset_from_start_x[, spacing]])¶

Widgets¶

Text¶

ImGui.text(text)¶

Main¶

ImGui.button(label[, width, height])¶

ImGui.checkbox(label, state)¶

Images¶

ImGui.image(image, width, height[, uv0x, uv0y, uv1x, uv1y])¶

Regular Sliders¶

ImGui.slider_float(label, state[, v_min, v_max, format, flags])¶

Input with Keyboard¶

ImGui.input_text(label, state[, flags])¶

Color Editor/Picker¶

ImGui.color_edit3(label, state)¶

ImGui.color_edit4(label, state)¶

Tooltips¶

ImGui.set_tooltip(text)¶

Item/Widgets Utilities and Query Functions¶

ImGui.is_item_hovered([flags])¶

ImGui.is_any_item_active()¶

Inputs Utilities: Mouse¶

ImGui.set_next_frame_want_capture_mouse([value])¶

ImGuiIO¶

Input Functions¶

ImGui.io_add_key_event(key, down)¶

ImGui.io_add_mouse_pos_event(x, y)¶

ImGui.io_add_mouse_button_event(button, down)¶

ImGui.io_add_mouse_wheel_event(wheel_x, wheel_y)¶

ImGui.io_add_input_character(c)¶

ImGui.io_get(key)¶

ImGui.io_set(key, val)¶

Static Members¶

ImGui.FltMax¶

Examples¶

`ImGui.create_context()`¶

`ImGui.destroy_context(ctx)`¶

`ImGui.get_context()`¶

`ImGui.set_context(ctx)`¶

`ImGui.new_frame()`¶

`ImGui.render()`¶

`ImGui.show_demo_window([state])`¶

`ImGui.begin(title[, state[, flags]])`¶

`ImGui.end()`¶

`ImGui.separator()`¶

`ImGui.same_line([offset_from_start_x[, spacing]])`¶

`ImGui.text(text)`¶

`ImGui.button(label[, width, height])`¶

`ImGui.checkbox(label, state)`¶

`ImGui.image(image, width, height[, uv0x, uv0y, uv1x, uv1y])`¶

`ImGui.slider_float(label, state[, v_min, v_max, format, flags])`¶

`ImGui.input_text(label, state[, flags])`¶

`ImGui.color_edit3(label, state)`¶

`ImGui.color_edit4(label, state)`¶

`ImGui.set_tooltip(text)`¶

`ImGui.is_item_hovered([flags])`¶

`ImGui.is_any_item_active()`¶

`ImGui.set_next_frame_want_capture_mouse([value])`¶

`ImGui.io_add_key_event(key, down)`¶

`ImGui.io_add_mouse_pos_event(x, y)`¶

`ImGui.io_add_mouse_button_event(button, down)`¶

`ImGui.io_add_mouse_wheel_event(wheel_x, wheel_y)`¶

`ImGui.io_add_input_character(c)`¶

`ImGui.io_get(key)`¶

`ImGui.io_set(key, val)`¶

`ImGui.FltMax`¶