{"id":14779635,"url":"https://github.com/immortalx74/lovr-ui2d","last_synced_at":"2025-04-30T14:21:14.163Z","repository":{"id":201131865,"uuid":"705169844","full_name":"immortalx74/lovr-ui2d","owner":"immortalx74","description":"An immediate mode GUI library for LÖVR and  LÖVE","archived":false,"fork":false,"pushed_at":"2024-09-10T14:00:05.000Z","size":271,"stargazers_count":38,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-01-08T13:31:32.668Z","etag":null,"topics":["gui","imgui","immediate-mode","love","love2d","lovr","lua"],"latest_commit_sha":null,"homepage":"","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/immortalx74.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2023-10-15T08:36:48.000Z","updated_at":"2024-12-05T11:10:49.000Z","dependencies_parsed_at":"2024-01-13T10:35:02.707Z","dependency_job_id":"17a5738d-cd6e-4313-94dd-06a10357ae0c","html_url":"https://github.com/immortalx74/lovr-ui2d","commit_stats":null,"previous_names":["immortalx74/lovr-ui2d"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/immortalx74%2Flovr-ui2d","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/immortalx74%2Flovr-ui2d/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/immortalx74%2Flovr-ui2d/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/immortalx74%2Flovr-ui2d/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/immortalx74","download_url":"https://codeload.github.com/immortalx74/lovr-ui2d/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":233266688,"owners_count":18650220,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gui","imgui","immediate-mode","love","love2d","lovr","lua"],"created_at":"2024-09-17T01:00:55.005Z","updated_at":"2025-01-09T22:25:04.851Z","avatar_url":"https://github.com/immortalx74.png","language":"Lua","funding_links":[],"categories":["Recently Updated","UI"],"sub_categories":["[Sep 15, 2024](/content/2024/09/15/README.md)"],"readme":"# lovr-ui2d\n\n### An immediate mode GUI library for the [LÖVR](https://lovr.org/) and [LÖVE](https://love2d.org/) frameworks.\nThis is the sister project of [lovr-ui](https://github.com/immortalx74/lovr-ui) (a VR GUI library for lovr).\nBoth projects borrow concepts from the outstanding [Dear ImGui](https://github.com/ocornut/imgui) library and are inspired by [microui](https://github.com/rxi/microui), trying to be simple and minimal.\n\n\nThis 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).\n\nhttps://github.com/immortalx74/lovr-ui2d/assets/29693328/3b1e15cc-948f-401f-a236-ee63c44e07ea\n\n**How to use:**\n\nSee `main.lua` for minimal and demo implementations. Below is the complete API documentation but some things will make more sense by examining the examples.\n\n**Widgets:**\n\n - Button\n - ImageButton\n - TextBox\n - ListBox\n - SliderInt\n - SliderFloat\n - Label\n - CheckBox\n - ToggleButton\n - RadioButton\n - TabBar\n - Dummy\n - ProgressBar\n - CustomWidget\n - Modal window\n - Separator\n\n**API:**\n\n---\n`UI2D.Button(name, width, height, tooltip)`\n|Argument|Type|Description\n|:---|:---|:---|\n|`name`|string|button's text\n|`width` _[opt]_|number|button width in pixels\n|`height` _[opt]_|number|button height in pixels\n|`tooltip` _[opt]_|string|tooltip text\n \n\u003cspan style=\"color:DeepSkyBlue\"\u003eReturns:\u003c/span\u003e `boolean`, true when clicked.  \nNOTE:  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. \n\n---\n`UI2D.ImageButton(texture, width, height, text, tooltip)`\n|Argument|Type|Description\n|:---|:---|:---|\n|`texture`|texture/image|texture(lovr) or image(love)\n|`width`|number|image width in pixels\n|`height`|number|image height in pixels\n|`text` _[opt]_|string|optional text\n|`tooltip` _[opt]_|string|tooltip text\n\n\u003cspan style=\"color:DeepSkyBlue\"\u003eReturns:\u003c/span\u003e `boolean` , true when clicked.  \n\n---\n`UI2D.CustomWidget(name, width, height, tooltip)`\n|Argument|Type|Description\n|:---|:---|:---|\n|`name`|string|custom widget name\n|`width`|number|width in pixels\n|`height`|number|height in pixels\n|`tooltip` _[opt]_|string|tooltip text\n\n\u003cspan style=\"color:DeepSkyBlue\"\u003eReturns:\u003c/span\u003e `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  \nNOTE: 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)\n\n---\n`UI2D.TextBox(name, num_visible_chars, text, tooltip)`\n|Argument|Type|Description\n|:---|:---|:---|\n|`name`|string|textbox name\n|`num_visible_chars`|number|number of visible characters\n|`text`|string|text\n|`tooltip` _[opt]_|string|tooltip text\n\n\u003cspan style=\"color:DeepSkyBlue\"\u003eReturns:\u003c/span\u003e `string`, `boolean` [1] text, [2] finished editing.  \nNOTE: 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.\n\n---\n`UI2D.ListBox(name, num_visible_rows, num_visible_chars, collection, selected, multi_select, tooltip)`\n|Argument|Type|Description\n|:---|:---|:---|\n|`name`|string|listbox name\n|`num_visible_rows`|number|number of visible rows\n|`num_visible_chars`|number|number of visible characters on each row\n|`collection`|table|table of strings\n|`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)\n|`multi_select` _[opt]_|boolean|whether multi-select should be enabled\n|`tooltip` _[opt]_|string|tooltip text\n\n\u003cspan style=\"color:DeepSkyBlue\"\u003eReturns:\u003c/span\u003e `boolean`, `number`, `table`, [1] true when clicked, [2] selected item index, [3] table of selected item indices (if multi_select is true)  \nNOTE: The `UI2D.ListBoxSetSelected` helper can be used to select item(s) programmatically.\n\n---\n`UI2D.SliderInt(name, v, v_min, v_max, width, tooltip)`\n|Argument|Type|Description\n|:---|:---|:---|\n|`name`|string|slider text\n|`v`|number|initial value\n|`v_min`|number|minimum value\n|`v_max`|number|maximum value\n|`width` _[opt]_|number|total width in pixels of the slider, including it's text\n|`tooltip` _[opt]_|string|tooltip text\n\n\u003cspan style=\"color:DeepSkyBlue\"\u003eReturns:\u003c/span\u003e `number`, `boolean`, [1] current value, [2] true when released  \nNOTE: Always assign back to your slider-value, e.g. `myval = UI2D.SliderInt(\"my slider\", myval, 0, 100)`\nIf width is provided, it will be taken into account only if it exceeds the width of text, otherwise it will be ignored. \n\n---\n`UI2D.SliderFloat(name, v, v_min, v_max, width, num_decimals, tooltip)`\n|Argument|Type|Description\n|:---|:---|:---|\n|`name`|string|slider text\n|`v`|number|initial value\n|`v_min`|number|minimum value\n|`v_max`|number|maximum value\n|`width` _[opt]_|number|total width in pixels of the slider, including it's text\n|`num_decimals` _[opt]_|number|number of decimals to display\n|`tooltip` _[opt]_|string|tooltip text\n\n\u003cspan style=\"color:DeepSkyBlue\"\u003eReturns:\u003c/span\u003e `number`, `boolean`, [1] current value, [2] true when released   \nNOTE: Always assign back to your slider-value, e.g. `myval = UI2D.SliderFloat(\"my slider\", myval, 0, 100)`\nIf `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.\n\n---\n`UI2D.Label(text)`\n|Argument|Type|Description\n|:---|:---|:---|\n|`text`|string|label text\n|`compact` _[opt]_|boolean|ignore vertical margin\n\n\u003cspan style=\"color:DeepSkyBlue\"\u003eReturns:\u003c/span\u003e `nothing`  \n\n---\n`UI2D.ProgressBar(progress, width, tooltip)`\n|Argument|Type|Description\n|:---|:---|:---|\n|`progress`|number|progress percentage\n|`width` _[opt]_|number|width in pixels\n|`tooltip` _[opt]_|string|tooltip text\n\n\u003cspan style=\"color:DeepSkyBlue\"\u003eReturns:\u003c/span\u003e `nothing`  \nNOTE: Default width is 300 pixels\n\n---\n`UI2D.Separator()`\n|Argument|Type|Description\n|:---|:---|:---|\n|`none`||\n\n\u003cspan style=\"color:DeepSkyBlue\"\u003eReturns:\u003c/span\u003e `nothing`  \nNOTE: Horizontal Separator\n\n---\n`UI2D.CheckBox(text, checked, tooltip)`\n|Argument|Type|Description\n|:---|:---|:---|\n|`text`|string|checkbox text\n|`checked`|boolean|state\n|`tooltip` _[opt]_|string|tooltip text\n\n\u003cspan style=\"color:DeepSkyBlue\"\u003eReturns:\u003c/span\u003e `boolean`, true when clicked  \nNOTE: To set the state use this idiom: `if UI2D.CheckBox(\"My checkbox\", my_state) then my_state = not my_state end`\n\n---\n`UI2D.ToggleButton(text, checked, tooltip)`\n|Argument|Type|Description\n|:---|:---|:---|\n|`text`|string|toggle button text\n|`checked`|boolean|state\n|`tooltip` _[opt]_|string|tooltip text\n\n\u003cspan style=\"color:DeepSkyBlue\"\u003eReturns:\u003c/span\u003e `boolean`, true when clicked  \nNOTE: To set the state use this idiom: `if UI2D.ToggleButton(\"My toggle button\", my_state) then my_state = not my_state end`\n\n---\n`UI2D.RadioButton(text, checked, tooltip)`\n|Argument|Type|Description\n|:---|:---|:---|\n|`text`|string|radiobutton text\n|`checked`|boolean|state\n|`tooltip` _[opt]_|string|tooltip text\n\n\u003cspan style=\"color:DeepSkyBlue\"\u003eReturns:\u003c/span\u003e `boolean`, true when clicked  \nNOTE: To set the state on a group of RadioButtons use this idiom: \n`if UI2D.RadioButton(\"Radio1\", rb_group_idx == 1) then rb_group_idx = 1 end`\n`if UI2D.RadioButton(\"Radio2\", rb_group_idx == 2) then rb_group_idx = 2 end`\n`-- etc...`\n\n---\n`UI2D.TabBar(name, tabs, idx, tooltip)`\n|Argument|Type|Description\n|:---|:---|:---|\n|`name`|string|TabBar name\n|`tabs`|table|a table of strings\n|`idx`|number|initial active tab index\n|`tooltip` _[opt]_|string|tooltip text\n\n\u003cspan style=\"color:DeepSkyBlue\"\u003eReturns:\u003c/span\u003e `boolean`, `number`, [1] true when clicked, [2] the selected tab index  \n\n---\n`UI2D.Dummy(width, height)`\n|Argument|Type|Description\n|:---|:---|:---|\n|`width`|number|width\n|`height`|number|height\n\n\u003cspan style=\"color:DeepSkyBlue\"\u003eReturns:\u003c/span\u003e `nothing`  \nNOTE: This is an invisible widget useful only to \"push\" other widgets' positions or to leave a desired gap.\n\n---\n`UI2D.Begin(name, x, y, is_modal)`\n|Argument|Type|Description\n|:---|:---|:---|\n|`name`|string|window title\n|`x`|number|window X position\n|`y`|number|window Y position\n|`is_modal` _[opt]_|boolean|is this a modal window\n\n\u003cspan style=\"color:DeepSkyBlue\"\u003eReturns:\u003c/span\u003e `nothing`  \nNOTE: 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. \n\n---\n`UI2D.End(main_pass(lovr) or nothing(love))`\n|Argument|Type|Description\n|:---|:---|:---|\n|`main_pass`|Pass|the main Pass object(only for lovr)\n\n\u003cspan style=\"color:DeepSkyBlue\"\u003eReturns:\u003c/span\u003e `nothing`  \nNOTE: Ends the current window. \n\n---\n`UI2D.SameLine()`\n|Argument|Type|Description\n|:---|:---|:---|\n|`none`||\n\n\u003cspan style=\"color:DeepSkyBlue\"\u003eReturns:\u003c/span\u003e `nothing`  \nNOTE: Places the next widget side-to-side with the last one, instead of bellow\n\n---\n`UI2D.GetWindowSize(name)`\n|Argument|Type|Description\n|:---|:---|:---|\n|`name`|number|window name\n\n\u003cspan style=\"color:DeepSkyBlue\"\u003eReturns:\u003c/span\u003e `number`, `number`, [1] window width, [2] window height  \nNOTE: If no window with this name was found, return type is `nil`\n\n---\n`UI2D.Init(type, size)`\n|Argument|Type|Description\n|:---|:---|:---|\n|`type`|string|which framework to use (valid values: \"lovr\", \"love\")\n|`size` _[opt]_|number|font size\n\n\u003cspan style=\"color:DeepSkyBlue\"\u003eReturns:\u003c/span\u003e `nothing`  \nNOTE: Initializes the library and should be called on `lovr/love.load()`. Font size dictates the general size of the UI. Default is 14\n\n---\n`UI2D.InputInfo()`\n|Argument|Type|Description\n|:---|:---|:---|\n|`none`||\n\n\u003cspan style=\"color:DeepSkyBlue\"\u003eReturns:\u003c/span\u003e `nothing`  \nNOTE: Should be called on `lovr/love.update()`\n\n---\n`UI2D.RenderFrame(main_pass(only for lovr))`\n|Argument|Type|Description\n|:---|:---|:---|\n|`main_pass`|Pass|the main Pass object(lovr).\n\n\u003cspan style=\"color:DeepSkyBlue\"\u003eReturns:\u003c/span\u003e `table` of ui passes(lovr) or nothing(love)  \nNOTE: 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.)\n\n---\n`UI2D.OverrideColor(col_name, color)`\n|Argument|Type|Description\n|:---|:---|:---|\n|`col_name`|string|color name\n|`color`|table|color value in table form (r, g, b, a)\n\n\u003cspan style=\"color:DeepSkyBlue\"\u003eReturns:\u003c/span\u003e `nothing`  \nNOTE: Helper to override a color value.\n\n---\n`UI2D.SetColorTheme(theme, copy_from)`\n|Argument|Type|Description\n|:---|:---|:---|\n|`theme`|string or table|color name or table with names of colors\n|`copy_from` _[opt]_|string|color-theme to copy values from\n\n\u003cspan style=\"color:DeepSkyBlue\"\u003eReturns:\u003c/span\u003e `nothing`  \nNOTE: 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.\n\n---\n`UI2D.CloseModalWindow()`\n|Argument|Type|Description\n|:---|:---|:---|\n|`none`||\n\n\u003cspan style=\"color:DeepSkyBlue\"\u003eReturns:\u003c/span\u003e `nothing`  \nNOTE: Closes a modal window\n\n---\n`UI2D.KeyPressed(key, repeating)`\n|Argument|Type|Description\n|:---|:---|:---|\n|`key`|string|key name\n|`repeating`|boolean|if the key is repeating instead of an instant press.\n\n\u003cspan style=\"color:DeepSkyBlue\"\u003eReturns:\u003c/span\u003e `nothing`  \nNOTE: Should be called on `lovr/love.keypressed()` callback.\n\n---\n`UI2D.TextInput(text)`\n|Argument|Type|Description\n|:---|:---|:---|\n|`text`|string|character from a textinput event.\n\n\u003cspan style=\"color:DeepSkyBlue\"\u003eReturns:\u003c/span\u003e `nothing`  \nNOTE: Should be called on `lovr/love.textinput()` callback.\n\n---\n`UI2D.KeyReleased()`\n|Argument|Type|Description\n|:---|:---|:---|\n|`none`||\n\n\u003cspan style=\"color:DeepSkyBlue\"\u003eReturns:\u003c/span\u003e `nothing`  \nNOTE: Should be called on `lovr/love.keyreleased()` callback.\n\n---\n`UI2D.WheelMoved(x, y)`\n|Argument|Type|Description\n|:---|:---|:---|\n|`x`|number|wheel X.\n|`y`|number|wheel Y.\n\n\u003cspan style=\"color:DeepSkyBlue\"\u003eReturns:\u003c/span\u003e `nothing`  \nNOTE: Should be called on `lovr/love.wheelmoved()` callback.\n\n---\n`UI2D.HasMouse()`\n|Argument|Type|Description\n|:---|:---|:---|\n|`none`||\n\n\u003cspan style=\"color:DeepSkyBlue\"\u003eReturns:\u003c/span\u003e `nothing`  \nNOTE: Whether the mouse-pointer hovers a UI2D window.\n\n---\n`UI2D.SetWindowPosition(name, x, y)`\n|Argument|Type|Description\n|:---|:---|:---|\n|`name`|string|name of the window\n|`x`|number|X position\n|`y`|number|Y position\n\n\u003cspan style=\"color:DeepSkyBlue\"\u003eReturns:\u003c/span\u003e `boolean`, true if the window was found  \nNOTE: Sets a window's position programmatically.\n\n---\n`UI2D.GetColorTheme()`\n|Argument|Type|Description\n|:---|:---|:---|\n|`none`||\n\n\u003cspan style=\"color:DeepSkyBlue\"\u003eReturns:\u003c/span\u003e `string`, theme name  \nNOTE: Gets the current color-theme\n\n---\n`UI2D.ResetColor(col_name)`\n|Argument|Type|Description\n|:---|:---|:---|\n|`col_name`|string|color name\n\n\u003cspan style=\"color:DeepSkyBlue\"\u003eReturns:\u003c/span\u003e `nothing`  \nNOTE: Resets a color to its default value\n\n---\n`UI2D.SetFontSize(size)`\n|Argument|Type|Description\n|:---|:---|:---|\n|`size`|number|font size\n\n\u003cspan style=\"color:DeepSkyBlue\"\u003eReturns:\u003c/span\u003e `nothing`  \nNOTE: Sets the font size\n\n---\n`UI2D.GetFontSize()`\n|Argument|Type|Description\n|:---|:---|:---|\n|`none`||\n\n\u003cspan style=\"color:DeepSkyBlue\"\u003eReturns:\u003c/span\u003e `number`, font size  \nNOTE: Gets the current font size\n\n---\n`UI2D.HasTextInput()`\n|Argument|Type|Description\n|:---|:---|:---|\n|`none`||\n\n\u003cspan style=\"color:DeepSkyBlue\"\u003eReturns:\u003c/span\u003e `boolean`, true if a textbox has focus  \nNOTE: Gets whether the text of a textbox is currently being edited\n\n---\n`UI2D.IsModalOpen()`\n|Argument|Type|Description\n|:---|:---|:---|\n|`none`||\n\n\u003cspan style=\"color:DeepSkyBlue\"\u003eReturns:\u003c/span\u003e `boolean`, true if a modal window is currently open  \nNOTE: Gets whether a modal window is currently open\n\n---\n`UI2D.EndModalWindow()`\n|Argument|Type|Description\n|:---|:---|:---|\n|`none`||\n\n\u003cspan style=\"color:DeepSkyBlue\"\u003eReturns:\u003c/span\u003e `nothing`  \nNOTE: 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. \n\n---\n`UI2D.SameColumn()`\n|Argument|Type|Description\n|:---|:---|:---|\n|`none`||\n\n\u003cspan style=\"color:DeepSkyBlue\"\u003eReturns:\u003c/span\u003e `nothing`  \nNOTE: 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.\n\n---\n`UI2D.ListBoxSetSelected(name, idx)`\n|Argument|Type|Description\n|:---|:---|:---|\n|`name`|string|listbox name\n|`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)\n\n\u003cspan style=\"color:DeepSkyBlue\"\u003eReturns:\u003c/span\u003e `nothing`  \nNOTE: Sets the selected item(s) of a ListBox programmatically\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fimmortalx74%2Flovr-ui2d","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fimmortalx74%2Flovr-ui2d","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fimmortalx74%2Flovr-ui2d/lists"}