lovr-ui2d

lovr-ui2d

An immediate mode GUI library for the LÖVR and LÖVE frameworks.

This is the sister project of lovr-ui (a VR GUI library for lovr). Both projects borrow concepts from the outstanding Dear ImGui library and are inspired by microui, trying to be simple and minimal.

This was formerly 2 different branches, one for each framework. It's now a unified codebase since lovr and love have a very similar API. It has zero depedencies and it is pure Lua, meaning this is not bindings to a "foreign" library (which usually require a specific version of said library to work).

https://github.com/immortalx74/lovr-ui2d/assets/29693328/3b1e15cc-948f-401f-a236-ee63c44e07ea

How to use:

See main.lua for minimal and demo implementations. Below is the complete API documentation but some things will make more sense by examining the examples.

Widgets:

• Button
• ImageButton
• TextBox
• ListBox
• SliderInt
• SliderFloat
• Label
• CheckBox
• ToggleButton
• RadioButton
• TabBar
• Dummy
• ProgressBar
• CustomWidget
• Modal window
• Separator

API:

---

UI2D.Button(name, width, height, tooltip) |Argument|Type|Description |:---|:---|:---| |name|string|button's text |width [opt]|number|button width in pixels |height [opt]|number|button height in pixels |tooltip [opt]|string|tooltip text

Returns: boolean, true when clicked.
NOTE: if no width and/or height are provided, the button size will be auto-calculated based on text. Otherwise, it will be set to width X height (with the text centered) or ignored if that size doesn't fit the text.

---

UI2D.ImageButton(texture, width, height, text, tooltip) |Argument|Type|Description |:---|:---|:---| |texture|texture/image|texture(lovr) or image(love) |width|number|image width in pixels |height|number|image height in pixels |text [opt]|string|optional text |tooltip [opt]|string|tooltip text

Returns: boolean , true when clicked.

---

UI2D.CustomWidget(name, width, height, tooltip) |Argument|Type|Description |:---|:---|:---| |name|string|custom widget name |width|number|width in pixels |height|number|height in pixels |tooltip [opt]|string|tooltip text

Returns: Pass(lovr) or Canvas(love), boolean, boolean, boolean, boolean, number, number, number, number [1] Pass object(lovr) or Canvas(love), [2] clicked, [3] down, [4] released, [5] hovered, [6] mouse X, [7] mouse Y, [8] wheel X, [9] wheel Y
NOTE: General purpose widget for custom drawing/interaction. The returned Pass(lovr) or Canvas(love) can be used to do regular draw-commands. X and Y are the local 2D coordinates of the pointer (0,0 is top,left)

---

UI2D.TextBox(name, num_visible_chars, text, tooltip) |Argument|Type|Description |:---|:---|:---| |name|string|textbox name |num_visible_chars|number|number of visible characters |text|string|text |tooltip [opt]|string|tooltip text

