UI Examples

This page contains examples for creating UI for your mod using the built-in ImGui library.

Everything you need to know about Dear ImGui can be found here and here.

You can also take a look at FellowImGui. It is a free online tool to create ImGui layouts with an easy to use interface. It also generates Lua code for you. Feel free to come on this Discord channel if you have issues or feedback to share.

Any ImGui code needs to be run from inside the onDraw callback.

Basic Window

ImGui.SetNextWindowPos(100, 500, ImGuiCond.FirstUseEver) -- set window position x, y
ImGui.SetNextWindowSize(300, 600, ImGuiCond.Appearing) -- set window size w, h

if ImGui.Begin("Unique Window Name") then
    ImGui.Text("Hello World")
    -- more window contents here
end
ImGui.End()

Modal/Popup Window

if ImGui.Button("Pop Button", 120, 0) then
      ImGui.OpenPopup("Delete?")
end

if ImGui.BeginPopupModal("Delete?", true, ImGuiWindowFlags.AlwaysAutoResize) then
    ImGui.Text("This is a popup")
    
    if ImGui.Button("Close") then ImGui.CloseCurrentPopup() end
    ImGui.EndPopup()
end

Combo Box with Selectables

local DropdownOptions = {"1", "2", "3", "4", "5"}
local DropdownSelected = "1"

if ImGui.BeginCombo("##My Combo Box", DropdownSelected) then -- Remove the ## if you'd like for the title to display above combo box

    for _, option in ipairs(DropdownOptions) do

        if ImGui.Selectable(option, (option == DropdownSelected)) then
            DropdownSelected = option
            ImGui.SetItemDefaultFocus()
        end

    end

    ImGui.EndCombo()
end

Checkbox

MyMod.myValue = ImGui.Checkbox("Check me", MyMod.myValue)

Button

if ImGui.Button("Click Me!", 100, 20) then -- Label, width, height - Use -1 as width for button to span available horizontal space
    -- do stuff here when button is clicked
end

local pressed

registerForEvent("onUpdate", function()
    if pressed then
        print("You pressed me!")
    end
end)

registerForEvent("onDraw", function()
    pressed = ImGui.Button("Click me I'm a Sexy Button", 250, 25)
end)

Tooltip

Default tooltip on a button.

local pressed = ImGui.Button("button text")
if ImGui.IsItemHovered() then
  ImGui.SetTooltip("tooltip text")
else
  ImGui.SetTooltip(nil)
end

To customize the tooltip window use BeginTooltip and EndTooltip.

local pressed = ImGui.Button("button text")
if ImGui.IsItemHovered() then
  ImGui.BeginTooltip()
  ImGui.PushTextWrapPos(50)
  ImGui.TextWrapped("tooltip text")
  ImGui.EndTooltip()
else
  ImGui.SetTooltip(nil)
end

Multi-column layout

Creating a multi-column layout is a pain in the ass, but you can go about it like this:

ImGui.BeginChild("Column 1", 300, 400) -- this will not display a label
    ImGui.Text('Column 1')
ImGui.EndChild()

ImGui.BeginChild("Column 2", 300, 400) -- this will not display a label
    ImGui.Text('Column 2')
ImGui.EndChild()

You can probably use dynamic dimensions somehow. If you find out, please update this guide.