1.02 Parts of a basic script

Calling the GUI library

First off, you're going to have run the GUI script and any classes you're planning to use. Lua doesn't care how you do it - requires, loadfile, copy/pasting the entire class file into your script... whatever works.

loadfile("Lokasenna_GUI/Core.lua")()
loadfile("Lokasenna_GUI/Classes/Class - Textbox.lua")()
loadfile("Lokasenna_GUI/Classes/Class - Slider.lua")()
loadfile("Lokasenna_GUI/Classes/Class - Button.lua")()

The script window and anchors

Next you set up the script window. This doesn't have to be done now; just make sure the values are set prior to calling GUI.Init. These values are passed directly to gfx.init, but GUI will hold on to them in case they're wanted later. For example, you might check to see if the window has been resized and then force it back to your original dimensions.

GUI.name = "My script's window"
GUI.x, GUI.y = 128, 128
GUI.w, GUI.h = 384, 96

You can also have the window positioned dynamically. "Centered on the mouse cursor" is always a popular choice:

GUI.anchor, GUI.corner = "mouse", "C"

Possible anchor settings are as follows. The corner strings refer to the corners and sides of the window - that is, "screen" and "TR" would place the window's top-right corner in the top-right corner of the screen.

	anchor	"screen" or "mouse"
	corner	"TL"
        "T"
        "TR"
        "R"
        "BR"
        "B"
        "BL"
        "L"
        "C"

In this case the x and y above are relative to the specified anchor oint.

Adding elements

Create all of your GUI elements. Only one parameter, [z], is actually required - the rest are up to individual classes. See the individual class pages for their parameters.

        name         class      z  x    y   w,  h,  caption     
GUI.New("my_txtbox", "Textbox", 1, 96,  28, 96, 20, "Track name:")

                                                                     min  max  steps  default
GUI.New("my_slider", "Slider",  1, 256, 32, 48,     "Track number:", 1,   10,  10,    1)

                                                                 function
GUI.New("my_button", "Button",  1, 160,  64, 64, 24, "Set name", set_track_name)

Note that the elements must be created via GUI.New in order for the GUI to properly track them. Don't call their :new methods directly.

Since this is Lua, creating elements can make use of whatever helper functions or variables you like. For instance, elements can use a common reference for coordinates to facilitate placing or moving them as a group:

local ref1 = {x = 32, y = 32}
GUI.New("my_txtbox", "Textbox", 1, ref1.x, ref1.y....
GUI.New("my_txtbox", "Textbox", 1, ref1.x, ref1.y + 24....
GUI.New("my_txtbox", "Textbox", 1, ref1.x, ref1.y + 48....

Elements can created at run-time as well.

Communicating with your script

Every element's state can be checked by name using GUI.Val.

local function set_track_name()
    local name = GUI.Val("my_txtbox")
    local num =  GUI.Val("my_slider")
    -- Do something with that information. Presumably renaming a track.
end

Changing the value of an element is just as simple - call GUI.Val with the new value as a parameter:

local function get_track_name()
    local name = ...get the current track's name somehow...
    GUI.Val("my_txtbox", name)
end

Each class will accept/return its value in a particular format. Some of the more adventurous classes will even accept multiple value types and sort it out for themselves. See each element's Class page.

Opening the window

GUI.Init()

...well that was underwhelming. To be fair, Init does set up a lot of stuff under the hood.

User functions

Lokasenna_GUI includes two hooks for your own functions to be run as part of the main loop.

GUI.func = my_function will be run on every update, or with a scheduled frequency (in seconds) by adding GUI.freq = 3 - the latter is probably a good idea if your functions are particularly CPU-intensive.

GUI.exit = save_my_data will be run when the script exits using reaper.atexit.

Starting the GUI

GUI.Main()

As described above, this will kick off the GUI library's logic and keep everything going until the user exits. Scripts can also request an early exit (after performing a one-time task, say) by setting GUI.quit = true.