lovr-ui

An immediate mode VR GUI library for LÖVR

( For a retained mode UI library check out chui ) How to use:

• Put the ui folder inside your project and require it: UI = require "ui/ui"
• Initialize the library by calling UI.Init() on lovr.load()
• Handle controller input by calling UI.InputInfo() on lovr.update()
• Everything inside NewFrame()/RenderFrame() is your GUI

Input:

• Change the dominant hand by pushing the corresponding trigger button.
• Scroll in ListBox with the Y-axis of the analog stick.
• Text entry is done by an on-screen keyboard (appears when a TextBox has focus).
• If additional keyboard languages are provided, cycling between them is done by holding grip and pressing the trigger on the space key.
• Enter an exact value in a slider by holding down grip and pressing trigger.
• Move windows by pointing at them and holding the grip button.
• Enable/Disable interaction with the GUI by pressing the Left Thumbstick down (user configurable).

Widgets:

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

---

UI.Button(text, width, height)

Argument	Type	Description
text	string	button's text
width [opt]	number	button width in pixels
height [opt]	number	button height in pixels

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.

---

UI.ImageButton(img_filename, width, height, text)

Argument	Type	Description
img_filename	string	image filename
width	number	image width in pixels
height	number	image height in pixels
text [opt]	string	optional text

Returns: boolean , true when clicked.

---

UI.WhiteBoard(name, width, height)

Argument	Type	Description
name	string	whiteboard ID
width	number	width in pixels
height	number	height in pixels

Returns: Pass, boolean, boolean, boolean, boolean, number, number, [1] Pass object, [2] clicked, [3] down, [4] released, [5] hovered, [6] X, [7] Y
NOTE: General purpose widget for custom drawing/interaction. The returned Pass can be used to do regular LÖVR draw-commands
like plane, circle, text, etc. X and Y are the local 2D coordinates of the pointer (0,0 is top,left)

---

UI.TextBox(name, num_visible_chars, buffer)

Argument	Type	Description
name	string	textbox ID
num_visible_chars	number	number of visible characters
buffer	string	user provided text buffer

Returns: boolean, boolean, number, string , [1] got focus, [2] buffer changed, [3] ID, [4] modified buffer.
NOTE: When clicked, an on-screen keyboard will pop-up for text entry. Enter closes the keyboard. To modify the original buffer assign the 4th return value back to the original buffer variable. The ID returned can be passed in the helper function UI.SetTextBoxText to set the desired text after validation. (example in main.lua)

---

UI.ListBox(name, num_visible_rows, num_visible_chars, collection, selected)

Argument	Type	Description
name	string	listbox ID
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)

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

---

UI.SliderInt(text, v, v_min, v_max, width)

Argument	Type	Description
text	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

