[Lua] UI Manager

Original Post

sir

Apr 30, 2018

sir

Toribash Dev

Join Date: Jan 2009

Apr 30, 2018

[Lua] UI Manager

Hi, this is an extensive guide on UI manager script included with Toribash 5.2+ (data/script/toriui/uielement.lua).

Intro and quick example

UI Manager is used for (almost) all new official scripts including new main menu, and it allows building complicated user interfaces with minimal effort.

UI Manager uses object-oriented approach with UIElement being the main class for all objects. Let's look at a quick example of a script that uses the manager:

Example

First of all, you need to include uielement.lua file. The first line of our script does that: dofile("toriui/uielement.lua") makes UIElement class visible to our script.

After that we spawn our first object. I made it local in the example due to script's simplicity, but for big scripts you may want to keep your primary object public so that you could address it from outside.
To spawn an object, you need to call UIElement's new(...) method and pass the table with object's properties. In our case we're spawning a basic 200x70px square black button with 100px padding from top and left of the screen that turns red when we hover over it and turns green when it's being pressed. All the possible options will be explained below.

Once the object is created, we add custom display and specify what to do once the button is pressed. Obviously, if you just need to display a simple box or an image, these steps aren't necessary.

UIElement's addCustomDisplay(...) method is used to specify custom display function. To output the "Press Me!" string we use UIElement's uiText(...) method in its simplest form. In short - it makes sure the string fits its parent object and aligns it the way you want inside of it. All the details will be explained below.

addMouseHandlers(...) method allows you to specify what to do when a user hovers over an object or presses on it. In our case we unload the display hooks and call the kill() method on our button to remove it - which basically unloads our script.

After that goes the drawVisuals() function. Generally you shouldn't need to do any modifications to it - the function you see in this example is same as used for other Toribash built-in scripts. It loops through all active UI elements, updates their positions and then draws them.

Lastly, we add hooks. Generally you won't need to apply any changes to what's provided in the example script - first three hooks handle mouse movements and clicks, fourth handles visuals.

That's it, you got a basic button that closes the script when you press it. No need to write your own code to detect mouse movements, no need to center the text or whatsoever.

UIElement class methods

UIElement:new(table options) - spawns an object.
Full list of currently available options ►
- parent - parent object, default is nil
  Your primary object most likely won't require a parent, but for any succeeding object it's highly advised to specify a parent out of already existing objects. Reasons why will be explained below.
- pos - takes a { number xPos, number yPos } table with object's relative position. Can't be null.
  In case of empty parent the position is absolute. Use negative values to invert orientation.
- size - takes a { number xSize, number ySize } table with object's size. Can't be null.
- bgColor - takes a { r, g, b, a } table with object's default color.
- interactive - takes a boolean value specifying whether the object should be interactive or not.
- scrollEnabled - takes a boolean value specifying whether scrollbar should be active or not.
- hoverColor - takes a { r, g, b, a } table with object's hover color. Requires interactive to display.
- pressedColor - takes an { r, g, b, a } table with object's pressed state color. Requires interactive to display.
- bgImage - takes a string with a .tga texture path.
  Default folder is data/script, add "../" to look up a texture in data/ or "../../" too look up a texture in Toribash main folder.
- shapeType - takes a shape id specifying object shape.
  Default shape is square (global variable SQUARE = 1), use global variable ROUNDED (equals 2) to add rounded edges.
- rounded - takes a number value specifying rounded edges' radius.
- hoverSound - takes a sound id to play when hovering over object. Requires interactive.
- upSound - takes a sound id to play when triggering mouse_button_up hook after pressing the object. Requires interactive.
- downSound - takes a sound id to play when triggering mouse_button_down hook when pressing the object. Requires interactive.
- innerShadow - takes a { number shadowTop, number shadowBot } table specifying innershadow height.
- shadowColor - takes a { table colorTop, table colorBot } table to specify innerShadow colors. Requires innerShadow to work.
- viewport - takes a boolean value specifying whether the object is a viewport. See explanations below.
- textfield - takes a boolean value specifying whether the object is a text field. Object also has to be interactive.
- textfieldstr - takes a { string textStr } table with a text field message. Requires textfield.
  Pay attention to the fact that it takes a table with a string instead of just a string. This is done to allow easier manipulations when globally visible variables are loaded as text field messages.
