Secret Santa 2024
Original Post
[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.


  • 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 "...".

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






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