Returns: string, boolean [1] text, [2] finished editing.
NOTE: Always assign back to your string variable e.g. mytext = UI2D.TextBox("My textbox, 10, mytext). To do validation on the edited text, check the finished editing return value.

---

UI2D.ListBox(name, num_visible_rows, num_visible_chars, collection, selected, multi_select, tooltip) |Argument|Type|Description |:---|:---|:---| |name|string|listbox name |num_visible_rows|number|number of visible rows |num_visible_chars|number|number of visible characters on each row |collection|table|table of strings |selected [opt]|number or string|selected item index (in case it's a string, selects the 1st occurence of the item that matches the string) |multi_select [opt]|boolean|whether multi-select should be enabled |tooltip [opt]|string|tooltip text

Returns: boolean, number, table, [1] true when clicked, [2] selected item index, [3] table of selected item indices (if multi_select is true)
NOTE: The UI2D.ListBoxSetSelected helper can be used to select item(s) programmatically.

---

UI2D.SliderInt(name, v, v_min, v_max, width, tooltip) |Argument|Type|Description |:---|:---|:---| |name|string|slider text |v|number|initial value |v_min|number|minimum value |v_max|number|maximum value |width [opt]|number|total width in pixels of the slider, including it's text |tooltip [opt]|string|tooltip text

Returns: number, boolean, [1] current value, [2] true when released
NOTE: Always assign back to your slider-value, e.g. myval = UI2D.SliderInt("my slider", myval, 0, 100) If width is provided, it will be taken into account only if it exceeds the width of text, otherwise it will be ignored.

---

UI2D.SliderFloat(name, v, v_min, v_max, width, num_decimals, tooltip) |Argument|Type|Description |:---|:---|:---| |name|string|slider text |v|number|initial value |v_min|number|minimum value |v_max|number|maximum value |width [opt]|number|total width in pixels of the slider, including it's text |num_decimals [opt]|number|number of decimals to display |tooltip [opt]|string|tooltip text

Returns: number, boolean, [1] current value, [2] true when released
NOTE: Always assign back to your slider-value, e.g. myval = UI2D.SliderFloat("my slider", myval, 0, 100) If width is provided, it will be taken into account only if it exceeds the width of text, otherwise it will be ignored. If no num_decimals is provided, it defaults to 2.

---

UI2D.Label(text) |Argument|Type|Description |:---|:---|:---| |text|string|label text |compact [opt]|boolean|ignore vertical margin

Returns: nothing

---

UI2D.ProgressBar(progress, width, tooltip) |Argument|Type|Description |:---|:---|:---| |progress|number|progress percentage |width [opt]|number|width in pixels |tooltip [opt]|string|tooltip text

Returns: nothing
NOTE: Default width is 300 pixels

---

UI2D.Separator() |Argument|Type|Description |:---|:---|:---| |none||

Returns: nothing
NOTE: Horizontal Separator

---

UI2D.CheckBox(text, checked, tooltip) |Argument|Type|Description |:---|:---|:---| |text|string|checkbox text |checked|boolean|state |tooltip [opt]|string|tooltip text

Returns: boolean, true when clicked
NOTE: To set the state use this idiom: if UI2D.CheckBox("My checkbox", my_state) then my_state = not my_state end

---

UI2D.ToggleButton(text, checked, tooltip) |Argument|Type|Description |:---|:---|:---| |text|string|toggle button text |checked|boolean|state |tooltip [opt]|string|tooltip text

Returns: boolean, true when clicked
NOTE: To set the state use this idiom: if UI2D.ToggleButton("My toggle button", my_state) then my_state = not my_state end

---

UI2D.RadioButton(text, checked, tooltip) |Argument|Type|Description |:---|:---|:---| |text|string|radiobutton text |checked|boolean|state |tooltip [opt]|string|tooltip text

Returns: boolean, true when clicked
NOTE: To set the state on a group of RadioButtons use this idiom: if UI2D.RadioButton("Radio1", rb_group_idx == 1) then rb_group_idx = 1 end if UI2D.RadioButton("Radio2", rb_group_idx == 2) then rb_group_idx = 2 end -- etc...

---

UI2D.TabBar(name, tabs, idx, tooltip) |Argument|Type|Description |:---|:---|:---| |name|string|TabBar name |tabs|table|a table of strings |idx|number|initial active tab index |tooltip [opt]|string|tooltip text

Returns: boolean, number, [1] true when clicked, [2] the selected tab index

---

UI2D.Dummy(width, height) |Argument|Type|Description |:---|:---|:---| |width|number|width |height|number|height

Returns: nothing
NOTE: This is an invisible widget useful only to "push" other widgets' positions or to leave a desired gap.

---

UI2D.Begin(name, x, y, is_modal) |Argument|Type|Description |:---|:---|:---| |name|string|window title |x|number|window X position |y|number|window Y position |is_modal [opt]|boolean|is this a modal window

Returns: nothing
NOTE: Starts a new window. Every widget call after this function will belong to this window, until UI2D.End() is called. If this is set as a modal window (by passing true to the last argument) you should always call UI2D.EndModalWindow before closing it physically.

---

UI2D.End(main_pass(lovr) or nothing(love)) |Argument|Type|Description |:---|:---|:---| |main_pass|Pass|the main Pass object(only for lovr)

Returns: nothing
NOTE: Ends the current window.

---

UI2D.SameLine() |Argument|Type|Description |:---|:---|:---| |none||

Returns: nothing
NOTE: Places the next widget side-to-side with the last one, instead of bellow

---

UI2D.GetWindowSize(name) |Argument|Type|Description |:---|:---|:---| |name|number|window name

Returns: number, number, [1] window width, [2] window height
NOTE: If no window with this name was found, return type is nil

---

UI2D.Init(type, size) |Argument|Type|Description |:---|:---|:---| |type|string|which framework to use (valid values: "lovr", "love") |size [opt]|number|font size

Returns: nothing
NOTE: Initializes the library and should be called on lovr/love.load(). Font size dictates the general size of the UI. Default is 14

---

UI2D.InputInfo() |Argument|Type|Description |:---|:---|:---| |none||

Returns: nothing
NOTE: Should be called on lovr/love.update()

---

UI2D.RenderFrame(main_pass(only for lovr)) |Argument|Type|Description |:---|:---|:---| |main_pass|Pass|the main Pass object(lovr).

Returns: table of ui passes(lovr) or nothing(love)
NOTE: Renders the UI. Should be called in lovr/love.draw(). (If you're using lovr see the examples on how to handle the passes returned from this call.)

---

UI2D.OverrideColor(col_name, color) |Argument|Type|Description |:---|:---|:---| |col_name|string|color name |color|table|color value in table form (r, g, b, a)

Returns: nothing
NOTE: Helper to override a color value.

---

UI2D.SetColorTheme(theme, copy_from) |Argument|Type|Description |:---|:---|:---| |theme|string or table|color name or table with names of colors |copy_from [opt]|string|color-theme to copy values from

Returns: nothing
NOTE: Sets the color-theme to one of the built-in ones ("dark", "light") if the passed argument is a string. Also accepts a table of colors. If the passed table doesn't contain all of the keys, the rest of them will be copied from the built-in theme of the copy_from argument.

---

UI2D.CloseModalWindow() |Argument|Type|Description |:---|:---|:---| |none||

Returns: nothing
NOTE: Closes a modal window

---

UI2D.KeyPressed(key, repeating) |Argument|Type|Description |:---|:---|:---| |key|string|key name |repeating|boolean|if the key is repeating instead of an instant press.

Returns: nothing
NOTE: Should be called on lovr/love.keypressed() callback.

---

UI2D.TextInput(text) |Argument|Type|Description |:---|:---|:---| |text|string|character from a textinput event.

Returns: nothing
NOTE: Should be called on lovr/love.textinput() callback.

---

UI2D.KeyReleased() |Argument|Type|Description |:---|:---|:---| |none||

Returns: nothing
NOTE: Should be called on lovr/love.keyreleased() callback.

---

UI2D.WheelMoved(x, y) |Argument|Type|Description |:---|:---|:---| |x|number|wheel X. |y|number|wheel Y.

Returns: nothing
NOTE: Should be called on lovr/love.wheelmoved() callback.

---

UI2D.HasMouse() |Argument|Type|Description |:---|:---|:---| |none||

Returns: nothing
NOTE: Whether the mouse-pointer hovers a UI2D window.

---

UI2D.SetWindowPosition(name, x, y) |Argument|Type|Description |:---|:---|:---| |name|string|name of the window |x|number|X position |y|number|Y position

Returns: boolean, true if the window was found
NOTE: Sets a window's position programmatically.

---

UI2D.GetColorTheme() |Argument|Type|Description |:---|:---|:---| |none||

Returns: string, theme name
NOTE: Gets the current color-theme

---

UI2D.ResetColor(col_name) |Argument|Type|Description |:---|:---|:---| |col_name|string|color name

Returns: nothing
NOTE: Resets a color to its default value

---

UI2D.SetFontSize(size) |Argument|Type|Description |:---|:---|:---| |size|number|font size

Returns: nothing
NOTE: Sets the font size

---

UI2D.GetFontSize() |Argument|Type|Description |:---|:---|:---| |none||

Returns: number, font size
NOTE: Gets the current font size

---

UI2D.HasTextInput() |Argument|Type|Description |:---|:---|:---| |none||

Returns: boolean, true if a textbox has focus
NOTE: Gets whether the text of a textbox is currently being edited

---

UI2D.IsModalOpen() |Argument|Type|Description |:---|:---|:---| |none||

Returns: boolean, true if a modal window is currently open
NOTE: Gets whether a modal window is currently open

---

UI2D.EndModalWindow() |Argument|Type|Description |:---|:---|:---| |none||

Returns: nothing
NOTE: Informs UI2D that a previously open modal-window was closed. You should always call this when closing a modal-window (usually performed from a button inside that window) so that UI2D can restore interaction with the other windows.

---

UI2D.SameColumn() |Argument|Type|Description |:---|:---|:---| |none||

Returns: nothing
NOTE: If the last widget used the UI2D.SameLine() call, it effectively started a new "column". This function can be called such as the next widget will be placed on that column, under the last widget.

---

UI2D.ListBoxSetSelected(name, idx) |Argument|Type|Description |:---|:---|:---| |name|string|listbox name |idx|number or table|Index of item to be selected, or table of indices (in case this listbox' multi_select property is set to true)

Returns: nothing
NOTE: Sets the selected item(s) of a ListBox programmatically