ui/imguiUtils Reference

Module defined in lua/common/extensions/ui/imguiUtils.lua. Higher-level ImGui widget utilities - dropdowns, key-value tables, recursive tree displays, texture objects, and sampled float displays.

---

Exports

Functions

M.changeUIScale(uiscale)

Change the ImGui UI scale factor.

• Parameters:
  • uiscale - number - Scale multiplier
• Returns: boolean - true on success

M.drawCursorPos(posX, posY)

Draw content at a specific cursor position.

• Parameters:
  • posX - number - X cursor position
  • posY - number - Y cursor position
• Returns: boolean

M.texObj(path)

Create or retrieve a cached texture object from a file path.

• Parameters:
  • path - string - Image file path
• Returns: table - Texture object

M.DropdownItem(label, icon, func, tooltip)

Create a dropdown menu item.

• Parameters:
  • label - string - Item label
  • icon - string|nil - Icon identifier
  • func - function - Click callback
  • tooltip - string|nil - Hover tooltip

M.DropdownSelectableItem(label, active, func, tooltip)

Create a selectable dropdown item with active state.

• Parameters:
  • label - string - Item label
  • active - boolean - Whether currently selected
  • func - function - Click callback
  • tooltip - string|nil - Hover tooltip

M.DropdownButton(label, size, items, icon, horizontal)

Create a dropdown button that opens a popup menu.

• Parameters:
  • label - string - Button label
  • size - ImVec2 - Button size
  • items - table - Array of DropdownItem tables
  • icon - string|nil - Button icon
  • horizontal - boolean|nil - Horizontal layout
• Returns: boolean - true if an item was clicked

M.DropdownSelectable(label, items, icon, iconSize, popupWidth, onChangeFunc, tooltip, itemsRMB)

Create a selectable dropdown with icon and popup.

• Parameters:
  • label - string - Display label
  • items - table - Selectable items
  • icon - string|nil - Icon
  • iconSize - number|nil - Icon size
  • popupWidth - number|nil - Popup width
  • onChangeFunc - function|nil - Selection change callback
  • tooltip - string|nil - Tooltip
  • itemsRMB - table|nil - Right-click menu items
• Returns: boolean

M.DropdownSelect(label, size, selectedItem, items, horizontal, excludeCurrent)

Dropdown select widget (combo box replacement).

• Parameters:
  • label - string - Label
  • size - ImVec2 - Widget size
  • selectedItem - string - Currently selected item
  • items - table - Available items
  • horizontal - boolean|nil - Horizontal layout
  • excludeCurrent - boolean|nil - Hide current selection from list
• Returns: boolean

M.IsWindowHovered(windowPos, windowSize)

Check if an ImGui window at the given position/size is hovered.

• Parameters:
  • windowPos - ImVec2 - Window position
  • windowSize - ImVec2 - Window size
• Returns: boolean

M.displayKeyValues(tbl)

Display a Lua table as key/value pairs in ImGui.

• Parameters:
  • tbl - table - Data to display

M.CreateKeyValApp(window, section, tbl, callback)

Create a simple key/value display app from a Lua table.

• Parameters:
  • window - string - Window name
  • section - string - Section name
  • tbl - table - Data table
  • callback - function|nil - Edit callback

M.keyValueTable(data, fullpath, highlightCallback, itemCallback)

Render a key-value table widget.

• Parameters:
  • data - table - Data to display
  • fullpath - string - Current path prefix
  • highlightCallback - function|nil - Row highlight callback
  • itemCallback - function|nil - Item interaction callback

M.addRecursiveTreeTable(data, fullpath, noColumns, highlightCallback, itemCallback)

Render a recursive tree table widget for nested data.

• Parameters:
  • data - table - Nested data to display
  • fullpath - string - Path prefix
  • noColumns - boolean|nil - Disable column headers
  • highlightCallback - function|nil - Highlight callback
  • itemCallback - function|nil - Item callback

M.cell(a, b)

Render a two-column table cell.

• Parameters:
  • a - string - Left column value
  • b - string - Right column value

M.CreateSampleFloatDisplay(sampleTimeInSeconds, startingValue, precision)

Create a sampled float display object that averages values over time.

• Parameters:
  • sampleTimeInSeconds - number - Sample window duration
  • startingValue - number - Initial display value
  • precision - number|nil - Decimal precision
• Returns: table - Display object with :update(value) and :display() methods

M.SampleFloatDisplay(id, value, sampleTimeInSeconds, precision)

Stateless sampled float display - auto-creates/updates a display by ID.

• Parameters:
  • id - string - Unique identifier
  • value - number - Current value
  • sampleTimeInSeconds - number - Sample window
  • precision - number|nil - Decimal precision

Variables

M.sampleFloatDisplayState

• Type: table
• Description: Internal state storage for SampleFloatDisplay instances (keyed by ID)

Internal Notes

• Uses FFI for ImGui pointer types
• newValueSampler creates time-windowed value averaging objects
• pointToLine helper computes point-to-line distance for UI interaction
• Sorted key iteration via getTableKeysSorted
• Recursive tree rendering handles arbitrary nesting depth