UIElement:kill(boolean childOnly) - removes the object and all of its children.
Arguments explanation:
- childOnly - specifies whether you want to only kill object's children elements. Default value is false
UIElement:show(boolean forceReload) - shows an object and its children.
Arguments explanation:
- forceReload - specifies whether to show override object's noreload option (see hide() method info). Default value is false
UIElement:hide(boolean noreload) - hides an object and its children.
Arguments explanation:
- noreload - specifies whether to require show() method's forceReload option to make object and its children visible again (see show() method info). Default value is false
UIElement:reload() - runs hide() and show() methods for the object.
UIElement:activate() - activates an interactive object.
UIElement:deactivate() - deactivates an interactive object.
Note: this doesn't hide the object but only makes it ignore mouse hooks.
UIElement:moveTo(number x, number y) - moves an object and its children to a relative position.
Arguments explanation:
- x - relative x position, accepts nil value
- y - relative y position, accepts nil value
UIElement:uiText(string textString, number x, number y, fontid font, alignid align, number scale, number angle, number shadow, color col1, color col2, number intensity, boolean check) - displays text inside an object. In case it doesn't fit the object, cuts it and replaces the hidden part with "...".

Examples ►
Text displayed within a 300x70 object (fits the size, string uncut)

Same text displayed within a 200x70 object (doesn't fit the size, cut to fit the object)

Arguments explanation:
- textString - string containing text that is going to be displayed. Allows the use of newline ("\n").
- x - absolute x position for text box. Default value is self.pos.x.
- y - absolute y position for text box. Default value is self.pos.y.
- font - desired font's id. Default value is FONTS.MEDIUM.
- align - desired align style id. Default value is CENTERMID.
  Align styles ►
  STYLE || VALUE LEFT || 0 CENTER || 1 RIGHT || 2 LEFTBOT || 3 CENTERBOT || 4 RIGHTBOT || 5 LEFTMID || 6 CENTERMID || 7 RIGHTMID || 8
- scale - font scale in percents. Default value is 1 (100%).
- angle - text angle in degrees. Default value is 0.
- shadow - text shadow thickness. Default value is 0.
- col1 - table containing text color. Default value is { 1, 1, 1, 1 } (white).
- col2 - table containing text shadow color. Default value is { 0, 0, 0, 0.6 } (60% black).
- intensity - specifies additional color intensity for text that's drawn with FONTS.MEDIUM, FONTS.BIG and FONTS.BIGGER font ids. Default value is 1.
- check - use this to check whether the string fits the object. Calling uiText() with check enabled won't draw anything but return true or false value depending on the check result. Default value is false.
UIElement:getButtonColor() - returns the current color of an interactive object.
UIElement:getPos() - returns a table containing object's relative position.
UIElement:getLocalPos(number xPos, number yPos, table pos) - returns a table containing object's relative position for a point with xPos and yPos absolute coordinates.
Arguments explanation:
- xPos - absolute x position of a point. Can't be nil.
- yPos - absolute y position of a point. Can't be nil.
- pos - table with closest parent's local pos for the point. Only used for during recursive calls inside the method, has to be nil for correct results.
UIElement:updateImage(string image, string default, boolean noreload) - sets a background image for an object.
Keeps a cache of all currently loaded textures and prevents premature texture unloading when killing objects in case of same image being used for multiple objects. Also prevents new textures from being loaded when you hit the 256 max textures cap.
Arguments explanation:
- image - desired image's path. Looks for images within data/script folder by default, add "../" or "../../" before the path to access data/ and Toribash root folder respectively. Use nil value to unload the image.
- default - default image's path. Default value is stored in DEFTEXTURE variable.
- noreload - specifies whether you want to prevent object's current texture (if any) from being unloaded. Use with caution as this can potentially mess the loaded textures cache. Default value is false.
UIElement:addMouseHandlers(function btnDown, function btnUp, function btnHover) - adds custom functionality for interactive objects.
This one is pretty straight-forward, you call it to attach your custom code when interactive objects are being used. Any of the three arguments accept nil values, but if you want to clear the previously used function you'd still need to pass an empty function as an argument.
UIElement:addKeyboardHandlers(function keyDown, function keyUp) - adds custom functionality for textfield objects.
Arguments accept nil values.
UIElement:makeScrollBar(UIElement listHolder, table listElements, UIElement toReload, table posShift, number scrollSpeed) - method used to create scrollable lists. Needs to be called on an object you plan to make scroll bar. See full usage example below.
UIElement:addCustomDisplay(boolean customOnly, function drawFunction, boolean drawBefore) - adds custom display to your object.
Arguments explanation:
- customOnly - specifies whether you want to override default object display function and only run custom code. Default value is false.
- drawFunction - custom function that will be run each time draw2d hook is called while the object is being displayed.
- drawBefore - specifies whether you want to run the custom display function after default display or before it. Default value is false.
UIElement:runCmd(string command, boolean echo) - runs a run_cmd() function with additional options.
Arguments explanation:
- command - a Toribash command to run.
- echo - specifies whether to display an echo message when running the command. Default value is false.
UIElement:qsort(table arr, string sort, boolean desc) - runs a quicksort operation on the arr table.
Arguments explanation:
- arr - a two-dimensional table that needs to be sorted.
- sort - column name which values will be used for sorting.
- desc - whether you want to return an inversed results table. Default value is false.

Examples

makeScrollBar(...) method usage example ►

Visual representation

lua code:

dofile("toriui/uielement.lua")



-- Creating a global posShift table - this will store the last scrollbar position between script runs within one game session

POS_SHIFT = POS_SHIFT or { 0 }



-- Creating the list

local list = { "The", "quick", "brown", "fox", "jumps", "over", "the", "lazy", "dog" }



-- Spawning the primary parent object

viewElement = UIElement:new({

	pos = { 0, 0 },

	size = { 400, 300 },

	bgColor = { 1, 0.4, 0, 1 }

})



-- Spawning a parent element for any object that needs to be reloaded every frame

local toReload = UIElement:new({

	parent = viewElement,

	pos = { 0, 0 },

	size = { viewElement.size.w, viewElement.size.h }

})



-- Adding toReload children objects which will overlay scrollable list elements on top and bottom.

-- In case any of the scrollable list elements are interactive, these should be interactive aswell to prevent accidental clicking.

-- Bars' height should be at least same as scrollable list's elements' height.

local listElementHeight = 40

local topBar = UIElement:new({

	parent = toReload,

	pos = { 0, 0 },

	size = { viewElement.size.w, listElementHeight },

	bgColor = { 0, 0, 0, 1 },

	interactive = true

})

local botBar = UIElement:new({

	parent = toReload,

	pos = { 0, -listElementHeight },

	size = { viewElement.size.w, listElementHeight },

	bgColor = { 0, 0, 0, 1 },

	interactive = true

})



-- Adding quit button

local quitButton = UIElement:new({

	parent = topBar,

	pos = { -40, 0 },

	size = { 40, 40 },

	interactive = true,

	bgColor = { 1, 1, 1, 0.2 },

	hoverColor = { 1, 0.4, 1, 0.2 },

	pressedColor = { 1, 0, 0, 1 }

})

quitButton:addMouseHandlers(nil, function()

		viewElement:kill()

		remove_hooks("uiVisuals")

	end)



-- Spawning main view for the scrollable list. 

-- Height should be equal to parent element's height minus the sum of bars' height.

local listMainView = UIElement:new({

	parent = viewElement,

	pos = { 0, topBar.size.h },

	size = { viewElement.size.w, viewElement.size.h - topBar.size.h - botBar.size.h }

})



-- Spawning scrollable list holder element. 

-- Can have same size as its' parent, in this example width is smaller to leave place for a scrollbar.

local scrollableListHolder = UIElement:new({

	parent = listMainView,

	pos = { 0, 0 },

	size = { listMainView.size.w - 30, listMainView.size.h }

})



-- Calculating scrollbar scale

-- When dealing with dynamically generated tables, you may need to run additional checks.

local scrollScale = (listMainView.size.h) / (#list * listElementHeight)



-- Creating the scroll bar

-- First creating a holder object, then attaching a scrollbar object to it.

local listScrollView = UIElement:new({

	parent = listMainView,

	pos = { -30, 0 },

	size = { 30, listMainView.size.h }

})

local listScrollBar = UIElement:new({

	parent = listScrollView,

	pos = { 0, 0 },

	size = { listScrollView.size.w, listScrollView.size.h * scrollScale },

	interactive = true,

	bgColor = { 0, 0, 0, 0.3 },

	hoverColor = { 0, 0, 0, 0.5 },

	pressedColor = { 0, 0, 0, 0.2 },

	scrollEnabled = true

})



-- Populating the scrollable list with objects

-- First, creating a table to store all list elements, then spawning them one-by-one and adding to the table

local listElements = {}

for i,v in pairs(list) do

	local listElement = UIElement:new({

		parent = scrollableListHolder,

		pos = { 0, (i - 1) * listElementHeight },

		size = { scrollableListHolder.size.w, listElementHeight },

		interactive = true,

		bgColor = { 0, 0, 0, i % 2 == 0 and 0 or 0.1 },

		hoverColor = { 0, 0, 0, 0.3 },

		pressedColor = { 0, 0, 0, 0.4 },

	})

	listElement:addCustomDisplay(false, function()

			listElement:uiText(v)

		end)

	-- Hiding every object, ones that need to be made visible will be activated upon running makeScrollBar(...)

	listElement:hide()

	table.insert(listElements, listElement)

end





-- Calling makeScrollBar() method to make scrollable list

listScrollBar:makeScrollBar(scrollableListHolder, listElements, toReload, POS_SHIFT, 0.4)





-- Adding standard drawVisuals() function and hooks

local function drawVisuals()

	for i, v in pairs(UIElementManager) do

		v:updatePos()

	end

	for i, v in pairs(UIVisualManager) do

		v:display()

	end

end



add_hook("mouse_button_down", "uiMouseHandler", function(s, x, y) UIElement:handleMouseDn(s, x, y) end)

add_hook("mouse_button_up", "uiMouseHandler", function(s, x, y) UIElement:handleMouseUp(s, x, y) end)

add_hook("mouse_move", "uiMouseHandler", function(x, y) UIElement:handleMouseHover(x, y) end)

add_hook("draw2d", "uiVisuals", drawVisuals)

Viewport example script ►

Visual representation

Quick info: draw_viewport hook has been added in Toribash 5.23 and allows to draw 3d objects within a viewport. This won't work in earlier versions of Toribash.
As objects drawn within a viewport are three-dimensional, you would need to adapt pos table accordingly. As of April 30th, only spheres are supported - which means you'd need to use a numeric radius property when spawning viewport objects instead of size table. Rotation can be tweaked using a {xRot, yRot, zRot} rot table.
lua code:

dofile("toriui/uielement.lua")

dofile("system/player_info.lua")



-- Using player_info.lua to populate player info data table

PLAYER_INFO = {}

PLAYER_INFO.username = PlayerInfo:getUser()

PLAYER_INFO.items = PlayerInfo:getItems(PLAYER_INFO.username)



-- Creating quit() function to exit the script

local function quit()

	tbMenuUserBar:kill()

	remove_hooks("uiVisuals")

end



-- Function that creates the objects

local function createUserBar()

	-- Spawning primary parent object

	tbMenuUserBar = UIElement:new({

		pos = { WIN_W - 500, 0 },

		size = { 500, 100 },

		bgColor = UICOLORRED

	})

	

	-- Creating the viewport - pay attention to viewport = true property

	local tbMenuUserHeadAvatarViewport = UIElement:new( {

		parent = tbMenuUserBar,

		pos = { 0, 0 },

		size = { tbMenuUserBar.size.h, tbMenuUserBar.size.h },

		viewport = true

	})

	

	-- Creating the neck sphere with user's force color.

	-- Pay attention to number of elements within pos and rot tables.

	local color = get_color_info(PLAYER_INFO.items.colors.force)

	local tbMenuUserHeadAvatarNeck = UIElement:new({

		parent = tbMenuUserHeadAvatarViewport,

		pos = { 0, 0, 9.35 },

		rot = { 0, 0, 0 },

		radius = 0.6,

		bgColor = { color.r, color.g, color.b, 1 }

	})

	

	-- Creating the head sphere with user's head texture (if exists) and tori's head texture as default.

	-- Same as with neck object, pos and rot tables have three elements each.

	local headTexture = { "../../custom/tori/head.tga", "../../custom/tori/head.tga" }

	if (PLAYER_INFO.items.textures.head.equipped) then

		headTexture[1] = "../../custom/" .. TB_MENU_PLAYER_INFO.username .. "/head.tga"

	end

	local tbMenuUserHeadAvatar = UIElement:new({

		parent = tbMenuUserHeadAvatarViewport,

		pos = { 0, 0, 10 },

		rot = { 0, 0, 0 },

		radius = 1,

		bgColor = { 1, 1, 1, 1 },

		bgImage = headTexture

	})

	

	-- Creating quit button

	local quitButton = UIElement:new({

		parent = tbMenuUserBar,

		pos = { -200, 10 },

		size = { 180, tbMenuUserBar.size.h - 20 },

		interactive = true,

		bgColor = UICOLORGREEN,

		hoverColor = UICOLORBLACK,

		pressedColor = UICOLORBLUE

	})

	quitButton:addMouseHandlers(nil, quit)

end



-- Spawning objects

createUserBar()



-- Default drawVisuals() function for draw2d hook.

local function drawVisuals()

	for i, v in pairs(UIElementManager) do

		v:updatePos()

	end

	for i, v in pairs(UIVisualManager) do

		v:display()

	end

end



-- Default drawViewport() function for draw_viewport hook.

-- Similarly to drawVisuals(), cycles through every viewport object and displays it on screen.

local function drawViewport()

	for i, v in pairs(UIViewportManager) do

		v:displayViewport()

	end

end



-- Adding hooks

add_hook("mouse_button_down", "uiMouseHandler", function(s, x, y) UIElement:handleMouseDn(s, x, y) end)

add_hook("mouse_button_up", "uiMouseHandler", function(s, x, y) UIElement:handleMouseUp(s, x, y) end)

add_hook("mouse_move", "uiMouseHandler", function(x, y) UIElement:handleMouseHover(x, y) end)

add_hook("draw2d", "uiVisuals", drawVisuals)

add_hook("draw_viewport", "uiVisuals", drawViewport)

Bad script example ►

Visual representation

lua code:

dofile("toriui/uielement.lua")



local function loadMain()

	-- Redundant definitions for object properties that are nil / false by default

	local mainElement = UIElement:new({

		parent = nil,

		pos = { 100, 100 },

		size = { WIN_W - 200, WIN_H - 200 },

		bgColor = { 0, 0, 0, 0.2 },

		interactive = nil,

		hoverColor = nil,

		pressedColor = nil,

		hoverSound = nil,

		textfield = nil,

		scrollEnabled = nil,

		viewport = nil

	})

	mainElement:addCustomDisplay(false, function()

			mainElement:uiText("mainElement", nil, nil, 4, LEFT, nil, nil, nil, UICOLORBLACK)

		end)



	-- Despite having relative object position and size upon creation, childElement doesn't have a parent and thus won't be dependent on mainElement object

	local childElement = UIElement:new({

		pos = { mainElement.size.w / 4, mainElement.size.h / 4 },

		size = { mainElement.size.w / 2, mainElement.size.h / 2 },

		bgColor = UICOLORRED

	})

	childElement:addCustomDisplay(false, function()

			childElement:uiText("childElement", nil, nil, 4, LEFT, nil, nil, nil, UICOLORBLACK)

		end)



	local childElement2 = UIElement:new({

		parent = mainElement,

		pos = { 100, 200 },

		size = { 200, 100 },

		bgColor = UICOLORGREEN

	})

	childElement2:addCustomDisplay(false, function()

			childElement2:uiText("childElement2", nil, nil, 4, LEFT, nil, nil, nil, UICOLORBLACK)

		end)

	-- Despite the addMouseHandlers(...) call for childElement2 object, none of the passed functions would work because the object isn't interactive.

	childElement2:addMouseHandlers(function()

			echo("hello there")

		end, function()

			echo("general kenobi")

		end, nil)

end



local function loadMainQuitButton()

	-- Due to mainElement being a local object within loadMain() function, quitButton has an empty parent

	-- As a result, it is assigned an absolute 0, 0 position

	local quitButton = UIElement:new({

		parent = mainElement,

		pos = { 0, 0 },

		size = { 100, 50 },

		interactive = true,

		bgColor = UICOLORBLUE,

		hoverColor = UICOLORGREEN,

		pressedColor = UICOLORBLACK

	})

	-- Once again, due to mainElement being out of scope the kill() call would fail.

	-- Making mainElement a global variable would partially solve the issue and won't result in a 

	-- runtime error when pressing the quit button, but loadMain()'s childElement object will stay 

	-- loaded because there's no way to kill it due to it not having a parent object.

	quitButton:addMouseHandlers(nil, function()

			mainElement:kill()

			remove_hooks("uiVisuals")

		end)

	-- "Quit" string would be drawn before the default draw_quad() display function for the object which would keep it invisible to a user

	quitButton:addCustomDisplay(false, function()

			quitButton:uiText("Quit")

		end, true)

end



loadMain()

loadMainQuitButton()



local function drawVisuals()

	for i, v in pairs(UIElementManager) do

		v:updatePos()

	end

	for i, v in pairs(UIVisualManager) do

		v:display()

	end

end



add_hook("mouse_button_down", "uiMouseHandler", function(s, x, y) UIElement:handleMouseDn(s, x, y) end)

add_hook("mouse_button_up", "uiMouseHandler", function(s, x, y) UIElement:handleMouseUp(s, x, y) end)

add_hook("mouse_move", "uiMouseHandler", function(x, y) UIElement:handleMouseHover(x, y) end)

add_hook("draw2d", "uiVisuals", drawVisuals)

More examples may be added later.

UI Manager is included with new Toribash builds.
You can also get the newest version from GitHub.

Last edited by sir; Feb 11, 2020 at 08:00 AM. Reason: removed dark red color

Quote

« Previous Thread | Next Thread »

Log in / Register

Inventory

Market

Clans

Ranking

Merch

Inventory

Store

Market

Clans

Community

Ranking

Merch