Returns: boolean, number, [1] true when released, [2] the current value
NOTE: Use this idiom to assign back to the provided number variable: slider_released, slider_val = UI.SliderInt("My slider", slider_val, 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.

---

UI.SliderFloat(text, v, v_min, v_max, width, num_decimals)

Argument	Type	Description
text	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

Returns: boolean, number, [1] true when released, [2] the current value
NOTE: Use this idiom to assign back to the provided number variable: slider_released, slider_val = UI.SliderFloat("My slider", slider_val, 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.

---

UI.Label(text)

Argument	Type	Description
text	string	label text
compact [opt]	boolean	ignore vertical margins

Returns: nothing

---

UI.ProgressBar(progress, width)

Argument	Type	Description
progress	number	progress percentage
width [opt]	number	width in pixels

Returns: nothing
NOTE: Default width is 300 pixels

---

UI.Separator()

Argument	Type	Description
none

Returns: nothing
NOTE: Horizontal Separator

---

UI.CheckBox(text, checked)

Argument	Type	Description
text	string	checkbox text
checked	boolean	state

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

---

UI.RadioButton(text, checked)

Argument	Type	Description
text	string	radiobutton text
checked	boolean	state

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

---

UI.TabBar(name, tabs, idx)

Argument	Type	Description
name	string	TabBar ID
tabs	table	a table of strings
idx	number	initial active tab index

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

---

UI.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.

---

UI.Begin(name, transform, is_modal)

Argument	Type	Description
name	string	window ID
transform	Mat4	window transform
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 UI.End(main_pass) is called. If this is set as a modal window (by passing true to the last argument) it should always call UI.EndModalWindow before closing it physically. (see example in main.lua)

---

UI.End(main_pass)

Argument	Type	Description
main_pass	Pass	the main Pass object

Returns: nothing
NOTE: Ends the current window.

---

UI.SameLine()

Argument	Type	Description
none

Returns: nothing
NOTE: Places the next widget beside the last one, instead of bellow

---

UI.GetWindowSize(name)

Argument	Type	Description
name	number	window ID

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

---

UI.SetTextBoxText(id, text)

Argument	Type	Description
id	number	textbox ID
text	string	textbox text

Returns: nothing
NOTE: Helper to set the textbox text after validation.

---

UI.SetInteractionEnabled(enabled)

Argument	Type	Description
enabled	boolean	if interaction should be enabled

Returns: nothing
NOTE: Useful if you want to set interaction on/off programmatically, without pressing the toggle button

---

UI.Init(interaction_toggle_device, interaction_toggle_button, enabled, pointer_rotation)

Argument	Type	Description
interaction_toggle_device [opt]	Device	controller
interaction_toggle_button [opt]	DeviceButton	controller button that toggles interaction on/off
enabled [opt]	boolean	initial state of interaction
pointer_rotation [opt]	number	pointer rotation angle (default value is similar to SteamVR/Oculus).

Returns: nothing
NOTE: Should be called on lovr.load(). Defaults are hand/left, thumbstick, true, math.pi / 3 respectively.

---

UI.InputInfo(emulated_headset, ray_position, ray_orientation)

Argument	Type	Description
emulated_headset [opt]	boolean	emulated headset
ray_position [opt]	Vec3	ray position
ray_orientation [opt]	Quat	ray orientation

Returns: nothing
NOTE: Should be called on lovr.update(). To operate in standard "VR mode" do not pass any arguments. The optional arguments could be passed to emulate the headset with mouse and keyboard. When only the 1st argument is passed, data is captured from the emulated headset directly. When the render pass has a different transform than the headset, then the 2 last arguments should be passed too.

---

UI.NewFrame(main_pass)

Argument	Type	Description
main_pass	Pass	the main Pass object

Returns: nothing
NOTE: Should be called on lovr.draw(). Windows and widgets should be called after this function, and a UI.RenderFrame(main_pass) finalizes the whole UI.

---

UI.RenderFrame(main_pass)

Argument	Type	Description
main_pass	Pass	the main Pass object.

Returns: table, ui passes
NOTE: During the frame, lovr-ui records its own passes for drawing the various elements but doesn't submit them. Instead, a table of those passes is returned to the user where they can be scheduled to be submitted along with the default pass (See the example near the end of main.lua).

---

UI.GetColorNames()

Argument	Type	Description
none

Returns: table, color names
NOTE: Helper to get the color keys as a table of strings

---

UI.GetColor(col_name)

Argument	Type	Description
col_name	string	color key

Returns: table, color value
NOTE: Helper to get a color value

---

UI.SetColor(col_name, color)

Argument	Type	Description
col_name	string	color key
col_name	string	color value

Returns: nothing
NOTE: Helper to set a color value. Don't call this every frame because it regenerates the keyboard textures. Use UI.OverrideColor instead.

---

UI.OverrideColor(col_name, color)

Argument	Type	Description
col_name	string	color key
col_name	string	color value

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

---

UI.SetColorTheme(theme, copy_from)

Argument	Type	Description
theme	string or table	color key or table with overrided keys
copy_from [opt]	string	theme to copy values from

Returns: nothing
NOTE: Sets a 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.

---

UI.CloseModalWindow()

Argument	Type	Description
none

Returns: nothing
NOTE: Closes a modal window

---

UI.AddKeyboardPack(lower_case, upper_case, symbols)

Argument	Type	Description
lower_case	table	lower case characters
upper_case	table	upper case characters
symbols	table	symbol characters

Returns: nothing
NOTE: Provides the ability to add a language pack for the on-screen keyboard. The default pack is Latin. Cycling between packs is done by holding the grip button and pressing the trigger on the space key of the on-screen keyboard.

---

UI.GetScale()

Argument	Type	Description
none

Returns: number, ui scale NOTE: Helper to get the ui scale

---

UI.SetScale(scale)

Argument	Type	Description
scale	number	ui scale

Returns: nothing
NOTE: Helper to set the ui scale. Don't call this every frame (it causes textures to be regenerated)

---

General Info: UI.Begin()/UI.End() defines a window. Widget function calls placed inside this block, are then part of this window. lovr-ui currently uses a row-based auto-layout. That means that there are limits to how widgets are positioned. Widget sizes are mostly character-width based. This is done for simplicity. This library borrows concepts from the outstanding Dear ImGui library and is inspired by microui, trying to be simple and minimal.