LUA Functions

Object-Free API

AddFixtures Official Docs

Signature

AddFixtures({'mode'=light_userdata:dmx_mode, 'amount'=integer:amount[, 'undo'=string:undo_text][, 'parent'=light_userdata:handle][, 'insert_index'=integer:value][, 'idtype'=string:idtype][, 'cid'=string:cid][, 'fid'=string:fid][, 'name'=string:name][, 'layer'=string:layer][, 'class'=string:class][, 'patch'={table 1..8: string:address}]}): boolean:success or nothing

Description

The AddFixture Lua function adds fixtures to the patch. The argument for the function is a table, which must contain valid data for the function to succeed. The function returns a “true” boolean value if the addition was a success. The function must be run with the command line in the correct patch destination.

Arguments

{'mode'=light_userdata:dmx_mode, 'amount'=integer:amount[, 'undo'=string:undo_text][, 'parent'=light_userdata:handle][, 'insert_index'=integer:value][, 'idtype'=string:idtype][, 'cid'=string:cid][, 'fid'=string:fid][, 'name'=string:name][, 'layer'=string:layer][, 'class'=string:class][, 'patch'={table 1..8: string:address}]}:

Returns

boolean: success or nothing

Example

This example adds a dimmer fixture with FID and CID 301 and patch address “10.001”. It is a requirement that the generic dimmer type is already added to the show, that the ID and patch address are available, and that the stage is called “Stage 1”. The example does not perform any check for availability.

return function()
    -- Change the command line destination to the root.
    Cmd("ChangeDestination Root")
    -- Enter the "Patch".
    Cmd('ChangeDestination "ShowData"."Patch"')
    -- Enter the fixture location for the "Stage 1" object.
    Cmd('ChangeDestination "Stages"."Stage 1"."Fixtures"')

    -- Create a table.
    local myAddFixtureTable = {}
    -- Set the mode to a 8-bit Dimmer fixture type.
    myAddFixtureTable.mode = Patch().FixtureTypes.Dimmer.DMXModes["Mode 0"]
    -- Set the amount of fixtures.
    myAddFixtureTable.amount = 1
    -- Set the FID for the fixture.
    myAddFixtureTable.fid = "301"
    -- Set the IdType - it is not needed if the type is "Fixture".
    myAddFixtureTable.idtype = "Channel"
    -- Set the CID - Use only this when the "idtype" is different than Fixture.
    myAddFixtureTable.cid = "301"
    -- Set the name of the fixture.
    myAddFixtureTable.name = "AddedDimmer 301"
    -- Create a patch table with an address.
    myAddFixtureTable.patch = {"10.001"}

    -- Add the fixture to the patch using the table data. Store the result in a local variable.
    local success = AddFixtures(myAddFixtureTable)

    -- Provide some feedback.
    if success ~= nil then
        Printf("Fixture " .. myAddFixtureTable.fid .. " is added with patch address " .. myAddFixtureTable.patch[1])
    else
        Printf("AddFixture failed!")
    end

    -- Return the command line to the root destination.
    Cmd("ChangeDestination Root")
end

AddonVars Official Docs

Signature

AddonVars(string:addon_name): light_userdata:addon_variables

Description

The AddonVars function returns a handle to the set of variables connected to a specific addon.

Arguments

string: addon_name

Returns

light_userdata: addon_variables

Example

This example prints information connected to the “Demo” addon variable set. It uses the Dump() function:

return function()
    -- Stores the handle to a variable set connected to the addon named 'Demo'.
    local variableSet = AddonVars("Demo")
    -- Check if the return is nil and print an error message
    if variableSet == nil then
        ErrPrintf("The variable set does not exists")
        return
    end
    Printf("=============== START OF DUMP ===============")
    variableSet:Dump()
    Printf("================ END OF DUMP ================")
end

BuildDetails Official Docs

Signature

BuildDetails(nothing): table:build_details

Description

The BuildDetails function returns a table with key-value pairs about the software build.

Arguments

No Arguments

Returns

table: build_details

Example

This example prints the content of the BuildDetails table:

return function()
    --Store the build detials table
    local myBuild = BuildDetails()
    --Print the content of the table
    Printf("GitDate: " .. myBuild.GitDate)
    Printf("GitHead: " .. myBuild.GitHead)
    Printf("GitHash: " .. myBuild.GitHash)
    Printf("CompileDate: " .. myBuild.CompileDate)
    Printf("CompileTime: " .. myBuild.CompileTime)
    Printf("BigVersion: " .. myBuild.BigVersion)
    Printf("SmallVersion: " .. myBuild.SmallVersion)
    Printf("HostType: " .. myBuild.HostType)
    Printf("HostSubType: " .. myBuild.HostSubType)
    Printf("CodeType: " .. myBuild.CodeType)
    Printf("IsRelease: " .. tostring(myBuild.IsRelease))
end

CallRealtimeLockedProtected New

Signature

CallRealtimeLockedProtected(function:name): result of function

Arguments

function: name

Returns

result of function:

ChannelTable New

Signature

ChannelTable(string:attribute_name or integer:attribute_index): table of ui_channel_index

Arguments

string: attribute_name or integer:attribute_index

Returns

table of ui_channel_index:

CheckDMXCollision Official Docs

Signature

CheckDMXCollision(light_userdata:dmx_mode, string:dmx_address[ ,integer:count[ ,integer:break_index]]): boolean:no_collision_found

Description

The CheckDMXCollision Lua function checks if a specific DMX address range is available or already used.

Arguments

light_userdata: dmx_mode
string: dmx_address
integer (optional): count
integer (optional): break_index

Returns

boolean: no_collision_found

Example

This example prints feedback to the DMX collision check based on a DMX address of “1.001” and the DMX mode of the first fixture in the current selection:

return function()
    -- Set the DMX universe - range 1-1024.
    local myDMXUniverse = 1
    -- Set the DMX address in the universe - range 1-512.
    local myDMXAddress = 1
    -- Set the optional count for the number of fixtures (break_index channel amount) to check.
    local myCount = 1
    -- Set the optional break_index number for fixtures with multiple breaks.
    -- Default value is 0 to indicate the first break.
    local myBreakIndex = 0

    -- Creates the string used for the DMX address.
    local startOfRange = string.format("%d.%03d", myDMXUniverse, myDMXAddress)

    -- Check if there is a selection and exit if there isn't.
    if SelectionFirst() == nil then
        Printf("Please make a selection and try again.")
        return
    end
    -- This gets the handle for the first fixture a patched generic Dimmers 8-bit mode.
    local myDmxMode = GetSubfixture(SelectionFirst()).ModeDirect

    if myDmxMode == nil then
        -- Exit the function if the DMX mode returns nil.

    else
        -- Do the actual collision check and provide useful feedback.
        if CheckDMXCollision(myDmxMode, startOfRange, myCount, myBreakIndex) then
            Printf("The DMX address " .. startOfRange .. " is available.")
            return
        else
            Printf("The DMX address " .. startOfRange .. " cannot be used as a start address for this patch.")
            return
        end
    end
end

CheckFIDCollision Official Docs

Signature

CheckFIDCollision(integer:fid[, integer:count[, integer:type]]): boolean:no_collision_found

Description

The CheckFIDCollision Lua function checks if a specific (range of) ID is available or already used. It can be used to check FID and any type of CID by adding a type integer.

Arguments

integer: fid
integer (optional): count
integer (optional): type

Returns

boolean: no_collision_found

Example

This example prints feedback to the FID check:

return function()
    -- Create a variable with the FID you want to check.
    local myFID = 2001
    -- Create a variable with the number of subsequent ID's to also check.
    local myCount = 10
    -- Create a variable with the IDType you want to check.
    -- Default value is 0. This is the "Fixture" type.
    -- Valid integers are:
    --- 0 = Fixture
    --- 1 = Channel
    --- 2 = Universal
    --- 3 = Houseligths (default name)
    --- 4 = NonDim (default name)
    --- 5 = Media (default name)
    --- 6 = Fog (default name)
    --- 7 = Effect (default name)
    --- 8 = Pyro (default name)
    --- 9 = MArker
    --- 10 = Multipatch
    local myType = 0

    -- Check if the count is more than one.
    if myCount > 1 then
        -- Check if there is a collision and print valid feedback.
        if CheckFIDCollision(myFID, myCount, myType) then
            Printf("The FID " .. myFID .. " to " .. (myFID + myCount) .. " is available.")
            return
        else
            Printf("The FID " .. myFID .. " to " .. (myFID + myCount) .. " gives an FID collision.")
            return
        end
    else
        if CheckFIDCollision(myFID, nil, myType) then
            Printf("The FID " .. myFID .. " is available.")
            return
        else
            Printf("The FID " .. myFID .. " gives an FID collision.")
            return
        end
    end
end

ClassExists Official Docs

Signature

ClassExists(string:class_name): boolean:result

Description

The ClassExists Lua function returns a boolean indicating whether the provided string is a class.

Arguments

string: class_name

Returns

boolean: result

Example

This example asks if the word “Display” is a class and returns proper feedback.

return function()
    -- Store a string with the class name
    local className = "Display"
    -- Check if the class exists and then provide proper feedback
    if ClassExists(className) then
        Printf("The class '%s' exists", className)
    else
        Printf("The class '%s' does not exists", className)
    end
end

CloseAllOverlays Official Docs

Signature

CloseAllOverlays(nothing): nothing

Description

The CloseAllOverlays function closes any pop-ups or menus (overlays) open on any screen.

Arguments

No Arguments

Returns

No Return

Example

This example simply closes any overlay.

return function()
    CloseAllOverlays()
end

CloseMessageQueue

Signature

CloseMessageQueue(string:queue name): boolean:success

Arguments

string: queue name

Returns

boolean: success

CloseUndo Official Docs

Signature

CloseUndo(light_userdata:undo_handle): boolean:closed (true if was closed, false - if it's still in use)

Description

The CloseUndo Lua function closes an open undo list. The function returns a boolean indicating if the function succeeds.

Arguments

light_userdata: undo_handle

Returns

boolean: closed (true if was closed, false - if it’s still in use)

Example

This example creates an undo list, performs a series of commands that are added to the undo list, and closes the undo list. Now the series of commands can be oopsed with one oops command.

return function()
    --Create the undo object
    local MyNewUndo = CreateUndo("MySelection")
    --Create command actions connected to the undo object
    Cmd("ClearAll", MyNewUndo)
    Cmd("Fixture 1", MyNewUndo)
    Cmd("Fixture 2", MyNewUndo)
    Cmd("Fixture 5", MyNewUndo)
    Cmd("Fixture 7", MyNewUndo)
    --Close the undo group and store it's return in a variable
    local closeSuccess = CloseUndo(MyNewUndo)
    --Print the feedback from the closing action - 1 = Success / 0 = Failure.
    if closeSuccess == false then
        ErrPrintf("The CloseUndo was not successful")
    elseif closeSuccess == true then
        Printf("The CloseUndo was successful")
    else
        Printf("The CloseUndo did not return a meaningful result")
    end
end

Cmd Official Docs

Signature

Cmd(string:formatted_command[ ,light_userdata:undo], ...): string:command_execution_result ('Ok', 'Syntax Error', 'Illegal Command', ...)

Description

The Cmd Lua function executes a command in the grandMA3 command line. It is executed in a Lua task - not the Main task (standard typed commands are run in the Main task). It is executed synchronously, and it blocks the Lua task while executing. This means that a bad command has the potential to block the system.

Arguments

string: formatted_command
light_userdata (optional): undo
...:

Returns

string: command_execution_result (‘Ok’, ‘Syntax Error’, ‘Illegal Command’, …)

Example

This example executes the command “ClearAll” in the command line.

return function()
    --Execute the command directly
    Cmd("ClearAll")
end

CmdIndirect Official Docs

Signature

CmdIndirect(string:command[, light_userdata:undo[, light_userdata:target]]): nothing

Description

The CmdIndirect Lua function executes a command within the grandMA3 command line. It is executed asynchronously in the Main task. It does not block the Lua execution since it is not executed in the Lua Task.

Arguments

string: command
light_userdata (optional): undo
light_userdata (optional): target

Returns

No Return

Example

This example prints “1” and “2” in the Command Line History and let the main task open the Configure Display pop-up on screen 2.

return function()
    --Print something
    Printf("1")
    --Use the 'CmdIndirect' to open a pop-up
    CmdIndirect("Menu DisplayConfig", nil, GetDisplayByIndex(2))
    --Print something else
    Printf("2")
end

CmdIndirectWait Official Docs

Signature

CmdIndirectWait(string:command[, light_userdata:undo[, light_userdata:target]]): nothing

Description

The CmdIndirectWait Lua function executes a command within the grandMA3 command line. It does not block the Lua execution and is executed synchronously in the main task. Synchronous commands wait for the command to be executed before executing any following command.

Arguments

string: command
light_userdata (optional): undo
light_userdata (optional): target

Returns

No Return

Example

This example prints “1” and “2” in the Command Line History and lets the main task open the Configure Display pop-up on screen 2.

return function()
    --Print something
    Printf("1")
    --Use the 'CmdIndirectWait' to open a pop-up
    CmdIndirectWait("Menu DisplayConfig", nil, GetDisplayByIndex(2))
    --Print something else
    Printf("2")
end

CmdObj Official Docs

Signature

CmdObj(nothing): light_userdata:handle

Description

The CmdObj Lua function returns information about the command line object.

Arguments

No Arguments

Returns

light_userdata: handle

Example

This example uses the Dump() function on the command object. It lists all the properties and lists the children and some extra examples of how the command line object can be used:

return function()
    --Store the handle to the command object
    local cmd = CmdObj()
    --Print all information about the command object
    Printf("=============== START OF DUMP ===============")
    cmd:Dump()
    Printf("================ END OF DUMP ================")
    --Print some selected elements from the command object - this is currently not in the online manual
    Printf("Current text in the command line: " ..cmd.cmdtext)
    Printf("Current cmd edit object: " ..tostring(cmd.editobject and cmd.editobject:ToAddr()))
    Printf("Current cmd destination: " ..tostring(cmd.destination and cmd.destination:ToAddr()))
    Printf("Current user of the command line: " ..tostring(cmd.user and cmd.user:ToAddr()))
    Printf("Current profile of the command line: " ..tostring(cmd.profile and cmd.profile:ToAddr()))
    Printf("Current DMX readout: " ..cmd.dmxreadout)
    Printf("Current amount steps: " ..cmd.maxstep)
    Printf("Current selected object: " ..tostring(cmd:GetSelectedObject() and cmd:GetSelectedObject():ToAddr()))
end

ColMeasureDeviceDarkCalibrate

Signature

ColMeasureDeviceDarkCalibrate(nothing): integer:flag

Arguments

No Arguments

Returns

integer: flag

ColMeasureDeviceDoMeasurement

Signature

ColMeasureDeviceDoMeasurement(nothing): table:values

Arguments

No Arguments

Returns

table: values

ConfigTable Official Docs

Signature

ConfigTable(nothing): table:config_details

Description

The ConfigTable Lua function returns a table with some configuration information. This is information only. The function does not have any actual functions. The table is not sorted.

Arguments

No Arguments

Returns

table: config_details

Example

This example prints the content of the returned table.

return function ()
    -- Prints the content of the ConfigTable
    for key,value in pairs(ConfigTable()) do
        Printf(key .. " : " .. value)
    end
end

Confirm Official Docs

Signature

Confirm([string:title [,string:message [,integer:display_index [,boolean:showCancel]]]]): boolean:result

Description

The Confirm Lua function provides a simple confirmation pop-up for a true/false query. It is part of the user interface functions.

Arguments

string (optional): title
string (optional): message
integer (optional): display_index
boolean (optional): showCancel

Returns

boolean: result

Example

This example creates a confirmation pop-up with printed feedback in the Command Line History:

return function()
    --Creates a pop-up asking to be confirmed and prints a useful text.
    if Confirm("Confirm me", "Tap OK or Cancel", nil, true) then
        Printf("Pop-up result: OK")
    else
        Printf("Pop-up result: Cancel")
    end
end

CopyFile

Signature

CopyFile(string:source_path, string:destination_path): boolean:result

Arguments

string: source_path
string: destination_path

Returns

boolean: result

CreateDirectoryRecursive

Signature

CreateDirectoryRecursive(string:path): boolean:result

Arguments

string: path

Returns

boolean: result

CreateMultiPatch Official Docs

Signature

CreateMultiPatch({light_userdata:fixture_handles}, integer:count[ ,string:undo_text]): integer:amount_of_multi-patch_fixtures_created

Description

The CreateMultiPatch Lua function creates a series of multi patch fixtures to a table of fixtures.

Arguments

{light_userdata:fixture_handles}:
integer: count
string (optional): undo_text

Returns

integer: amount_of_multi-patch_fixtures_created

Example

This example creates two multi patch fixtures to the first fixture (excluding the “Universal” fixture) in the patch.

return function()
    -- Enter Patch.
    Cmd("ChangeDestination Root");
    -- Enter the SetupPatch.
    Cmd("ChangeDestination 'ShowData'.'Patch'");

    -- Get the handle for the first fixture in the patch.
    local myFixture = Patch().Stages[1].Fixtures[2]
    -- Add the handle a list element in an table.
    local myFixtureTable = {myFixture}
    -- Add a variable with the amount of multipatch fixtures needed.
    local multiPatchAmount = 2

    -- Count the number of elements in the fixture table and store in a variable.
    local count = 0
    for _ in pairs(myFixtureTable) do
         count = count + 1
    end
    -- Create an unto text string.
    local undoText = string.format("Create %d multipatch fixtures for up to %d fixtures", multiPatchAmount, count)

    -- Create the multipatch fixtures to the each fixture handle in the table and store the returned value.
    local multiPatchAmount = CreateMultiPatch(myFixtureTable, multiPatchAmount, undoText)
    if multiPatchAmount ~= nil then
        Printf(multiPatchAmount .. " multi patch objects was created")
    else
        Printf("An error occured")
    end

    -- Return the command line destination to the root.
    Cmd("ChangeDestination Root")
end

CreateUndo Official Docs

Signature

CreateUndo(string:undo_text): light_userdata:undo_handle

Description

The CreateUndo Lua function returns a handle to a list of commands and function calls grouped in the same oops action.

Arguments

string: undo_text

Returns

light_userdata: undo_handle

Example

This example creates an undo list, performs a series of commands being added to the undo list, and closes the undo list. Now, the series of commands can be oopsed with one oops command.

return function()
    -- Create the undo group.
    local MyNewUndo = CreateUndo("MySelection")
    -- Make some command line actions linked to the undo.
    Cmd("ClearAll", MyNewUndo)
    Cmd("Fixture 1", MyNewUndo)
    Cmd("Fixture 2", MyNewUndo)
    Cmd("Fixture 5", MyNewUndo)
    Cmd("Fixture 7", MyNewUndo)
    -- Closing the undo group and store it's return in a variable.
    local closeSuccess = CloseUndo(MyNewUndo)
    -- Print the feedback from the closing action - 1 = Success / 0 = Failure.
    if closeSuccess == false then
        ErrPrintf("The CloseUndo was not successful")
    elseif closeSuccess == true then
        Printf("The CloseUndo was successful")
    else
        Printf("The CloseUndo did not return a meaningful result")
    end
end

CurrentEnvironment Official Docs

Signature

CurrentEnvironment(nothing): light_userdata:handle

Description

The CurrentEnvironment Lua function returns a handle to the current users’ selected environment.

Arguments

No Arguments

Returns

light_userdata: handle

Example

This example prints the data connected to the handle. It uses the Dump() function:

return function()
    -- Dumps information about the current environment
    Printf("=============== START OF DUMP ===============")
    CurrentEnvironment():Dump()
    Printf("================ END OF DUMP ================")
end

CurrentExecPage Official Docs

Signature

CurrentExecPage(nothing): light_userdata:handle

Description

The CurrentEnvironment Lua function returns a handle to the current users’ selected executor page.

Arguments

No Arguments

Returns

light_userdata: handle

Example

This example prints the data connected to the handle. It uses the Dump() function:

return function()
    -- Dumps information about the current executor page
    Printf("=============== START OF DUMP ===============")
    CurrentExecPage():Dump()
    Printf("================ END OF DUMP ================")
end

CurrentProfile Official Docs

Signature

CurrentProfile(nothing): light_userdata:handle

Description

The CurrentProfile Lua function returns a handle to the current users’ profile.

Arguments

No Arguments

Returns

light_userdata: handle

Example

This example prints the data connected to the handle. It uses the Dump() function:

return function()
    -- Dumps information about the current executor page
    Printf("=============== START OF DUMP ===============")
    CurrentProfile():Dump()
    Printf("================ END OF DUMP ================")
end

CurrentScreenConfig Official Docs

Signature

CurrentScreenConfig(nothing): light_userdata:handle

Description

The CurrentScreenConfig Lua function returns a handle to the current users’ screen configuration.

Arguments

No Arguments

Returns

light_userdata: handle

Example

This example prints the data connected to the handle. It uses the Dump() function:

return function()
    -- Dumps information about the current screen configuration
    Printf("=============== START OF DUMP ===============")
    CurrentScreenConfig():Dump()
    Printf("================ END OF DUMP ================")
end

CurrentUser Official Docs

Signature

CurrentUser(nothing): light_userdata:handle

Description

The CurrentUser Lua function returns a handle to the current user.

Arguments

No Arguments

Returns

light_userdata: handle

Example

This example prints the data connected to the handle. It uses the Dump() function:

return function()
    -- Dumps information about the current user
    Printf("=============== START OF DUMP ===============")
    CurrentUser():Dump()
    Printf("================ END OF DUMP ================")
end

DataPool Official Docs

Signature

DataPool(nothing): light_userdata:handle

Description

The DataPool Lua function references the currently selected DataPool and is used to read or edit properties within the data pool.

Arguments

No Arguments

Returns

light_userdata: handle

Example

This example uses the Dump() function on the data pool object. Dump lists all the properties and lists the children. Finally, the example also prints the name of the first sequence in the data pool.

return function()
    -- Dumps information about the datapool object.
    Printf("=============== START OF DUMP ===============")
    DataPool():Dump()
    Printf("================ END OF DUMP ================")
    -- Prints the name of the first sequence.
    Printf("Name of sequence 1: " .. DataPool().Sequences[1].Name)
end

DefaultDisplayPositions Official Docs

Signature

DefaultDisplayPositions(nothing): light_userdata:handle

Description

The DefaultDisplayPositions Lua function returns the handle of the conventional default display positions, which contains the first seven screens as children.

Arguments

No Arguments

Returns

light_userdata: handle

Example

This example prints all the information about display 1 (child 1 of the default displays) using the Dump() function:

return function()
    -- Store a handle to display 1 (child 1 of the default displays).
    local display1 = DefaultDisplayPositions():Children()[1]
    -- Dumps information about the display.
    Printf("=============== START OF DUMP ===============")
    display1:Dump()
    Printf("================ END OF DUMP ================")
end

DelVar Official Docs

Signature

DelVar(light_userdata:variables, string:varname): boolean:success

Description

The DelVar Lua function deletes a specific variable in a set of variables. To learn more about the variables in plugins, have a look at the Variable Functions topic.

Arguments

light_userdata: variables
string: varname

Returns

boolean: success

Example

This example deletes a variable called “myUserVar” in the set of user variables.

return function()
    -- Deletes the variable called 'myUserVar' in the 'UserVars' variable set.
    local success = DelVar(UserVars(), "myUserVar")
    -- Prints the outcome of the deletion outcome.
    if success then
        Printf("Variable is deleted.")
    else
        Printf("Variable is NOT deleted!")
    end
end

DeskLocked Official Docs

Signature

DeskLocked(nothing): boolean:desk_is_locked

Description

The DeskLocked Lua function returns a boolean indicating if the station is locked.

Arguments

No Arguments

Returns

boolean: desk_is_locked

Example

This example prints the boolean number indicating the “DeskLocked” status to the Command Line History.

return function()
    -- The DeskLocked() return is printed.
    Printf("The desk is locked: " .. tostring(DeskLocked()))
end

DeviceConfiguration Official Docs

Signature

DeviceConfiguration(nothing): light_userdata:handle

Description

The DeviceConfiguration Lua function returns a handle to the DeviceConfiguration object.

Arguments

No Arguments

Returns

light_userdata: handle

Example

This example prints the data connected to the handle. It uses the Dump() function:

return function()
    -- This example dumps all information about the DeviceConfiguration object.
    Printf("=============== START OF DUMP ===============")
    DeviceConfiguration():Dump()
    Printf("================ END OF DUMP ================")
end

DevMode3d

Signature

DevMode3d(nothing): string:devmode3d

Arguments

No Arguments

Returns

string: devmode3d

DirList Official Docs

Signature

DirList(string:path[ ,string:filter]): table of {name:string, size:int, time:int}

Description

The DirList Lua function returns a table of files at a specified path. The returned list can be filtered using an optional filter argument.

Arguments

string: path
string (optional): filter

Returns

table of {name:string, size:int, time:int}:

Example

This example prints the show files in the showfile directory. It uses the GetPath() function.

return function ()
    -- Get the path to the show files.
    local path = GetPath(Enums.PathType.Showfiles)
    -- Make a filter to only list .show files.
    local filter = "*show"
    -- Use the DirList function to get a table of the files.
    local returnTable = DirList(path, filter)

    -- Print the information of the files in the returned table.
    for _, value in pairs(returnTable) do
        Printf(value['name'] .. " - Size: " .. value['size'] .. " bytes - Time: " .. os.date("%c", value['time']))
    end
end

DrawPointer Official Docs

Signature

DrawPointer(integer:display_index, {x=integer:x_position,y=integer:y_position}, integer:duration in ms)): nothing

Description

The DrawPointer function draws a red pointer on the display. There can only be one pointer at a time on each station.

Arguments

integer: display_index
{x=integer:x_position,y=integer:y_position}:
integer: duration in ms)

Returns

No Return

Example

This example draws a pointer on display 1 for 5 seconds:

return function()
    --Set a display index
    local displayIndex = 1
    --Create and set the position in a table
    local position = {}
    position.x = 150
    position.y = 25
    --Set a 5 seconds duration - in milliseconds
    local duration = 5000
    --Draw the actual pointer
    DrawPointer(displayIndex,position,duration)
end

DumpAllHooks Official Docs

Signature

DumpAllHooks(nothing): nothing

Description

The DumpAllHooks function prints a list of the hooks in the system. The list is only shown in the System Monitor.

Arguments

No Arguments

Returns

No Return

Example

This example prints the list of hooks in the system monitor.

return function()
    -- Dumps a list of all the hooks in the System Monitor.
    Printf("=============== START OF HOOK DUMP ===============")
    DumpAllHooks()
    Printf("================ END OF HOOK DUMP ================")
end

Echo Official Docs

Signature

Echo(string:formatted_command ...): nothing

Description

The Echo Lua function prints a string in the System Monitor.

Arguments

string: formatted_command …

Returns

No Return

Example

This example prints “Hello World!” on the System Monitor:

return function()
    -- Prints 'Hellow World!' in the system monitor in yellow text.
    Echo("Hello World!")
end

ErrEcho Official Docs

Signature

ErrEcho(string:formatted_command ...): nothing

Description

The ErrEcho Lua function prints a red error message on the System Monitor.

Arguments

string: formatted_command …

Returns

No Return

Example

This prints “This is a red error message!” on the system monitor:

return function()
    -- Prints an error message in the system monitor in red text.
    ErrEcho("This is an error message!")
end

ErrPrintf Official Docs

Signature

ErrPrintf(string:formatted_command ...): nothing

Description

The ErrPrintf Lua function prints a red error message in the Command Line History and System Monitor.

Arguments

string: formatted_command …

Returns

No Return

Example

This example prints “This is a red error message!” in the Command Line History and System Monitor:

return function()
    -- Prints an error message in the command line feedback in red text.
    ErrPrintf("This is an error message!")
end

Export Official Docs

Signature

Export(string:file_name, table:export_data): boolean:success

Description

The object-free Export Lua function exports a Lua table in XML format.

Arguments

string: file_name
table: export_data

Returns

boolean: success

Example

To export the build details table, create a plugin with this code:

return function()
    -- 'BuildDetails()' creates a table with information about the software build.
    local build = BuildDetails()
    --The path and filename is stored in a variable.
    local exportPath = GetPath(Enums.PathType.Library) .. "/BuildDetails.xml"
    --The actual export (in xml format) using the path and the table - the result boolean stored in a variable.
    local success = Export(exportPath, build)
    --Print feedback about the export path.
    if success then
        Printf("The export was stored at: " .. exportPath)
    else
        Printf("The export failed")
    end
end

ExportCSV Official Docs

Signature

ExportCSV(string:file_name, table:export_data): boolean:success

Description

The object-free ExportCSV Lua function exports a Lua table in CSV format.

Arguments

string: file_name
table: export_data

Returns

boolean: success

Example

To export the build details table, create a plugin with this code:

return function()
    -- 'BuildDetails()' creates a table with information about the software build.
    local build = BuildDetails()
    --The path and filename is stored in a variable.
    local exportPath = GetPath(Enums.PathType.Library) .. "/BuildDetails.csv"
    --The actual export (in csv format) using the path and the table - the result boolean stored in a variable.
    local success = ExportCSV(exportPath, build)
    --Print feedback about the export path.
    if success then
        Printf("The export was stored at: " .. exportPath)
    else
        Printf("The export failed.")
    end
end

ExportJson Official Docs

Signature

ExportJson(string:file_name, table:export_data): boolean:success

Description

The object-free ExportJson Lua function exports a Lua table in JSON format.

Arguments

string: file_name
table: export_data

Returns

boolean: success

Example

To export the build details table, create a plugin with this code:

return function()
    -- 'BuildDetails()' creates a table with information about the software build.
    local build = BuildDetails()
    --The path and filename is stored in a variable.
    local exportPath = GetPath(Enums.PathType.Library) .. "/BuildDetails.json"
    --The actual export (in JSON format) using the path and the table - the result boolean stored in a variable.
    local success = ExportJson(exportPath, build)
    --Print feedback about the export path.
    if success then
        Printf("The export was stored at: " .. exportPath)
    else
        Printf("The export failed.")
    end
end

FileExists Official Docs

Signature

FileExists(string:path): boolean:result

Description

The FileExists Lua function checks if a file exists and returns a boolean with the result.

Arguments

string: path

Returns

boolean: result

Example

This example returns feedback for the first file in the show file folder. The example uses the GetPath() and DirList() functions.

return function ()
    -- Get the path to the show files.
    local path = GetPath(Enums.PathType.Showfiles)
    -- Get a table of files at the path.
    local dirTable = DirList(path)
    -- Get the file name for the first file.
    local firstFile = dirTable[1]['name']
    -- Create a string with the path and filename.
    local filepath = string.format("%s%s%s", path, GetPathSeparator(), firstFile)

    -- Check if the file exist and return useful feedback.
    if FileExists(filepath) then
        Printf('The file "' .. firstFile .. '" exist at path "' .. path .. '"')
    else
        Printf('The file "' .. firstFile .. '" does not exist')
    end
end

FindBestDMXPatchAddr

Signature

FindBestDMXPatchAddr(light_userdata:patch, integer:starting_address, integer:footprint): integer:absolute_address

Arguments

light_userdata: patch
integer: starting_address
integer: footprint

Returns

integer: absolute_address

FindBestFocus

Signature

FindBestFocus([light_userdata:handle]): nothing

Arguments

light_userdata (optional): handle

Returns

No Return

FindNextFocus

Signature

FindNextFocus([bool:backwards(false)[, int(Focus::Reason):reason(UserTabKey)]]): nothing

Arguments

bool (optional): backwards(false)
int(Focus::Reason) (optional): reason(UserTabKey)

Returns

No Return

FindTexture Official Docs

Signature

FindTexture(string:texture name): light_userdata:handle to texture found

Description

The FindTixture Lua function returns a handle to the texture matching the input text string - if the texture exists.

Arguments

string: texture name

Returns

light_userdata: handle to texture found

Example

This example prints the information about the “button” texture. The example uses the Dump() function.

return function ()
    -- Set a texture name.
    local textureName = "button"
    -- Get the handle of the texture.
    local textureHandle = FindTexture(textureName)
    -- Check if textureHandle returned something and provide feedback.
    if textureHandle == nil then
        ErrPrintf("Texture does not exist.")
    else
        Printf("=============== START OF DUMP ===============")
        FindTexture(textureName):Dump()
        Printf("================ END OF DUMP ================")
    end
end

FirstDmxModeFixture Official Docs

Signature

FirstDmxModeFixture(light_userdata:dmxmode): light_userdata:fixture

Description

The FirstDmxModeFixture Lua function returns a handle to the first fixture matching the supplied DMX mode.

Arguments

light_userdata: dmxmode

Returns

light_userdata: fixture

Example

If it exists, this example prints the data connected to the first “Dimmer” fixture using “Mode 0” - if the fixture type exists in the show. It uses the Dump() functions:

return function ()
    -- Get the handle for the Dimmer fixture.
    local fixtureTypeHandle = Patch().FixtureTypes['Dimmer']

    -- Check if fixture type returned something and provide feedback.
    if fixtureTypeHandle == nil then
        ErrPrintf("The fixture type does not exist in this show. Try adding it or edit this plugin.")
    else
        -- Get the handle for the DMX mode of a Dimmer fixture.
        local fixtureDMXMode = fixtureTypeHandle.DMXModes["Mode 0"]

        -- Check if fixtureDMXMode returned something and provide feedback.
        if fixtureDMXMode == nil then
            ErrPrintf("The fixture type does not contain a 'Mode 0' DMX mode. Try adding it or edit this plugin.")
        else
            -- Dumps information about the first fixture matching the DMX mode.
            Printf("=============== START OF DUMP ===============")
            FirstDmxModeFixture(fixtureDMXMode):Dump()
            Printf("================ END OF DUMP ================")
        end
    end
end

FixtureType Official Docs

Signature

FixtureType(nothing): light_userdata:handle

Description

The FixtureType Lua function returns a handle to the fixture type. The function does not accept any arguments, but the function must be executed when the command line destination is at a fixture type. If the command line destination is not a valid fixture type, then the function returns “nil”.

Arguments

No Arguments

Returns

light_userdata: handle

Example

This example prints the information about the second fixture type in the show:

return function ()
    -- The function returns the handle to the fixture at the current command line destination.
    -- Change to the "FixtureType" destination.
    Cmd("ChangeDestination FixtureType")
    -- Change to the second fixture type in the show.
    Cmd("ChangeDestination 2")
    -- Dump information about the Fixture Type handle.
    Printf("=============== START OF DUMP ===============")
    FixtureType():Dump()
    Printf("================ END OF DUMP ================")
    -- Return the command line destination to the Root.
    Cmd("ChangeDestination Root")
end

FromAddr Official Docs

Signature

FromAddr(string:address[, light_userdata:base_handle]): light_userdata:handle

Description

The FromAddr Lua function converts a numbered string address into a handle that can be used in commands.

Arguments

string: address
light_userdata (optional): base_handle

Returns

light_userdata: handle

Example

This example prints the address of the first sequence:

return function()
    -- Converts the string to a handle and store in a variabel.
    local mySequenceHandle = FromAddr("14.14.1.6.1")
    -- Converts the handle back to a numbered string and prints it.
    Printf("The address is: " ..mySequenceHandle:Addr())
    -- Converts the handle to a named string and prints it.
    Printf("The address is: " ..mySequenceHandle:AddrNative())

    -- Store the handle of the selected datapool.
    local myDataPool = DataPool()
    -- Prints the address of the selected datapool.
    Printf("The datapool address is: " ..myDataPool:Addr())

    --- The follwoing example uses the name of a sequence in the sequence pool.
    --- Please adjust the "Default" name in the next line to match an existing named sequence.
    -- Finds the address based on the base location and a text string with names.
    local alsoMySequenceHandle = FromAddr("Sequences.Default", myDataPool)
    -- Converts the handle back to a numbered string and prints it.
    Printf("The address is: " ..alsoMySequenceHandle:Addr())
    -- Converts the handle to a named string and prints it.
    Printf("The address is: " ..alsoMySequenceHandle:AddrNative())
end

FSExtendedModeHasDots

Signature

FSExtendedModeHasDots(light_userdata:handle to UIGrid (or derived), {r, c}:cell): boolean

Arguments

light_userdata: handle to UIGrid (or derived)
{r, c}: cell

Returns

boolean:

GetApiDescriptor Official Docs

Signature

GetApiDescriptor(nothing): table of {string:function_name, string:arguments, string:return_values}

Description

The GetApiDescriptor Lua function returns a table with a description of all the object-free Lua functions. These are descriptions only. The function does not have any actual functions. The table is not sorted.

Arguments

No Arguments

Returns

table of {string:function_name, string:arguments, string:return_values}:

Example

This example prints the content of the returned table.

return function ()
    -- This returns information about all the Lua "object-free" functions.
    -- GetApiDescriptor() returns a table with all the functions.
    -- Each table element is another table with the name, argument description, and return description.
      for key,value in ipairs(GetApiDescriptor()) do
        if value[1] ~= nil then
          Printf("Api " .. key .. " is: " .. value[1])
        end
        if value[2] ~= nil then
          Printf("Arguments: " .. value[2])
        end
        if value[3] ~= nil then
          Printf("Returns: " .. value[3])
        end
        Printf("---------------------------------------")
      end
  end

GetAttributeByUIChannel Official Docs

Signature

GetAttributeByUIChannel(integer:ui channel index): light_userdata:reference_to_attribute

Description

The GetAttributeByUIChannel Lua function returns the handle to an attribute based on a “UI Channel Index”. The index number can be found in the Parameter List.

Arguments

integer: ui channel index

Returns

light_userdata: reference_to_attribute

Example

This example prints the “native” address to the first attribute of the first fixture in the current selection:

return function()
    -- Get a handle to the first fixture in the current selection
    local fixtureIndex = SelectionFirst()
    -- Get the UI Channel Index number for the first attribute for the fixture
    local channelIndex = GetUIChannelIndex(fixtureIndex,0)
    -- Print the native address for the attribute with the handle
    Printf("The native addr for the attribute is: %s",GetAttributeByUIChannel(channelIndex):AddrNative())
end

GetAttributeColumnId

Signature

GetAttributeColumnId(light_userdata:handle, light_userdata:attribute): integer:column_id

Arguments

light_userdata: handle
light_userdata: attribute

Returns

integer: column_id

GetAttributeCount Official Docs

Signature

GetAttributeCount(nothing): integer:attribute_count

Description

The GetAttributeCount Lua function returns the total number of attribute definitions in the show.

Arguments

No Arguments

Returns

integer: attribute_count

Example

This example prints the returned number in the Command Line History.

return function()
    Printf("Attribute count is %i", GetAttributeCount())
end

GetAttributeIndex Official Docs

Signature

GetAttributeIndex(string:attribute_name): integer:attribute_index

Description

The GetAttributeIndex Lua function returns the (0 based) index number of the attribute definition based on the system name of the attribute.

Arguments

string: attribute_name

Returns

integer: attribute_index

Example

This example prints the index number of the attribute in Command Line History if it exists:

return function()
    -- store the returned index or nil of "Gobo1"
    local attributeIndex = GetAttributeIndex("Gobo1")
    -- Check if the returned value is not nil and print a useful feedback
    if attributeIndex~=nil then
        Printf("Attribute is index number %i", attributeIndex)
    else
        Printf("The attribute is not found")
    end
end

GetBlockInput New

Signature

GetBlockInput(nothing): boolean:block_input

Arguments

No Arguments

Returns

boolean: block_input

GetButton Official Docs

Signature

GetButton(light_userdata:usb_device_object_handle): table of boolean:state

Description

The GetButton Lua function returns a key-value pairs table indicating, with a boolean value, whether a button is pressed on an MA3Module.

Arguments

light_userdata: usb_device_object_handle

Returns

table of boolean: state

Example

This example requests the buttons states on the master module on a grandMA3 full-size console:

return function()
    --- grandMA3 full-size modules are:
    --- Master Module (MM): "UsbDeviceMA3 2"
    --- Fader Module Encoder (MFE): "UsbDeviceMA3 3"
    --- Fader Module Crossfader (MFX): "UsbDeviceMA3 4"

    -- Get a handle to the Master Module on a grandMA3 full-size.
    local usbDeviceHandle = Root().UsbNotifier.MA3Modules["UsbDeviceMA3 2"]
    -- Create a table with the button status.
    local buttonTable = GetButton(usbDeviceHandle)
    -- Check if the table is nil and then print an error.
    if buttonTable == nil then
        ErrPrintf("nil")
        return
    end
    -- If the table is not nil, then print a usefull feedback about pressed buttons.
    for key,value in pairs(buttonTable) do
        if tostring(value) == "true" then
            Printf("The button with the index " .. key .. " is pressed.")
        end
    end
end

GetChannelFunction Official Docs

Signature

GetChannelFunction(integer:ui_channel_index, integer:attribute_index): light_userdata:handle

Description

The GetChannelFunction Lua function returns a handle to a channel function based on two index inputs.

Arguments

integer: ui_channel_index
integer: attribute_index

Returns

light_userdata: handle

Example

This example prints the data connected to the handle. It uses the Dump() function:

return function()
    -- Select the first fixture in the current selection.
    local subfixtureIndex = SelectionFirst()
    -- End the function if there is no selection.
    if subfixtureIndex == nil then
        ErrPrintf("Please select a fixture with a Dimmer")
        return
    end
    -- Get the Attribute index and UIChannel index.
    local attributeIndex = GetAttributeIndex("Dimmer")
    local uiChannelIndex = GetUIChannelIndex(subfixtureIndex,attributeIndex)
    Printf("The UIChannel Index is: %i. The Attribute Index is: %i. ",uiChannelIndex, attributeIndex)
    -- End the function if any of the index return nil.
    if (attributeIndex == nil or uiChannelIndex == nil) then
        ErrPrintf("Something wrong happened, maybe your first selected fixture don't have a Dimmer - Please try again")
        return
    end
    -- The following prints the dump for the dimmer channel function.
    Printf("=============== START OF DUMP ===============")
    GetChannelFunction(uiChannelIndex,attributeIndex):Dump()
    Printf("================ END OF DUMP ================")
end

GetChannelFunctionIndex Official Docs

Signature

GetChannelFunctionIndex(integer:ui_channel_index, integer:attribute_index): integer:channel_function_index

Description

The GetChannelFunctionIndex Lua function returns the integer matching a channel function based on two index inputs.

Arguments

integer: ui_channel_index
integer: attribute_index

Returns

integer: channel_function_index

Example

This example prints the indexes based on the fixture selection and the “Dimmer” attribute.

return function()
    -- Get the Attribute index and UIChannel index.
    local attributeIndex = GetAttributeIndex("Dimmer")
    local uiChannelIndex = GetUIChannelIndex(SelectionFirst(),attributeIndex)
    -- End the function if any of the index return nil.
    if (attributeIndex == nil or uiChannelIndex == nil) then
        ErrPrintf("Something wrong happened, maybe your first selected fixture don't have a Dimmer - Please try again")
        return
    end
    -- Get the Channel Function Index and store it in a variable.
    local channelFunctionIndex = GetChannelFunctionIndex(uiChannelIndex,attributeIndex)
    Printf("The UIChannel Index is: %i. The Attribute Index is: %i. The Channel Function Index is: %i", uiChannelIndex, attributeIndex, channelFunctionIndex)
end

GetClassDerivationLevel Official Docs

Signature

GetClassDerivationLevel(string:class_name): integer:result or nothing

Description

The GetClassDerivationLevel Lua function returns an integer indicating the derivation level index for a class based on a class name.

Arguments

string: class_name

Returns

integer: result or nothing

Example

This example prints the index integer for the Pool class in the Command Line History:

return function()
    -- Get the index integer for the "Pool" class.
    local classDerivationLevel = GetClassDerivationLevel("Pool")
    -- Create a valid Printf return.
    if classDerivationLevel == nil then
        Printf("The return is nil")
    else
        Printf("The ClassDerivationLevel index for 'Pool' is: %i", classDerivationLevel)
    end
end

GetCurrentCue Official Docs

Signature

GetCurrentCue(nothing): light_userdata:handle

Description

The GetCurrentCue Lua function returns a handle to the last activated cue in the selected sequence.

Arguments

No Arguments

Returns

light_userdata: handle

Example

This example prints the data connected to the handle. It uses the Dump() function:

return function()
    -- Dumps information about the last activated cue in the selected sequence
    Printf("=============== START OF DUMP ===============")
    GetCurrentCue():Dump()
    Printf("================ END OF DUMP ================")
end

GetDebugFPS Official Docs

Signature

GetDebugFPS(nothing): float:fps

Description

The GetDebugFPS Lua function returns a float number with the frames per second.

Arguments

No Arguments

Returns

float: fps

Example

This example prints the FPS number:

return function ()
    -- Prints the current frames per second.
    Printf("Current FPS: " .. GetDebugFPS())
end

GetDisplayByIndex Official Docs

Signature

GetDisplayByIndex(integer:display_index): light_userdata:display_handle

Description

The GetDisplayByIndex Lua function returns a handle to the display object matching the provided index number.

Arguments

integer: display_index

Returns

light_userdata: display_handle

Example

This example prints the data connected to the handle. It uses the Dump() function:

return function()
    -- Get the index number for "Display 1"
    local displayIndex = GetDisplayCollect()["Display 1"].INDEX
    -- return error text in case the index number is nil
    if displayIndex == nil then
        ErrPrintf('Something went wrong. It appears that there is no "display 1"')
        return
    end
    -- Dump all information about the display with the index number
    Printf("=============== START OF DUMP ===============")
    GetDisplayByIndex(displayIndex):Dump()
    Printf("================ END OF DUMP ================")
end

GetDisplayCollect Official Docs

Signature

GetDisplayCollect(nothing): light_userdata:handle to DisplayCollect

Description

The GetDisplayCollect Lua function returns a handle to the DisplayCollect object.

Arguments

No Arguments

Returns

light_userdata: handle to DisplayCollect

Example

This example prints the data connected to the handle. It uses the Dump() function:

return function()
    -- This example dumps all information about the DisplayCollect object.
    Printf("=============== START OF DUMP ===============")
    GetDisplayCollect():Dump()
    Printf("================ END OF DUMP ================")
end

GetDMXUniverse Official Docs

Signature

GetDMXUniverse(integer:universe[ ,boolean:modePercent]): {integer:dmx_values}

Description

The GetDMXUniverse Lua function returns a table with the DMX channels and their current value.

Arguments

integer: universe
boolean (optional): modePercent

Returns

{integer:dmx_values}:

Example

This example prints the table in a list for DMX universe 1 (if it is granted):

return function()
    -- This gets a table for universe 1 with the returned value in percent.
    local tableDMXUniverse = GetDMXUniverse(1,true)
    -- Check the returned table and print information if nil.
    if tableDMXUniverse == nil then
        Printf("No value is returned. The univer is not granted or input is out of range")
        return
    end
    -- Prints the table if not nil.
    for addr, value in ipairs(tableDMXUniverse) do
        Printf("DMX Addr: %i - DMX value : %i", addr, value)
    end
end

GetDMXValue Official Docs

Signature

GetDMXValue(integer:address[ ,integer:universe, boolean:mode_percent]): integer:dmx_value

Description

The GetDMXValue Lua function returns a number indicating the DMX value of a specified DMX address.

Arguments

integer: address
integer (optional): universe
boolean (optional): mode_percent

Returns

integer: dmx_value

Example

This example prints the value for DMX address 2 in Universe 1 (if it is granted):

return function()
    -- This prints the value of DMX address 2 in universe 1 in a range of 0 to 255
    local address = 2       -- The DMX address
    local universe = 1      -- The DMX universe
    local percent = false   -- Readout in percent or DMX value
    local value = GetDMXValue(address, universe, percent)
    if value == nil then
        Printf("The DMX address did not return a valid value")
    else
        Printf("DMX address %i.%03d has a value of %03d", universe, address, value)
    end
end

GetExecutor Official Docs

Signature

GetExecutor(integer:executor): light_userdata:executor, light_userdata:page

Description

The GetExecutor Lua function returns the handles of the executor and the page based on the executor number.

Arguments

integer: executor

Returns

light_userdata: executor
light_userdata: page

Example

This example stores the handles for executor number 201. It then uses the Dump() function to show the data for the two handles.

return function ()
    -- This saves the handles for executor 201 on the selected page.
    local executorHandle, pageHandle = GetExecutor(201)
    -- exit the function and print an error message if any of the handles are nil.
    if executorHandle == nil or pageHandle == nil then
        ErrPrintf("There is not a valid object on executor 201, please assign something and try again.")
        return
    end
    -- The following prints the dumps of the two handles.
    Printf("============ START OF EXEC DUMP =============")
    executorHandle:Dump()
    Printf("================ END OF DUMP ================")
    Printf("============ START OF PAGE DUMP =============")
    pageHandle:Dump()
    Printf("================ END OF DUMP ================")
end

GetFocus Official Docs

Signature

GetFocus(nothing): light_userdata:display_handle

Description

The GetFocus Lua function returns a handle to the object that currently has focus in the UI.

Arguments

No Arguments

Returns

light_userdata: display_handle

Example

This example prints the data connected to the handle. It uses the Dump() function:

return function()
    -- This example dumps all information about the object who currently got focus.
    Printf("=============== START OF DUMP ===============")
    GetFocus():Dump()
    Printf("================ END OF DUMP ================")
end

GetFocusDisplay Official Docs

Signature

GetFocusDisplay(nothing): light_userdata:display_handle

Description

The GetFocusDisplay Lua function returns a handle to the display object that currently has focus in the UI.

Arguments

No Arguments

Returns

light_userdata: display_handle

Example

This example prints the data connected to the handle. It uses the Dump() function:

return function()
    -- This example dumps all information about the display object who currently got focus.
    Printf("=============== START OF DUMP ===============")
    GetFocusDisplay():Dump()
    Printf("================ END OF DUMP ================")
end

GetObjApiDescriptor Official Docs

Signature

GetObjApiDescriptor(nothing): table of {string:function_name, string:arguments, string:return_values}

Description

The GetObjApiDescriptor Lua function returns a table with a description of all the object Lua functions. These are descriptions only. The function does not have any actual functions. The table is not sorted.

Arguments

No Arguments

Returns

table of {string:function_name, string:arguments, string:return_values}:

Example

This example prints the content of the returned table.

return function ()
  -- This returns information about all the Lua "object" functions.
  -- GetObjApiDescriptor() returns a table with all the functions.
  -- Each table element is another table with the name, argument description, and return description.
    for key,value in ipairs(GetObjApiDescriptor()) do
      if value[1] ~= nil then
        Printf("Api " .. key .. " is: " .. value[1])
      end
      if value[2] ~= nil then
        Printf("Arguments: " .. value[2])
      end
      if value[3] ~= nil then
        Printf("Returns: " .. value[3])
      end
      Printf("---------------------------------------")
      end
end

GetObject

Signature

GetObject(string:address): light_userdata:handle

Arguments

string: address

Returns

light_userdata: handle

GetPath Official Docs

Signature

GetPath(string:path_type or integer:path_type(Enums.PathType)[ ,boolean:create]): string:path

Description

The GetPath Lua function returns a string with the path of a grandMA3 folder.

Arguments

string: path_type or integer:path_type(Enums.PathType)
boolean (optional): create

Returns

string: path

Example

This example prints the paths of the show folder on the system monitor twice. It demonstrates the two different input types:

return function()
    -- This prints a path based on a string input and it creates the folder if it does not exists.
    Printf("Path of show files (string) is: " .. GetPath("shows", true))
    -- This prints the path based on an integer. The integer is looked-up using the 'PathType' enum.
    Printf("Path of show files (integer) is: " .. GetPath(Enums.PathType.Showfiles))
end

GetPathOverrideFor Official Docs

Signature

GetPathOverrideFor(string:path_type or integer:path_type(Enums.PathType), string:path[ ,boolean:create]): string:overwritten_path

Description

The GetPathOverrideFor Lua function delivers a string with the path of a grandMA3 folder. The function is relevant when the path should be on a removable drive connected to a console.

Arguments

string: path_type or integer:path_type(Enums.PathType)
string: path
boolean (optional): create

Returns

string: overwritten_path

Example

This example prints the override path of the macro folder on the system monitor. It should be run on a console with a removable drive connected.

return function ()
    -- Set a path for the first removable media.
    -- Set the initial value to nil.
    local myBasePath = nil
    -- Itereate the drives and find the first 'Removeable' drive and store the path.
    for _, value in ipairs(Root().Temp.DriveCollect) do
        local driveType = value.drivetype
        if driveType == "Removeable" then
            myBasePath = value.path
            break
        end
    end
    -- If no removeable drive was found, then provide feedback and exit the function.
    if myBasePath == nil then
        ErrPrintf("No removeable drive could be found. Please insert one and try again")
        return
    end

    -- Get the integer for the UserMacros path type.
    local myPathType = Enums.PathType.UserMacros

    -- Gey the string for the path override.
    local myOverridePath = GetPathOverrideFor(myPathType, myBasePath)
    -- Print the returned string.
    Printf("The path is: " .. myOverridePath)
end

GetPathSeparator

Signature

GetPathSeparator(nothing): string:seperator

Arguments

No Arguments

Returns

string: seperator

GetPathType Official Docs

Signature

GetPathType(light_userdata:target_object[ ,integer:content_type (Enums.PathContentType)]): string:path_type_name

Description

The GetPathType Lua function returns a string with a name for the path type. This function can be useful when importing objects.

Arguments

light_userdata: target_object
integer (optional): content_type (Enums.PathContentType)

Returns

string: path_type_name

Example

This example prints the path type name for the first macro object - if it exists:

return function ()
    -- Get a handle to the first Macro.
    local myMacro = DataPool().Macros[1]
    if myMacro == nil then
        ErrPrintf("An error occurred, possibly because the first macro does not exist.")
        ErrPrintf("Please create one and try again.")
        return
    end
    -- Get the user name of the path type.
    local myPathTypeNameUser = GetPathType(myMacro, Enums.PathContentType.User)
    if myPathTypeNameUser ~= nil then
        Printf("The user name of the path type is: " .. myPathTypeNameUser)
    else
        ErrPrintf("There was an error getting the path type.")
    end

    -- Get the system name of the path type.
    local myPathTypeNameSystem = GetPathType(myMacro, Enums.PathContentType.System)
    if myPathTypeNameSystem ~= nil then
        Printf("The system name of the path type is: " .. myPathTypeNameSystem)
    else
        ErrPrintf("There was an error getting the path type.")
    end
end

GetPresetData Official Docs

Signature

GetPresetData(light_userdata:preset_handle[, boolean:phasers_only(default=false)[, boolean:by_fixtures(default=true)]]): table:phaser_data

Description

The GetPresetData Lua function returns a table with the preset data based on the preset handle.

Arguments

light_userdata: preset_handle
boolean (optional): phasers_only(default=false)
boolean (optional): by_fixtures(default=true)

Returns

table: phaser_data

Example

This example prints information about the first level table in the preset data and the first level of the first fixture in the preset. It uses dimmer preset 1, which must exist.

return function()
    -- Get the handle for the first Dimmer preset.
    local myPreset = DataPool().PresetPools[1][1]
    -- Get the Preset Data of the handle.
    local myPresetData = GetPresetData(myPreset, false, false)
    -- Check if the GetPresetData returns something.
    if myPresetData == nil then
        ErrPrintf("Dimmer preset 1 does not exist. Please create one and try again.")
        return
    end

    -- Print the myPresetData table.
    for Key, value in pairs(myPresetData) do
      if type(value) == "table" then
        Printf("Key: " .. Key .. " ; Value type is: " .. type(value))
      else
        Printf("Key: " .. Key .. " ; Value type is: " .. type(value) .. " ; Value: " .. value)
      end
    end

    -- Create a table object to hold all the integer keys in the myPresetData table.
    local myIntegerTableKeys = {}
    -- Fill the table.
    for key,_ in pairs(myPresetData) do
        if type(key) == "number" then
            table.insert(myIntegerTableKeys, key)
        end
    end
    -- Sort the table
    table.sort(myIntegerTableKeys)

    -- Print the elements of the fixture with the lowest ui_channel_index in the preset.
    local tableIndex = myIntegerTableKeys[1]
    if tableIndex ~= nil then
        Printf("=============== TABLE CONTENT START - Table Key: " .. tableIndex .." ===============")
        for Key, value in pairs(myPresetData[tableIndex]) do
          if type(value) == "table" then
            Printf("Key: " .. Key .. " ; Value type is: " .. type(value))
          else
            Printf("Key: " .. Key .. " ; Value type is: " .. type(value) .. " ; Value: " .. tostring(value))
          end
        end
        Printf("================ TABLE CONTENT END - Table Key: " .. tableIndex .." ================")
    end
end

GetProgPhaser

Signature

GetProgPhaser(integer:ui_channel_index, boolean:phaser_only): {['abs_preset'=light_userdata:handle], ['rel_preset'=light_userdata:handle], ['fade'=float:seconds], ['delay'=float:seconds], ['speed'=float:hz], ['phase'=float:degree], ['measure'=float:percent], ['gridpos'=integer:value], ['mask_active_phaser'=integer:bitmask], ['mask_active_value'=integer:bitmask], ['mask_individual'=integer:bitmask], {['channel_function'=integer:value], ['absolute'=float:percent], ['absolute_value'=integer:value], ['relative'=float:percent], ['accel'=float:percent[, 'accel_type'=integer:enum_value(Enums.SplineType)]], ['decel'=float:percent[, 'decel_type'=integer:enum_value(Enums.SplineType)]], ['trans'=float:percent], ['width'=float:percent], ['integrated'=light_userdata:preset_handle]}}

Arguments

integer: ui_channel_index
boolean: phaser_only

Returns

{['abs_preset'=light_userdata:handle], ['rel_preset'=light_userdata:handle], ['fade'=float:seconds], ['delay'=float:seconds], ['speed'=float:hz], ['phase'=float:degree], ['measure'=float:percent], ['gridpos'=integer:value], ['mask_active_phaser'=integer:bitmask], ['mask_active_value'=integer:bitmask], ['mask_individual'=integer:bitmask], {['channel_function'=integer:value], ['absolute'=float:percent], ['absolute_value'=integer:value], ['relative'=float:percent], ['accel'=float:percent[, 'accel_type'=integer:enum_value(Enums.SplineType)]], ['decel'=float:percent[, 'decel_type'=integer:enum_value(Enums.SplineType)]], ['trans'=float:percent], ['width'=float:percent], ['integrated'=light_userdata:preset_handle]}}:

GetProgPhaserValue

Signature

GetProgPhaserValue(integer:ui_channel_index, integer:step): {['channel_function'=integer:value], ['absolute'=number:percent], ['absolute_value'=number:value], ['relative'=number:percent], ['accel'=number:percent[, 'accel_type'=integer:enum_value(Enums.SplineType)]], ['decel'=number:percent[, 'decel_type'=integer:enum_value(Enums.SplineType)]], ['trans'=number:percent], ['width'=number:percent], ['integrated'=light_userdata:preset_handle]}

Arguments

integer: ui_channel_index
integer: step

Returns

{['channel_function'=integer:value], ['absolute'=number:percent], ['absolute_value'=number:value], ['relative'=number:percent], ['accel'=number:percent[, 'accel_type'=integer:enum_value(Enums.SplineType)]], ['decel'=number:percent[, 'decel_type'=integer:enum_value(Enums.SplineType)]], ['trans'=number:percent], ['width'=number:percent], ['integrated'=light_userdata:preset_handle]}:

GetPropertyColumnId

Signature

GetPropertyColumnId(light_userdata:handle, string:property_name): integer:column_id

Arguments

light_userdata: handle
string: property_name

Returns

integer: column_id

GetRemoteVideoInfo

Signature

GetRemoteVideoInfo(nothing): integer:wingID, boolean:isExtension

Arguments

No Arguments

Returns

integer: wingID
boolean: isExtension

GetRTChannel Official Docs

Signature

GetRTChannel(integer:rt_channel_index): table:rt_channel_descriptor

Description

The GetRTChannel Lua function returns a table with information about the related RT Channel.

Arguments

integer: rt_channel_index

Returns

table: rt_channel_descriptor

Example

This example prints all information related to the first RT Channel for the first fixture in the selection:

return function()
    -- Get the index number for the first RT Channel for the first fixture in the current selection
    local channelRTIndex = GetRTChannels(SelectionFirst())[1]
    -- Print an error message if returnd index is nil
    if channelRTIndex == nil then
        ErrPrintf("Please select a fixture and try again")
        return
    end
    -- Print all information about the RT Channel if it does not return nil
    local rtChannel = GetRTChannel(channelRTIndex)
    if rtChannel == nil then
        Printf("An RTChannel could not be found. Please try to selct a different fixture and try again.")
        return
    end
    Printf("================= RT CHANNEL =================")
    Printf("ui_index_first = " .. rtChannel["ui_index_first"])
    Printf("dmx_lowlight = " .. rtChannel["dmx_lowlight"])
    Printf("dmx_highlight = " .. rtChannel["dmx_highlight"])
    Printf("dmx_default = " .. rtChannel["dmx_default"])
    Printf("freq = " .. rtChannel["freq"])
    Printf("rt_index = " .. rtChannel["rt_index"])
    Printf("========== RELATED DMX CHANNEL DUMP ==========")
    rtChannel["dmx_channel"]:Dump() -- Handle for relevant DMX channel
    Printf("============ RELATED FIXTURE DUMP ============")
    rtChannel["fixture"]:Dump() -- Handle for relevant fixture
    Printf("========== RELATED SUBFIXTURE DUMP ===========")
    rtChannel["subfixture"]:Dump() -- Handle for relevant subfixture
    Printf("=================== INFO =====================")
    Printf("normed_phaser_time = " .. rtChannel["info"]["normed_phaser_time"])
    Printf("================ INFO FLAGS ==================")
    Printf("group_master = " .. rtChannel["info"]["flags"]["group_master"])
    Printf("additive_master = " .. rtChannel["info"]["flags"]["additive_master"])
    Printf("solo = " .. rtChannel["info"]["flags"]["solo"])
    Printf("highlight = " .. rtChannel["info"]["flags"]["highlight"])
    Printf("lowlight = " .. rtChannel["info"]["flags"]["lowlight"])
    Printf("=================== PATCH ====================")
    Printf("break = " .. rtChannel["patch"]["break"])
    Printf("coarse = " .. rtChannel["patch"]["coarse"])
    Printf("fine = " .. rtChannel["patch"]["fine"])
    Printf("ultra = " .. rtChannel["patch"]["ultra"])
end

GetRTChannelCount Official Docs

Signature

GetRTChannelCount(nothing): integer:rt_channel_count

Description

The GetRTChannelCount Lua function returns a number indicating the total amount of RT channels.

Arguments

No Arguments

Returns

integer: rt_channel_count

Example

This example prints the number of RT channels to the Command Line History:

return function()
    Printf("The number of RT channels is " .. GetRTChannelCount())
end

GetRTChannels Official Docs

Signature

GetRTChannels(integer:fixture index or light_userdata: reference_to_fixture_object[, boolean:return_as_handles]): {integer:rt_channels} or {light_userdata:rt_channels}

Description

The GetRTChannels Lua function returns a table with RT Channel indexes or a table with handles to the RT Channel objects. There are two different types of arguments for this function.

Arguments

integer: fixture index or light_userdata: reference_to_fixture_object
boolean (optional): return_as_handles

Returns

{integer:rt_channels} or {light_userdata:rt_channels}:

Example

return function()
    -- Get the index number for the first fixture in the current selection
    local fixtureIndex = SelectionFirst()
    -- Get the indexes of the RT channels
    local rtChannels = GetRTChannels(fixtureIndex, false)
    -- Print an error message if returnd table is nil
    if rtChannels == nil then
        ErrPrintf("Please select a fixture and try again")
        return
    end
    -- Print the table content
    for key,value in ipairs(rtChannels) do
        Printf("List index number ".. key .." : RTChannel index number = ".. value)
    end
end

GetSample Official Docs

Signature

GetSample(string:type('MEMORY', 'CPU', 'CPUTEMP', 'GPUTEMP', 'SYSTEMP', 'FANRPM')): integer:current_value_in_percent

Description

The GetSample Lua function returns a number representing a percentage usage based on a string input.

Arguments

string: type(‘MEMORY’, ‘CPU’, ‘CPUTEMP’, ‘GPUTEMP’, ‘SYSTEMP’, ‘FANRPM’)

Returns

integer: current_value_in_percent

Example

This example stores the different samples in a table and then prints the content of the table:

return function()
    -- Gather the sample information in a table
    local sample = {}
    sample["MEMORY"] = GetSample("MEMORY")
    sample["CPU"] = GetSample("CPU")
    sample["CPUTEMP"] = GetSample("CPUTEMP")
    sample["GPUTEMP"] = GetSample("GPUTEMP")
    sample["SYSTEMP"] = GetSample("SYSTEMP")
    sample["FANRPM"] = GetSample("FANRPM")
    -- Print the collected data
    Printf("Memory ; ".. sample["MEMORY"])
    Printf("CPU ; ".. sample["CPU"])
    Printf("CPU temperature ; ".. sample["CPUTEMP"])
    Printf("GPU temperature ; ".. sample["GPUTEMP"])
    Printf("System temperature ; ".. sample["SYSTEMP"])
    Printf("Fan RPM ; ".. sample["FANRPM"])
end

GetScreenContent Official Docs

Signature

GetScreenContent(light_userdata:handle to ScreenConfig): light_userdata:handle

Description

The GetScreenContent Lua function returns a handle to the screen content based on a provided handle to a screen configuration.

Arguments

light_userdata: handle to ScreenConfig

Returns

light_userdata: handle

Example

This example prints the data connected to the screen content handle. It uses the CurrentScreenConfig() and Dump() functions:

return function()
    -- Create a handle for the current screen configuration.
    local myCurrentScreenConfig = CurrentScreenConfig()
    -- Create a handle for the screen content based on the screen configuration.
    local myScreenContent = GetScreenContent(myCurrentScreenConfig)
    -- Print the Dump of the handle.
    Printf("=============== START OF DUMP ===============")
    myScreenContent:Dump()
    Printf("================ END OF DUMP ================")
end

GetSelectedAttribute Official Docs

Signature

GetSelectedAttribute(nothing): light_userdata:handle

Description

The GetSelectedAttribute Lua function returns a handle to the currently selected attribute.

Arguments

No Arguments

Returns

light_userdata: handle

Example

This example prints the data connected to the handle. It uses the Dump() function:

return function()
    -- This example dumps all information about the currently selected attribute
    Printf("=============== START OF DUMP ===============")
    GetSelectedAttribute():Dump()
    Printf("================ END OF DUMP ================")
end

GetShowFileStatus Official Docs

Signature

GetShowFileStatus(nothing): string:showfile_status

Description

The GetShowFileStatus Lua function returns a string with the current device’s show file status, for example, “NoShow”, “ShowLoaded”, “ShowDownloaded”, “ShowSaving”, and “DataNegotiationActive”.

Arguments

No Arguments

Returns

string: showfile_status

Example

This example prints the current device’s show file status in the Command Line History:

return function ()
    -- Prints the current showfile status
    Printf("ShowfileStatus: "..GetShowFileStatus())
end

GetSubfixture Official Docs

Signature

GetSubfixture(integer:subfixture_index): light_userdata:subfixture

Description

The GetSubfixture Lua function returns the handle of the fixture specified by its patch index number.

Arguments

integer: subfixture_index

Returns

light_userdata: subfixture

Example

This example uses a fixture selection to print all the information (in the Command Line History) about the first fixture in the selection using the Dump() function:

return function ()
    -- Check for a fixture selection, by returning an index for the first fixture
    if (SelectionFirst()) then
        -- There is a fixture selection, store the index for the first fixture
        local fixtureIndex = SelectionFirst()
        -- Dump all information about the fixture
        Printf("=============== START OF DUMP ===============")
        GetSubfixture(fixtureIndex):Dump()
        Printf("================ END OF DUMP ================")
    else
        -- There needs to be a selection of at least one fixture
        Printf("Please select a fixture")
    end
end

GetSubfixtureCount Official Docs

Signature

GetSubfixtureCount(nothing): integer:subfixture_count

Description

The GetSubfixtureCount Lua function returns the total number of fixtures that are patched within the show file.

Arguments

No Arguments

Returns

integer: subfixture_count

Example

This example prints the total number of patched fixtures in the Command Line History:

return function ()
    Printf('Total number of patched fixtures: %i', GetSubfixtureCount())
end

GetTextScreenLine

Signature

GetTextScreenLine(nothing): integer:internal line number

Arguments

No Arguments

Returns

integer: internal line number

GetTextScreenLineCount

Signature

GetTextScreenLineCount([integer:starting internal line number]): integer:line count

Arguments

integer (optional): starting internal line number

Returns

integer: line count

GetTokenName Official Docs

Signature

GetTokenName(string:short_name): string:full_name

Description

The GetTokenName Lua function returns a string with the full keyword based on the short version string input or nil if there is no corresponding keyword.

Arguments

string: short_name

Returns

string: full_name

Example

This example returns the full keyword matching the short “seq” string:

return function()
    -- Store a short string to be used as input
    local shortToken = 'seq'
    -- Get the full token name
    local tokenName = GetTokenName(shortToken)
    -- Print useful output if nil is not returned
    if tokenName ~= nil then
        Printf("The full version of '".. shortToken .. "' is '" .. tokenName .. "'")
    end
end

GetTokenNameByIndex Official Docs

Signature

GetTokenNameByIndex(integer:token_index): string:full_name

Description

The GetTokenNameByIndex Lua function returns a string with the keyword based on the index number provided.

Arguments

integer: token_index

Returns

string: full_name

Example

If the keyword exists, this example returns the keywords matching the first 443 index numbers:

return function()
    -- Create a variable to hold the keyword string
    local tokenName = ""
    -- Print the keywords to the first 443 indexes if possible
    for index = 1, 443, 1 do
        tokenName = GetTokenNameByIndex(index)
        if tokenName ~= nil then
            Printf("Token index " .. index .. " = " .. tokenName)
        end
    end
end

GetTopModal Official Docs

Signature

GetTopModal(nothing): light_userdata:handle to top modal overlay

Description

The GetTopModal Lua function returns a handle for the modal at the top. Modal is the internal name for pop-ups that interrupt the system’s normal operation. A modal blocks other UI elements from being used while it is open.

Arguments

No Arguments

Returns

light_userdata: handle to top modal overlay

Example

This example uses the Dump() function to show information about the StagePopup selection pop-up.

return function()
    -- Open a Modal / Pop-up.
    Cmd('Menu "StagePopup"')
    -- Add a small wait.
    coroutine.yield(0.5)
    -- Get the handle for the modal / pop-up.
    local modalHandle = GetTopModal()
    -- If there is a handle then dump all information else print en error feedback.
    if modalHandle ~= nil then
        Printf("=============== START OF DUMP ===============")
        modalHandle:Dump()
        Printf("================ END OF DUMP ================")
    else
        ErrPrintf("The Modal UI object could not be found.")
    end
    -- Close the modal / pop-up by pressing the Escape key.
    Keyboard(1,'press','Escape')
    Keyboard(1,'release','Escape')
end

GetTopOverlay Official Docs

Signature

GetTopOverlay(integer:display_index): light_userdata:handle to top overlay on the display

Description

The GetTopOverlay Lua function returns a handle for the overlay at the top of the display with the provided index number. Overlay is the internal name for what is called pop-ups or menus in the rest of this manual.

Arguments

integer: display_index

Returns

light_userdata: handle to top overlay on the display

Example

This example uses the Dump() function to show information about the MenuSelector pop-up - it is the one opening when pressing the Menu key.

return function()
    -- Open the MenuSelector overlay.
    Cmd('Menu "MenuSelector')
    -- Add a small delay.
    coroutine.yield(0.5)
    -- Get the handle for the overlay on the display with index 1.
    local overlayHandle = GetTopOverlay(1)
    -- Add a small delay.
    coroutine.yield(0.5)
    -- Close the MenuSelector overlay.
    Cmd('Menu "MenuSelector')
    -- Check if there is a handle and print appropriate feedback.
    if overlayHandle ~= nil then
        Printf("=============== START OF DUMP ===============")
        overlayHandle:Dump()
        Printf("================ END OF DUMP ================")
    else
        ErrPrintf("The Overlay UI object could not be found.")
    end
end

GetUIChannel

Signature

GetUIChannel(integer:ui_channel_index or light_userdata: subfixture_reference, integer:attribute_index or string:attribute_name): table:ui_channel_descriptor

Arguments

integer: ui_channel_index or light_userdata: subfixture_reference
integer: attribute_index or string:attribute_name

Returns

table: ui_channel_descriptor

GetUIChannelCount Official Docs

Signature

GetUIChannelCount(nothing): integer:ui_channel_count

Description

The GetUIChannelCount Lua function returns a number indicating the total amount of UI channels.

Arguments

No Arguments

Returns

integer: ui_channel_count

Example

This example prints the number of UI channels to the Command Line History:

return function()
    Printf("The number of UI channels is " .. GetUIChannelCount())
end

GetUIChannelIndex Official Docs

Signature

GetUIChannelIndex(integer:subfixture_index, integer:attribute_index): integer:ui_channel_index

Description

The GetUIChannelIndex Lua function returns the index integer matching a UI channel based on two index inputs.

Arguments

integer: subfixture_index
integer: attribute_index

Returns

integer: ui_channel_index

Example

This example prints the UI channel index of the “Dimmer” attribute of the first fixture in the current selection:

return function()
    -- Get the Attribute index and UIChannel indexes
    local attributeIndex = GetAttributeIndex("Dimmer")
    local uiChannelIndex = GetUIChannelIndex(SelectionFirst(),attributeIndex)
    -- End the function if any of the index return nil
    if (attributeIndex == nil or uiChannelIndex == nil) then
        ErrPrintf("Something went wrong, maybe your first selected fixture don't have a Dimmer - Please try again")
        return
    end
    Printf("The UI Channel Index is " .. uiChannelIndex)
end

GetUIChannels Official Docs

Signature

GetUIChannels(integer:subfixture_index or light_userdata: subfixture_handle[, boolean:return_as_handles]): {integer:ui_channels} or {light_userdata:ui_channels}

Description

The GetUIChannels Lua function returns a table with UI Channel indexes or a table with handles to the UI Channel objects. There are two different types of arguments for this function.

Arguments

integer: subfixture_index or light_userdata: subfixture_handle
boolean (optional): return_as_handles

Returns

{integer:ui_channels} or {light_userdata:ui_channels}:

Example

return function()
    -- Creates a table of indexes of the UI channels of the first selected fixture.
    local uiChannels = GetUIChannels(SelectionFirst())
    if uiChannels == nil then
        ErrPrintf("Please select a fixture and try again")
        return
    end
    for key,value in ipairs(uiChannels) do
        Printf("List index number ".. key .. " :  UIChannel Index = " .. value)
    end
end

GetUIObjectAtPosition Official Docs

Signature

GetUIObjectAtPosition(integer:display_index, {x=integer:x_position,y=integer:y_position}): light_userdata:handle to UI object or nil

Description

The GetUIObjectAtPosition Lua function returns the handle of the UI Object at a specified position on a specified display.

Arguments

integer: display_index
{x=integer:x_position,y=integer:y_position}:

Returns

light_userdata: handle to UI object or nil

Example

This example prints the Dump of the UIObject at a specific position on display 1. It also uses the DrawPointer function to draw a red pointer at the position.

return function()
    -- Get the index number for "Display 1"
    local displayIndex = GetDisplayCollect()["Display 1"].INDEX
    -- Create a table with X and Y position
    local positionTable = {}
    positionTable.x = 1000
    positionTable.y = 500
    -- Get the UI object handle
    local uiObjectAtPositionHandle = GetUIObjectAtPosition(displayIndex,positionTable)
    -- Dump all information about the display with the index number if not nil
    if uiObjectAtPositionHandle == nil then
        Printf("The returned value was not a valid handle.")
        return
    end
    -- Draw a pointer at the posiiton for 5 seconds
    DrawPointer(displayIndex,positionTable,5000)
    --Dump of the UIObject
    Printf("=============== START OF DUMP ===============")
    uiObjectAtPositionHandle:Dump()
    Printf("================ END OF DUMP ================")
end

GetVar Official Docs

Signature

GetVar(light_userdata:variables, string:varname): value

Description

The GetVar Lua function returns the value of a specific variable in a set of variables. To learn more about the variables in plugins, look at the Variable Functions topic.

Arguments

light_userdata: variables
string: varname

Returns

value:

Example

This example returns the value of a variable called “myUserVar” in the set of user variables if it exists:

return function()
    -- Get the value from a user variable called "myUserVar" - assuming it already exists
    local varValue = GetVar(UserVars(), "myUserVar")
    -- Print en error feedback or the value of the variable
    if varValue == nil then
        Printf("Variable returns nothing!")
    else
        Printf("Variable value is: " .. varValue)
    end
end

GetVarVersion New

Signature

GetVarVersion(light_userdata:variables, string:varname): integer:version

Arguments

light_userdata: variables
string: varname

Returns

integer: version

GlobalVars Official Docs

Signature

GlobalVars(nothing): light_userdata:global_variables

Description

The GlobalVars function returns a handle to the set of global variables. Read more about these in the Variables topic in the Macro section.

Arguments

No Arguments

Returns

light_userdata: global_variables

Example

This example sets, gets, and deletes a global variable:

return function()
    -- Stores a local Lua variable with the handle for the global variable set.
    local variableSet = GlobalVars()
    -- Sets a global variable with an integer value using the SetVar() function.
    SetVar(variableSet, "myGlobalVar", 42)
    -- Prints the global variable using the GetVar() function.
    Printf("The value  of myGlobalVar is: " .. GetVar(variableSet, "myGlobalVar"))
    -- Deletes the global variable using the DelVar() function.
    DelVar(variableSet, "myGlobalVar")
end

HandleToInt Official Docs

Signature

HandleToInt(light_userdata:handle): integer:handle

Description

The HandleToInt Lua function converts a handle into an integer format.

Arguments

light_userdata: handle

Returns

integer: handle

Example

This example prints the handle integer number for the selected sequence. It also converts the integer back to a handle and uses this to print the name of the sequence:

return function()
    Printf("The integer number for the handle of the selected sequence: %i", HandleToInt(SelectedSequence()))
end

HandleToStr

Signature

HandleToStr(light_userdata:handle): string:handle(in H#... format)

Arguments

light_userdata: handle

Returns

string: handle(in H#… format)

HookObjectChange Official Docs

Signature

HookObjectChange(function:callback, light_userdata:handle, light_userdata:plugin_handle[, light_userdata:target]): integer:hook_id

Description

The HookObjectChange Lua function automatically calls a function when a grandMA3 object changes.

Arguments

function: callback
light_userdata: handle
light_userdata: plugin_handle
light_userdata (optional): target

Returns

integer: hook_id

Example

To call a function every time the content of the sequence pool changes, create a plugin with this code:

-- Get the handle to this Lua component.
local luaComponentHandle = select(4,...)

function Main()
    -- Get a handle to the sequence pool.
    local hookObject = DataPool().Sequences
    -- Get a handle to this plugin.
    local pluginHandle = luaComponentHandle:Parent()
    -- Create the hook and save the Hook ID.
    SequenceHookId = HookObjectChange(MySequencePoolCallback, hookObject, pluginHandle)
    -- Print the returned Hook ID.
    Printf("HookId: " .. SequenceHookId)
end

-- This function is called when there are changes in the sequence pool.
function MySequencePoolCallback(obj)
    Printf(tostring(obj.name) .. " changed!")
end

return Main

HostOS Official Docs

Signature

HostOS(nothing): string:ostype

Description

The HostOS Lua function returns a string with the type of operating system of the device where the plugin is executed (for instance, “Windows”, “Linux”, or “Mac”).

Arguments

No Arguments

Returns

string: ostype

Example

This example prints the operating system of the device in the Command Line History:

return function()
    Printf("The HostOS is "..HostOS())
end

HostRevision New

Signature

HostRevision(nothing): string:hostrevision

Arguments

No Arguments

Returns

string: hostrevision

HostSubType Official Docs

Signature

HostSubType(nothing): string:hostsubtype

Description

The HostSubType Lua function returns a string with the host sub type of the station where the plugin is executed (for example, “FullSize”, “Light”, “RPU”, “onPCRackUnit”, “Undefined”).

Arguments

No Arguments

Returns

string: hostsubtype

Example

This example prints the host sub-type of the station in the Command Line History:

return function()
    Printf("The HostSubType is "..HostSubType())
end

HostType Official Docs

Signature

HostType(nothing): string:hosttype

Description

The HostType Lua function returns a string with the host type of the device where the plugin is executed (for example, “Console” or “onPC”).

Arguments

No Arguments

Returns

string: hosttype

Example

This example prints the host type of the device in the Command Line History:

return function()
    Printf("The HostType is "..HostType())
end

Import Official Docs

Signature

Import(string:file_name): table:content

Description

The object-free Import Lua function imports a Lua table in XML format.

Arguments

string: file_name

Returns

table: content

Example

This example imports the table exported using the example in the Export() function topic - please run that example before running this example.

return function ()
    -- Get the path for the exported table.
    local importPath = GetPath(Enums.PathType.Library) .. "/BuildDetails.xml"
    -- Check if the file exist and print relevant feedback.
    if importPath == nil then
        -- File does not exist.
        ErrPrintf("The desired file does not exist. Please add it or adjust the requested file name.")
    else
        -- Import the table.
        local importedTable = Import(importPath)
        -- Check if the import returned something and print relevant feedback.
        if importedTable == nil then
            -- Import didn't return anything.
            ErrPrintf("The import failed.")
        else
        -- Print some of the table content.
        Printf("CompileDate: " .. importedTable.CompileDate)
        Printf("CompileTime: " .. importedTable.CompileTime)
        Printf("BigVersion: " .. importedTable.BigVersion)
        Printf("HostType: " .. importedTable.HostType)
        Printf("HostSubType: " .. importedTable.HostSubType)
        Printf("CodeType: " .. importedTable.CodeType)
        end
    end
end

IncProgress Official Docs

Signature

IncProgress(integer:progressbar_index[, integer:delta]): nothing

Description

The IncProgress Lua function changes the value on the range for a progress bar using an integer input. A handle input argument defines the progress bar. The progress bar needs to be created using the StartProgress() function.

Arguments

integer: progressbar_index
integer (optional): delta

Returns

No Return

Example

These two examples increase and decrease the range value for the progress bar created using the example in the StartProgress topic (link above):

return function()
    -- Increase the current value for a progress bar with the matching handle.
    IncProgress(progressHandle, 1)
end

IntToHandle Official Docs

Signature

IntToHandle(integer:handle): light_userdata:handle

Arguments

integer: handle

Returns

light_userdata: handle

Example

This example prints the handle integer number for the selected sequence. It also converts the integer back to a handle and uses this to print the name of the sequence:

return function()
    -- Convert the handle of the currently selected sequence to an integer
    local handleInt = HandleToInt(SelectedSequence())
    -- Print the handle integer
    Printf("The handle integer number of the selected sequence: %i", HandleToInt(SelectedSequence()))
    -- Convter the integer back to a hanndle and use it to get the sequence name
    Printf("The name of the selected sequence is: %s", IntToHandle(handleInt).name)
end

IsClassDerivedFrom Official Docs

Signature

IsClassDerivedFrom(string:derived_name, string:base_name): boolean:result

Description

The IsClassDerivedFrom Lua function returns a boolean indicating if a class is derived from a different class.

Arguments

string: derived_name
string: base_name

Returns

boolean: result

Example

This example checks if a class is derived from a different class and returns useful feedback.

return function()
    -- Set the value of the two strings.
    local derivedName = "World"
    local baseName = "Group"
    -- Check if the derivedName is the name of a class derived from the baseName class.
    local isDerived = IsClassDerivedFrom(derivedName, baseName)
    -- Provide feedback.
    if isDerived then
        Printf(derivedName .. " is derived from " .. baseName)
    else
        Printf(derivedName .. " is not derived from " .. baseName)
    end
end

IsObjectValid Official Docs

Signature

IsObjectValid(light_userdata:handle): boolean:valid

Description

The IsObjectValid function returns a boolean true or nil depending on whether the supplied argument is a valid object.

Arguments

light_userdata: handle

Returns

boolean: valid

Example

This example below examines if “Root()” is a valid object and prints meaningful feedback:

return function()
    --Create a variable with the possible object
    local myObject = Root()
    --Check if it is an object
    local myReturn = IsObjectValid(myObject)
    --Print the result
    if myReturn == nil then
        ErrPrintf("It is not a valid object")
    else
        Printf("It is an object")
    end
end

Keyboard

Signature

Keyboard(integer:display_index, string:type('press', 'char', 'release')[ ,string:char(for type 'char') or string:keycode, boolean:shift, boolean:ctrl, boolean:alt, boolean:numlock]): nothing

Arguments

integer: display_index
string: type(‘press’, ‘char’, ‘release’)
string (optional): char(for type ‘char’) or string:keycode
boolean: shift
boolean: ctrl
boolean: alt
boolean (optional): numlock

Returns

No Return

KeyboardObj Official Docs

Signature

KeyboardObj(nothing): light_userdata:handle

Description

The KeyboardObj function returns the handle to the first found keyboard object.

Arguments

No Arguments

Returns

light_userdata: handle

Example

This example prints the information of the keyboard object. It uses the Dump() function:

return function()
    -- Print all informatin about the KeyboardObj object
    Printf("=============== START OF DUMP ===============")
    KeyboardObj():Dump()
    Printf("================ END OF DUMP ================")
end

LoadExecConfig

Signature

LoadExecConfig(light_userdata:executor): nothing

Arguments

light_userdata: executor

Returns

No Return

MasterPool Official Docs

Signature

MasterPool(nothing): light_userdata:handle

Description

The MasterPool Lua function returns the handle to the masters.

Arguments

No Arguments

Returns

light_userdata: handle

Example

This example prints the information of the MasterPool object. It uses the Dump() function:

return function()
    -- Print all informatin about the MasterPool object
    Printf("=============== START OF DUMP ===============")
    MasterPool():Dump()
    Printf("================ END OF DUMP ================")
end

MessageBox Official Docs

Signature

MessageBox({title:string,[, string:backColor][, integer:timeout (ms)][, boolean:timeoutResultCancel][, integer:timeoutResultID][, string:icon][, string:titleTextColor][, string:messageTextColor] [, boolean:autoCloseOnInput] string:message[, integer:message_align_h(Enums.AlignmentH)][, integer:message_align_v(Enums.AlignmentV)][, integer|lightuserdata:display], commands:{array of {integer:value, string:name[, integer:order]}}, inputs:{array of {string:name, string:value, string:blackFilter, string:whiteFilter, string:vkPlugin, integer:maxTextLength[, integer:order]}}, states:{array of {string:name, boolean:state[, integer:order]}, selectors:{array of {name:string, integer:selectedValue, values:table[, type:integer 0-swipe, 1-radio][, integer:order]} }): {boolean:success, integer:result, inputs:{array of [string:name] = string:value}, states:{array of [string:name] = boolean:state}, selectors:{array of [string:name] = integer:selected-value}}

Description

The MessageBox Lua function is used to create pop-up message boxes. These can be simple or complex information pop-ups with many different options and user inputs.

Arguments

{title:string,[, string:backColor][, integer:timeout (ms)][, boolean:timeoutResultCancel][, integer:timeoutResultID][, string:icon][, string:titleTextColor][, string:messageTextColor] [, boolean:autoCloseOnInput] string:message[, integer:message_align_h(Enums.AlignmentH)][, integer:message_align_v(Enums.AlignmentV)][, integer|lightuserdata:display], commands:{array of {integer:value, string:name[, integer:order]}}, inputs:{array of {string:name, string:value, string:blackFilter, string:whiteFilter, string:vkPlugin, integer:maxTextLength[, integer:order]}}, states:{array of {string:name, boolean:state[, integer:order]}, selectors:{array of {name:string, integer:selectedValue, values:table[, type:integer 0-swipe, 1-radio][, integer:order]} }:

Returns

{boolean:success, integer:result, inputs:{array of [string:name] = string:value}, states:{array of [string:name] = boolean:state}, selectors:{array of [string:name] = integer:selected-value}}:

Example

There are six different examples demonstrating different elements of the message box. The elements can be combined, but the examples highlight different functions.

return function ()
    -- This creates a small pop-up with a single button.
    local returnTable = MessageBox(
        {
            title = "Please confirm This",
            commands = {{value = 1, name = "Confirm"}}
        }
    )

    -- Print the content of the returned table.
    Printf("Success = "..tostring(returnTable.success))
    Printf("Result = "..returnTable.result)
end

Mouse

Signature

Mouse(integer:display_index, string:type('press', 'move', 'release')[ ,string:button('Left', 'Middle', 'Right' for 'press', 'release') or integer:abs_x, integer:abs_y)]): nothing

Arguments

integer: display_index
string: type(‘press’, ‘move’, ‘release’)
string (optional): button(‘Left’, ‘Middle’, ‘Right’ for ‘press’, ‘release’) or integer:abs_x
integer (optional): abs_y)

Returns

No Return

MouseObj Official Docs

Signature

MouseObj(nothing): light_userdata:handle

Description

The MouseObj function returns the handle to the first found mouse object.

Arguments

No Arguments

Returns

light_userdata: handle

Example

This example prints the information of the mouse object. Is uses the Dump() function:

return function()
    -- Print all informatin about the MouseObj object
    Printf("=============== START OF DUMP ===============")
    MouseObj():Dump()
    Printf("================ END OF DUMP ================")
end

NeedShowSave Official Docs

Signature

NeedShowSave(nothing): boolean:need_show_save

Description

The NeedShowSave Lua function returns a boolean indicating if there are unsaved changes to the showfile.

Arguments

No Arguments

Returns

boolean: need_show_save

Example

This example prints feedback indicating if the show file should be saved or not.

return function ()
    -- Check if the show should be saved.
    if NeedShowSave() then
        Printf("You should save your showfile.")
    else
        Printf("You do not need to save your showfile.")
    end
end

NextDmxModeFixture

Signature

NextDmxModeFixture(light_userdata:fixture): light_userdata:fixture

Arguments

light_userdata: fixture

Returns

light_userdata: fixture

ObjectList Official Docs

Signature

ObjectList(string:address[, {['selected_as_default'=boolean:enabled], ['reverse_order'=boolean:enabled]}): {light_userdata:handles}

Description

The ObjectList Lua function returns a table with handles. The table is created based on a string input that should create a selection.

Arguments

string: address
{['selected_as_default'=boolean:enabled], ['reverse_order'=boolean:enabled]} (optional):

Returns

{light_userdata:handles}:

Example

This example returns the names and patch addresses of fixtures 1 through 10. It assumes these fixtures exist - if they do not, then it returns an error text.

return function()
    -- Create a list of handles based on the "Fixture 1 Thru 10" selection and store it in a table.
    local myObjects = ObjectList("Fixture 1 Thru 10", {reverse_order=true})
    -- If the selection returned a table, then go through all elements and print information of the object.
    if myObjects~= nil then
        for i in pairs(myObjects) do
            Printf("Fixture: " .. myObjects[i].name .. " - Patch: " ..myObjects[i].patch)
        end
    else
        ErrPrintf("An error occured. Does Fixture 1 Thru 10 exist?")
    end
end

OpenMessageQueue

Signature

OpenMessageQueue(string:queue name): boolean:success

Arguments

string: queue name

Returns

boolean: success

OverallDeviceCertificate

Signature

OverallDeviceCertificate(nothing): light_userdata:handle

Arguments

No Arguments

Returns

light_userdata: handle

Patch Official Docs

Signature

Patch(nothing): light_userdata:handle

Description

The Patch Lua function returns a handle to the patch object.

Arguments

No Arguments

Returns

light_userdata: handle

Example

This example prints the data connected to the handle. It uses the Dump() function:

return function()
    -- This example dumps all information about the patch object
    Printf("=============== START OF DUMP ===============")
    Patch():Dump()
    Printf("================ END OF DUMP ================")
end

PluginVars

Signature

PluginVars([string:plugin_name]): light_userdata:plugin_preferences

Arguments

string (optional): plugin_name

Returns

light_userdata: plugin_preferences

PopupInput

Signature

PopupInput({title:str, caller:handle, items:table:{{'str'|'int'|'lua'|'handle', name, type-dependent}...}, selectedValue:str, x:int, y:int, target:handle, render_options:{left_icon, number, right_icon}, useTopLeft:bool, properties:{prop:value}, add_args:{FilterSupport='Yes'/'No'}}): integer:selected_index, string:selected_value

Arguments

{title:str, caller:handle, items:table:{{'str'|'int'|'lua'|'handle', name, type-dependent}...}, selectedValue:str, x:int, y:int, target:handle, render_options:{left_icon, number, right_icon}, useTopLeft:bool, properties:{prop:value}, add_args:{FilterSupport='Yes'/'No'}}:

Returns

integer: selected_index
string: selected_value

PrepareWaitObjectChange

Signature

PrepareWaitObjectChange(light_userdata:handle[ ,integer:change_level_threshold]): boolean:true or nothing

Arguments

light_userdata: handle
integer (optional): change_level_threshold

Returns

boolean: true or nothing

Printf Official Docs

Signature

Printf(string:formatted_command ...): nothing

Description

The Printf Lua function prints a string in the Command Line History and System Monitor.

Arguments

string: formatted_command …

Returns

No Return

Example

This example prints “Hello World!” in the Command Line History:

return function()
    Printf("Hello World!")
end

Programmer Official Docs

Signature

Programmer(nothing): light_userdata:handle

Description

The Programmer Lua function references the current programmer object.

Arguments

No Arguments

Returns

light_userdata: handle

Example

This example uses the Dump() function on the programmer object:

return function ()
    -- Dumps information about the programmer object.
    Printf("=============== START OF DUMP ===============")
    Programmer():Dump()
    Printf("================ END OF DUMP ================")
end

ProgrammerPart Official Docs

Signature

ProgrammerPart(nothing): light_userdata:handle

Description

The ProgrammerPart Lua function references the current programmer part object.

Arguments

No Arguments

Returns

light_userdata: handle

Example

This example uses the Dump() function on the programmer part object:

return function ()
    -- Dumps information about the current programmer part object.
    Printf("=============== START OF DUMP ===============")
    ProgrammerPart():Dump()
    Printf("================ END OF DUMP ================")
end

Pult Official Docs

Signature

Pult(nothing): light_userdata:handle

Description

The Pult Lua function returns a handle to the current “Pult” object at position Root/GraphicsRoot/PultCollect. The “Pult” object contains display and device information.

Arguments

No Arguments

Returns

light_userdata: handle

Example

This example prints the data connected to the handle. It uses the Dump() function:

return function()
    -- The following prints the dump for the pult object
    Printf("=============== START OF DUMP ===============")
    Pult():Dump()
    Printf("================ END OF DUMP ================")
end

RefreshLibrary

Signature

RefreshLibrary(light_userdata:handle): nothing

Arguments

light_userdata: handle

Returns

No Return

ReleaseType Official Docs

Signature

ReleaseType(nothing): string:releasetype

Description

The ReleaseType Lua function returns a string with the type of release for the MA software. All the software versions available from MA Lighting will return “Release”. Internally and during development, there can be other release types.

Arguments

No Arguments

Returns

string: releasetype

Example

This example prints the release type in the Command Line History:

return function()
    Printf("The ReleaseType is "..ReleaseType())
end

RemoteCallRunning New

Signature

RemoteCallRunning(nothing): boolean:remotecall_is_running

Arguments

No Arguments

Returns

boolean: remotecall_is_running

RemoteCommand

Signature

RemoteCommand(string:ip, string:command): boolean:success

Arguments

string: ip
string: command

Returns

boolean: success

Root Official Docs

Signature

Root(nothing): light_userdata:handle

Description

The Root Lua function returns a handle to the object at the root position.

Arguments

No Arguments

Returns

light_userdata: handle

SaveExecConfig

Signature

SaveExecConfig(light_userdata:executor): nothing

Arguments

light_userdata: executor

Returns

No Return

SelectedDrive

Signature

SelectedDrive(nothing): light_userdata:handle

Arguments

No Arguments

Returns

light_userdata: handle

SelectedFeature Official Docs

Signature

SelectedFeature(nothing): light_userdata:handle

Description

The SelectedFeature Lua function returns the handle of the selected feature.

Arguments

No Arguments

Returns

light_userdata: handle

Example

This example prints all information about the selected feature in the Command Line History using the Dump() function:

return function ()
    -- The following prints the dump for the selected feature object
    Printf("=============== START OF DUMP ===============")
    SelectedFeature():Dump()
    Printf("================ END OF DUMP ================")
end

SelectedLayout Official Docs

Signature

SelectedLayout(nothing): light_userdata:handle

Description

The SelectedLayout Lua function returns the handle of the selected layout.

Arguments

No Arguments

Returns

light_userdata: handle

Example

This example prints all information about the selected layout in the Command Line History using the Dump() function:

return function ()
    -- The following prints the dump for the selected layout object
    Printf("=============== START OF DUMP ===============")
    SelectedLayout():Dump()
    Printf("================ END OF DUMP ================")
end

SelectedSequence Official Docs

Signature

SelectedSequence(nothing): light_userdata:handle

Description

The SelectedSequence Lua function returns the handle of the selected sequence.

Arguments

No Arguments

Returns

light_userdata: handle

Example

This example prints all information about the selected sequence in the Command Line History using the Dump() function:

return function ()
    -- The following prints the dump for the selected sequence object
    Printf("=============== START OF DUMP ===============")
    SelectedSequence():Dump()
    Printf("================ END OF DUMP ================")
end

SelectedTimecode Official Docs

Signature

SelectedTimecode(nothing): light_userdata:handle

Description

The SelectedTimecode Lua function returns the handle of the selected timecode object.

Arguments

No Arguments

Returns

light_userdata: handle

Example

This example prints all information about the selected timecode show in the Command Line History using the Dump() function:

return function ()
    -- The following prints the dump for the selected timecode object
    local myTimecodeShow = SelectedTimecode()
    if myTimecodeShow ~= nil then
        Printf("=============== START OF DUMP ===============")
        myTimecodeShow:Dump()
        Printf("================ END OF DUMP ================")
    end
end

SelectedTimer Official Docs

Signature

SelectedTimer(nothing): light_userdata:handle

Description

The SelectedTimer Lua function returns the handle of the selected timer object.

Arguments

No Arguments

Returns

light_userdata: handle

Example

This example prints all information about the selected timer in the Command Line History using the Dump() function:

return function ()
    -- The following prints the dump for the selected timer object
    local myTimer = SelectedTimer()
    if myTimer ~= nil then
        Printf("=============== START OF DUMP ===============")
        myTimer:Dump()
        Printf("================ END OF DUMP ================")
    end
end

Selection Official Docs

Signature

Selection(nothing): light_userdata:handle

Description

The Selection Lua function returns a handle to the object holding the current selection of fixtures.

Arguments

No Arguments

Returns

light_userdata: handle

Example

This example prints the information of the Selection object in the Command Line History using the Dump() function:

return function ()
    -- The following prints the dump for the object for the selection
    Printf("=============== START OF DUMP ===============")
    Selection():Dump()
    Printf("================ END OF DUMP ================")
end

SelectionComponentX

Signature

SelectionComponentX(nothing): integer:min, integer:max, integer:index, integer:block, integer:group

Arguments

No Arguments

Returns

integer: min
integer: max
integer: index
integer: block
integer: group

SelectionComponentY

Signature

SelectionComponentY(nothing): integer:min, integer:max, integer:index, integer:block, integer:group

Arguments

No Arguments

Returns

integer: min
integer: max
integer: index
integer: block
integer: group

SelectionComponentZ

Signature

SelectionComponentZ(nothing): integer:min, integer:max, integer:index, integer:block, integer:group

Arguments

No Arguments

Returns

integer: min
integer: max
integer: index
integer: block
integer: group

SelectionCount Official Docs

Signature

SelectionCount(nothing): integer:amount_of_selected_subfixtures

Description

The SelectionCount Lua function returns a number indicating the total amount of currently selected fixtures.

Arguments

No Arguments

Returns

integer: amount_of_selected_subfixtures

Example

This example prints the number of fixtures in the current selection to the Command Line History:

return function()
    Printf('Number of fixtures in the current selection: %i', SelectionCount())
end

SelectionFirst Official Docs

Signature

SelectionFirst(nothing): integer:first_subfixture_index, integer:x, integer:y, integer:z

Description

The SelectionFirst Lua function returns a set of integers for the selection’s first fixture. It is the patch index number and the XYZ grid values in the selection grid.

Arguments

No Arguments

Returns

integer: first_subfixture_index
integer: x
integer: y
integer: z

Example

This example prints the returned numbers of the first fixture in the selection, to the Command Line History:

return function()
    -- Store the return in a local variable
    local fixtureIndex, gridX, gridY, gridZ = SelectionFirst();

    -- Cancel the plugin if no fixture is selected
    assert(fixtureIndex,"Please select a fixture and try again.");

    -- Print the index number of the first fixture in the selection
    Printf("First selected fixture has index number: "..fixtureIndex
        .." and gridX value: "..gridX
        .." and gridY value: "..gridY
        .." and gridZ value: "..gridZ);
end

SelectionNext Official Docs

Signature

SelectionNext(integer:current_subfixture_index): integer:next_subfixture_index, integer:x, integer:y, integer:z

Description

The SelectionNext function returns a set of integers for the next fixture in a selection based on the index number input as an argument. It is the index number in the patch and the XYZ grid values in the selection grid.

Arguments

integer: current_subfixture_index

Returns

integer: next_subfixture_index
integer: x
integer: y
integer: z

Example

This example prints the patch index number and grid positions of all the fixtures in the current selection:

return function()
    -- Store the return in a local variable
    local fixtureIndex, gridX, gridY, gridZ = SelectionFirst()

    -- Cancel the plugin if no fixture is selected
    assert(fixtureIndex,"Please select a (range of) fixture(s) and try again.")

    -- Loop that prints the index and gridpositions of all the fixtures in the selection
    while fixtureIndex do
        Printf('The fixture has index number: %i and gridposition %i / %i / %i',
          fixtureIndex, gridX, gridY, gridZ);

        -- Here is SelectionNext actually used to find the next fixture in the selection
        fixtureIndex, gridX, gridY, gridZ = SelectionNext(fixtureIndex)
    end
end

SelectionNotifyBegin

Signature

SelectionNotifyBegin(light_userdata:associated_context): nothing

Arguments

light_userdata: associated_context

Returns

No Return

SelectionNotifyEnd

Signature

SelectionNotifyEnd(light_userdata:associated_context): nothing

Arguments

light_userdata: associated_context

Returns

No Return

SelectionNotifyObject

Signature

SelectionNotifyObject(light_userdata:object_to_notify_about): nothing

Arguments

light_userdata: object_to_notify_about

Returns

No Return

SelectionTable New

Signature

SelectionTable(nothing): table of subfixture_index

Arguments

No Arguments

Returns

table of subfixture_index:

SendLuaMessage

Signature

SendLuaMessage(string:ip/station, string:channel name, table:data): boolean:success

Arguments

string: ip/station
string: channel name
table: data

Returns

boolean: success

SerialNumber Official Docs

Signature

SerialNumber(nothing): string:serialnumber

Description

The SerialNumber Lua function returns the serial number of the grandMA3 hardware or grandMA3 onPC.

Arguments

No Arguments

Returns

string: serialnumber

Example

This example prints the serial number in the Command Line History:

return function()
    Printf("Serial number: " .. SerialNumber())
end

SetBlockInput Official Docs Changed

Signature

SetBlockInput(boolean:block[, boolean:show_info]): nothing

Description

The SetBlockInput function is an internal function used during the system tests. It stops input from USB-connected keyboards and mouse. The built-in keyboard on some models is internally connected using a USB connection, which is also blocked by this function. The block affects the station where the function is executed.

Arguments

boolean: block
boolean (optional): show_info

Returns

No Return

Example

This example blocks mouse and keyboard input for 10 seconds:

return function()
    -- Set a variable for yield time in seconds
    yieldTime = 10
    -- Set the block to true
    SetBlockInput(true)
    -- Wait the [yieldtime]
    coroutine.yield(yieldTime)
    -- Unblock the station
    SetBlockInput(false)
end

SetColor

Signature

SetColor(string:color_model('RGB', 'xyY', 'Lab', 'XYZ', 'HSB'), float:tripel1, float:tripel2, float:tripel3, float:brightness, float:quality, boolean:const_brightness): integer:flag

Arguments

string: color_model(‘RGB’, ‘xyY’, ‘Lab’, ‘XYZ’, ‘HSB’)
float: tripel1
float: tripel2
float: tripel3
float: brightness
float: quality
boolean: const_brightness

Returns

integer: flag

SetLED Official Docs

Signature

SetLED(light_userdata:usb_device_object_handle, table:led_values): nothing

Description

The SetLED Lua function sends a table with a set of LED brightness values to an MA3Module. After around two seconds, the system automatically sets the LED values to what it believes it should be.

Arguments

light_userdata: usb_device_object_handle
table: led_values

Returns

No Return

Example

This example sets the LEDs on encoder 1 to green on a full-size console:

return function()
    -- Create the LED table
    local myLedTable = {}
    -- Fill the table with default "release" value
    for index=1,256 do
        myLedTable[index] = -1;
    end
    -- Set values in the table
    -- Encoder_inside1 = green
    myLedTable[7] = 0
    myLedTable[10] = 255
    myLedTable[22] = 0
    -- Encoder_outside1 = green
    myLedTable[8] = 0
    myLedTable[11] = 255
    myLedTable[23] = 0
    -- Get the handle for the MasterModule on a console
    local usbDeviceHandle = Root().UsbNotifier.MA3Modules["UsbDeviceMA3 2"]
    -- Set the values for the LEDs
    SetLED(usbDeviceHandle, myLedTable)
end

SetProgPhaser

Signature

SetProgPhaser(integer:ui_channel_index, {['abs_preset'=light_userdata:handle], ['rel_preset'=light_userdata:handle], ['fade'=number:seconds], ['delay'=number:seconds], ['speed'=number:hz], ['phase'=number:degree], ['measure'=number:percent], ['gridpos'=integer:value], {['channel_function'=integer:value], ['absolute'=number:percent], ['absolute_value'=integer:value], ['relative'=number:percent], ['accel'=number:percent[, 'accel_type'=integer:enum_value(Enums.SplineType)]], ['decel'=number:percent[, 'decel_type'=integer:enum_value(Enums.SplineType)]], ['trans'=number:percent], ['width'=number:percent], ['integrated'=light_userdata:preset_handle]}}): nothing

Arguments

integer: ui_channel_index
{['abs_preset'=light_userdata:handle], ['rel_preset'=light_userdata:handle], ['fade'=number:seconds], ['delay'=number:seconds], ['speed'=number:hz], ['phase'=number:degree], ['measure'=number:percent], ['gridpos'=integer:value], {['channel_function'=integer:value], ['absolute'=number:percent], ['absolute_value'=integer:value], ['relative'=number:percent], ['accel'=number:percent[, 'accel_type'=integer:enum_value(Enums.SplineType)]], ['decel'=number:percent[, 'decel_type'=integer:enum_value(Enums.SplineType)]], ['trans'=number:percent], ['width'=number:percent], ['integrated'=light_userdata:preset_handle]}}:

Returns

No Return

SetProgPhaserValue

Signature

SetProgPhaserValue(integer:ui_channel_index, integer:step, {['channel_function'=integer:value], ['absolute'=number:percent], ['absolute_value'=integer:value], ['relative'=number:percent], ['accel'=number:percent[, 'accel_type'=integer:enum_value(Enums.SplineType)]], ['decel'=number:percent[, 'decel_type'=integer:enum_value(Enums.SplineType)]], ['trans'=number:percent], ['width'=number:percent], ['integrated'=light_userdata:preset_handle]}): nothing

Arguments

integer: ui_channel_index
integer: step
{['channel_function'=integer:value], ['absolute'=number:percent], ['absolute_value'=integer:value], ['relative'=number:percent], ['accel'=number:percent[, 'accel_type'=integer:enum_value(Enums.SplineType)]], ['decel'=number:percent[, 'decel_type'=integer:enum_value(Enums.SplineType)]], ['trans'=number:percent], ['width'=number:percent], ['integrated'=light_userdata:preset_handle]}:

Returns

No Return

SetProgress Official Docs

Signature

SetProgress(integer:progressbar_index, integer:value): nothing

Description

The SetProgress Lua function defines a value on the range for a progress bar. A handle input argument defines the progress bar. The progress bar needs have been created using the StartProgress function.

Arguments

integer: progressbar_index
integer: value

Returns

No Return

Example

This example sets a range value for the progress bar created using the example in the StartProgress topic (link above):

return function()
    -- Sets the current value to 5 for a progress bar with the matching handle
    SetProgress(progressHandle, 5)
end

SetProgressRange Official Docs

Signature

SetProgressRange(integer:progressbar_index, integer:start, integer:end): nothing

Description

The SetProgressRange Lua function defines a range for a progress bar.

Arguments

integer: progressbar_index
integer: start
integer: end

Returns

No Return

Example

This example sets a range for the progress bar created using the example in the StartProgress topic (link above):

return function()
    -- Sets the range of a progress bar with the matching handle
    SetProgressRange(progressHandle, 1, 10)
end

SetProgressText Official Docs

Signature

SetProgressText(integer:progressbar_index, string:text): nothing

Description

The SetProgressText Lua function defines a text string to be displayed in a progress bar next to the progress bar title text. The title cannot be changed after creation, but this text can be changed. It could be used to describe the current step in the progress.

Arguments

integer: progressbar_index
string: text

Returns

No Return

Example

This example sets a text string for the progress bar created using the example in the StartProgress topic (link above):

return function()
    -- Sets the text next to progress title
    SetProgressText(progressHandle, "- This is text next to the progress title")
end

SetVar Official Docs

Signature

SetVar(light_userdata:variables, string:varname, value): boolean:success

Description

The SetVar Lua function sets a value to a specific variable in a set of variables. To learn more about the variables in plugins, look at the Variable Functions topic.

Arguments

light_userdata: variables
string: varname
value:

Returns

boolean: success

Example

This example sets a value to the variable called “myUserVar” in the set of user variables if it exists.

return function()
    -- Sets the value of user variable "myUserVar" to "Hello World" and store the returned boolean in a Lua variable
    local success = SetVar(UserVars(), "myUserVar", "Hello World")
    -- Prints the ressult
    if success then
        Printf("Variable is stored.")
    else
        Printf("Variable is NOT stored!")
    end
end

ShowData Official Docs

Signature

ShowData(nothing): light_userdata:handle

Description

ShowData is an object-free function that returns a handle to the object at position Root/ShowData.

Arguments

No Arguments

Returns

light_userdata: handle

ShowSettings Official Docs

Signature

ShowSettings(nothing): light_userdata:handle

Description

ShowSettings is an object-free function that returns a handle to the object at Root/ShowData/ShowSettings.

Arguments

No Arguments

Returns

light_userdata: handle

Example

This simple example prints the information of the ShowSettings object using the Dump() function:

return function ()
    -- The following prints the dump for the object for the show settings
    Printf("=============== START OF DUMP ===============")
    ShowSettings():Dump()
    Printf("================ END OF DUMP ================")
end

StartProgress Official Docs

Signature

StartProgress(string:name): integer:progressbar_index

Description

The StartProgress Lua function creates and displays a progress bar on all screens. A string input argument creates a title for the progress bar. The function returns a handle that is used to further interact with the progress bar.

Arguments

string: name

Returns

integer: progressbar_index

Example

This creates and displays a progress bar on all screens. The progress bar does not disappear using this example - see the example in the StopProgress (link above) function to remove:

return function()
    -- Create and display a progress bar with a title
    -- IMPORTANT: The Lua variable 'progressHandle' is needed to remove the progressbar again - StopProgress()
    progressHandle = StartProgress("ProgressBar Title")
end

StopProgress Official Docs

Signature

StopProgress(integer:progressbar_index): nothing

Description

The StopProgress Lua function removes a progress bar. A handle input argument defines which progress bar it removes. The progress bar must exist before it can be removed. Progress bars are created using the StartProgress function.

Arguments

integer: progressbar_index

Returns

No Return

Example

This example stops the progress bar created using the example in the StartProgress topic (link above):

return function()
    -- Stops and closes the progress bar with the matching handle
    StopProgress(progressHandle)
end

StrToHandle Official Docs

Signature

StrToHandle(string:handle(in H#... format)): light_userdata:handle

Arguments

string: handle(in H#… format)

Returns

light_userdata: handle

Example

This example prints the handle hex number for the selected sequence. It also converts the string back to a handle and uses this to print the name of the sequence:

return function()
    -- Store a variable with the string of the handle converted to hex
    local mySeqStr = HandleToStr(SelectedSequence())
    -- Print some feedback with the handle in a string version
    Printf("The handle for the selected sequence (string version): %s", mySeqStr)
    -- Print some feedback where the string is converted back to a handle
    Printf("The name of the selected sequence is: %s", StrToHandle(mySeqStr).name)
end

SyncFS

Signature

SyncFS(nothing): nothing

Arguments

No Arguments

Returns

No Return

TextInput Official Docs

Signature

TextInput([string:title[, string:value[, integer:x[, integer:y]]]]): string:value

Description

The TextInput Lua function opens a text input pop-up and returns the typed input as a string. It is part of the user interface functions.

Arguments

string (optional): title
string (optional): value
integer (optional): x
integer (optional): y

Returns

string: value

Time Official Docs

Signature

Time(nothing): integer:time

Description

The Time function returns the time (in seconds) the station has been on, as a number (float). It is basically a stopwatch that starts when the grandMA3 application starts. It is not the current time of day or the session online time.

Arguments

No Arguments

Returns

integer: time

Example

This example finds, formats, and prints the time.

return function()
    -- Get the current time
    local time = Time()

    --Calculate the different elements
    local days = math.floor(time/86400)
    local hours = math.floor((time % 86400)/3600)
    local minutes = math.floor((time % 3600)/60)
    local seconds = math.floor(time % 60)

    --Print the result
    Printf("The time is %d:%02d:%02d:%02d", days, hours, minutes, seconds)
end

Timer Official Docs

Signature

Timer(function:timer_function, integer:delay_time, integer:max_count[, function:cleanup][, light_userdata:context object]): nothing

Description

The Timer Lua function call a different function using a timer. The other function can be called multiple times using the timer interval.

Arguments

function: timer_function
integer: delay_time
integer: max_count
function (optional): cleanup]
light_userdata (optional): context object

Returns

No Return

Example

This example prints a greeting three times and then calls a clean up function:

-- Function that will be called several times.
function TimedFunction()
    -- Check the value of RunAmount and print something.
    if RunAmount 1 then
        Printf("Hello")
    else
        Printf("Hello again")
    end
    -- Add 1 to the RunAmount variable.
    RunAmount = RunAmount + 1
end

-- Cleanup function.
function TimerCleanup()
    Printf("Goodbye")
    -- Delete the RunAmount variable.
    RunAmount = nil
end

-- Function with the Timer call.
function Main()
    -- Set a wait variable.
    local waitSeconds = 1
    -- Set a variable with the number of iterations.
    local iterations = 3
    -- Create a counter variable and set it to 0.
    RunAmount = 0
    -- Call the timer function.
    Timer(TimedFunction, waitSeconds, iterations, TimerCleanup);
end

-- call the main function.
return Main

ToAddr Official Docs

Signature

ToAddr(light_userdata:handle, boolean:with_name[, boolean:use_visible_addr]): string:address

Description

The ToAddr Lua object-free function converts a handle to an address string that can be used in commands.

Arguments

light_userdata: handle
boolean: with_name
boolean (optional): use_visible_addr

Returns

string: address

Example

This example prints the address of the selected sequence in both the numbered and named versions.

return function ()
    local mySequence = SelectedSequence()
    -- Print the address to the selected sequence in number and name format.
    Printf(ToAddr(mySequence))
    Printf(ToAddr(mySequence, true))
end

Touch

Signature

Touch(integer:display_index, string:type('press', 'move', 'release'), integer:touch_id, integer:abs_x, integer:abs_y): nothing

Arguments

integer: display_index
string: type(‘press’, ‘move’, ‘release’)
integer: touch_id
integer: abs_x
integer: abs_y

Returns

No Return

TouchObj Official Docs

Signature

TouchObj(nothing): light_userdata:handle

Description

The TouchObj function returns the handle to the first found touch object.

Arguments

No Arguments

Returns

light_userdata: handle

Example

This example prints information about the touch object using the Dump() function:

return function()
    -- Print all informatin about the TouchObj object
    Printf("=============== START OF DUMP ===============")
    TouchObj():Dump()
    Printf("================ END OF DUMP ================")
end

Unhook Official Docs

Signature

Unhook(integer:hook_id): nothing

Description

The Unhook Lua function removes a hook.

Arguments

integer: hook_id

Returns

No Return

Example

This example unhooks the hook created using the example in the HookObjectChange - please run that example before this one.

return function()
    -- Unhooks the specific Hook integer ID.
    Unhook(SequenceHookId)
end

UnhookMultiple Official Docs

Signature

UnhookMultiple(function:callback(can be nil), light_userdata:handle to target(can be nil), light_userdata:handle to context (can be nil)): integer:amount of removed hooks

Description

The UnhookMultiple Lua function unhooks multiple hooks based on an input. This input acts like a filter to identify all the hooks that should be unhooked.

Arguments

function: callback(can be nil)
light_userdata: handle to target(can be nil)
light_userdata: handle to context (can be nil)

Returns

integer: amount of removed hooks

Example

This example unhooks all hooked related to the function created in the example for the HookObjectChange - please run the example from that topic before running this one.

return function ()
    -- Unhooks all hooks related to the "MySequencePoolCallback" function.
    local amount = UnhookMultiple(MySequencePoolCallback)
    -- Print how many hooks that were unhooked.
    Printf(amount .. " hook(s) were unhooked.")
end

UserVars Official Docs

Signature

UserVars(nothing): light_userdata:user_variables

Arguments

No Arguments

Returns

light_userdata: user_variables

Example

This example sets, gets, and deletes a user variable:

return function()
    -- Stores a local Lua variable with the handle for the user variables.
    local variableSection = UserVars()

    -- Sets a user variable with an integer value using the SetVar function.
    SetVar(variableSection, "myUserVar", 42)

    -- Prints the user variable using the GetVar function.
    Printf("The value  of myUserVar is: " .. GetVar(variableSection, "myUserVar"))

    -- Deletes the user variable using the DelVar function.
    DelVar(variableSection, "myUserVar")
end

Version Official Docs

Signature

Version(nothing): string:version

Description

The Version Lua function returns the software version.

Arguments

No Arguments

Returns

string: version

Example

This example prints the software version in the Command Line History:

return function()
    Printf("Software version: %s", Version())
end

WaitModal

Signature

WaitModal([number:seconds to wait]): handle to modal overlay or nil on failure(timeout)

Arguments

number (optional): seconds to wait

Returns

handle to modal overlay or nil on failure(timeout):

WaitObjectDelete

Signature

WaitObjectDelete(light_userdata:handle to UIObject[, number:seconds to wait]): boolean:true on success, nil on timeout

Arguments

light_userdata: handle to UIObject
number (optional): seconds to wait

Returns

boolean: true on success
nil on timeout:

Object API

Acquire

Signature

Acquire(light_userdata:handle[, string:class[, light_userdata:undo]]): light_userdata:child_handle

Arguments

light_userdata: handle
string (optional): class
light_userdata (optional): undo

Returns

light_userdata: child_handle

AddListChildren

Signature

AddListChildren(light_userdata:handle, light_userdata:parent[, enum{Roles}:role]): nothing

Arguments

light_userdata: handle
light_userdata: parent
enum{Roles} (optional): role

Returns

No Return

AddListChildrenNames

Signature

AddListChildrenNames(light_userdata:handle, light_userdata:parent[, enum{Roles}:role]): nothing

Arguments

light_userdata: handle
light_userdata: parent
enum{Roles} (optional): role

Returns

No Return

AddListLuaItem

Signature

AddListLuaItem(light_userdata:handle, string:name, string:value/function name, lua_function:callback reference[, <any lua type>:argument to pass to callback[, {[left={...}][right={...}]}:appearance]]): nothing

Arguments

light_userdata: handle
string: name
string: value/function name
lua_function: callback reference
<any lua type> (optional): argument to pass to callback
{[left={...}][right={...}]} (optional): appearance

Returns

No Return

AddListLuaItems

Signature

AddListLuaItems(light_userdata:handle, table{item={[1]=name, [2]=value/function name, [3]=callback reference[, [4]=argument of any lua type to pass to callback]}, ...}): nothing

Arguments

light_userdata: handle
table{item={[1]=name, [2]=value/function name, [3]=callback reference[, [4]=argument of any lua type to pass to callback]}, ...}:

Returns

No Return

AddListNumericItem

Signature

AddListNumericItem(light_userdata:handle, string:name, number:value[,light_userdata:base handle[, {[left={...}][right={...}]}:appearance]]): nothing

Arguments

light_userdata: handle
string: name
number: value
light_userdata (optional): base handle
{[left={...}][right={...}]} (optional): appearance

Returns

No Return

AddListNumericItems

Signature

AddListNumericItems(light_userdata:handle, table{item={[1]=name, [2]=integer:value}, ...}): nothing

Arguments

light_userdata: handle
table{item={[1]=name, [2]=integer:value}, ...}:

Returns

No Return

AddListObjectItem Changed

Signature

AddListObjectItem(light_userdata:handle, light_userdata:target object[, (string: explicit name[, {[boolean:appearance],[left={...}][right={...}]}:appearance] | enum{Roles}: role [, :boolean: extended_name[, {[left={...}][right={...}]}:appearance],[string:postNameText])]): nothing

Arguments

light_userdata: handle
light_userdata: target object
(string: explicit name[, {[boolean:appearance],[left={...}][right={...}]}:appearance] | enum{Roles}: role [, :boolean: extended_name[, {[left={...}][right={...}]}:appearance],[string:postNameText]) (optional):

Returns

No Return

AddListPropertyItem

Signature

AddListPropertyItem(light_userdata:handle, string:name, string:value, light_userdata:target handle[,{[left={...}][right={...}]}:appearance]): nothing

Arguments

light_userdata: handle
string: name
string: value
light_userdata: target handle
{[left={...}][right={...}]} (optional): appearance

Returns

No Return

AddListPropertyItems

Signature

AddListPropertyItems(light_userdata:handle, table{item={[1]=name, [2]=property name, [3]=target handle}, ...}): nothing

Arguments

light_userdata: handle
table{item={[1]=name, [2]=property name, [3]=target handle}, ...}:

Returns

No Return

AddListRecursiveNames

Signature

AddListRecursiveNames(light_userdata:handle, light_userdata:parent[, enum{Roles}:role]): nothing

Arguments

light_userdata: handle
light_userdata: parent
enum{Roles} (optional): role

Returns

No Return

AddListStringItem

Signature

AddListStringItem(light_userdata:handle, string:name, string:value[, {[left={...}][right={...}]}:appearance]): nothing

Arguments

light_userdata: handle
string: name
string: value
{[left={...}][right={...}]} (optional): appearance

Returns

No Return

AddListStringItems

Signature

AddListStringItems(light_userdata:handle, table{item={[1]=name, [2]=value}, ...}): nothing

Arguments

light_userdata: handle
table{item={[1]=name, [2]=value}, ...}:

Returns

No Return

Addr Official Docs

Signature

Addr(light_userdata:handle[, light_userdata:base_handle[, boolean:force_parent-based_address[, boolean:force_commandline_index-based_address]]]): string:numeric_root_address

Description

The Addr Lua object function converts a handle to an address string that can be used in commands.

Arguments

light_userdata: handle
light_userdata (optional): base_handle
boolean (optional): force_parent-based_address
boolean (optional): force_commandline_index-based_address

Returns

string: numeric_root_address

Example

This example prints different versions of the address to a cue in a sequence:

return function()
    -- Creates a cue in sequence 1
    Cmd("Store Sequence 1 Cue 100 /Merge /NoConfirmation")
    --Store a handle to the created cue
    local cueObject = ObjectList("Sequence 1 Cue 100")[1]
    --Print different version of the handle address
    Printf("ToAddr:              " .. cueObject:ToAddr())
    Printf("Addr:                " .. cueObject:Addr())
    Printf("Addr(Parent, false, false): " .. cueObject:Addr(cueObject:Parent(), false, false))
    Printf("Addr(Parent, true, false):  " .. cueObject:Addr(cueObject:Parent(), true, false))
    Printf("Addr(Parent, false, true): " .. cueObject:Addr(cueObject:Parent(), false, true))
    Printf("Addr(Parent, true, true):  " .. cueObject:Addr(cueObject:Parent(), true, true))
end

AddrNative Official Docs

Signature

AddrNative(light_userdata:handle, light_userdata:base_handle[, boolean:escape_names]]): string:numeric_root_address

Description

The AddrNative Lua object function converts a handle to an address string that can be used in commands.

Arguments

light_userdata: handle
light_userdata: base_handle
boolean (optional): escape_names

Returns

string: numeric_root_address

Example

This example prints the address of the first sequence:

return function()
    -- Stores the handle to the first sequence.
    local mySequence = DataPool().Sequences[1]
    -- Print the native address.
    Printf("The full address is: " .. mySequence:AddrNative())
    -- Stores a handle to the default DataPool.
    local myDataPool = DataPool()
    -- Print the native address to the datapool using the default datapool as a base.
    Printf("The address in the datapool is: " .. mySequence:AddrNative(myDataPool))
    -- Print the native address to the datapool, using the default datapool as a base, with names as strings.
    Printf("The address in the datapool with quotes around the names is: " .. mySequence:AddrNative(myDataPool, true))
end

Append

Signature

Append(light_userdata:handle[, string:class[, light_userdata:undo[, integer:count]]]): light_userdata:child_handle

Arguments

light_userdata: handle
string (optional): class
light_userdata (optional): undo
integer (optional): count

Returns

light_userdata: child_handle

Aquire

Signature

Aquire(light_userdata:handle[, string:class[, light_userdata:undo]]): light_userdata:child_handle

Arguments

light_userdata: handle
string (optional): class
light_userdata (optional): undo

Returns

light_userdata: child_handle

Changed

Signature

Changed(light_userdata:handle, string:change_level_enum_name): nothing

Arguments

light_userdata: handle
string: change_level_enum_name

Returns

No Return

Children Official Docs

Signature

Children(light_userdata:handle): {light_userdata:child_handles}

Description

The Children Lua function creates a table of handles for the children of an object.

Arguments

light_userdata: handle

Returns

{light_userdata:child_handles}:

Example

This example returns the name of the cues in the first sequence of the selected data pool:

return function()
    -- Stores the handle for sequence 1 in a variable.
    local mySequence = DataPool().Sequences[1]
    if mySequence ~= nil then
            -- Use the "Children()" funciton to store a table with all the children in a new variable.
        local cues = mySequence:Children()
        -- For loop that uses the length operator on the cue variable.
        for i = 1, #cues do
            -- Text is printed for each child.
            Printf("Sequence 1 Child " .. i .. " = " .. cues[i].name)
        end
    else
        ErrPrintf("Sequence could not be found.")
    end
end

ClearList

Signature

ClearList(light_userdata:handle): nothing

Arguments

light_userdata: handle

Returns

No Return

ClearUIChildren

Signature

ClearUIChildren(light_userdata:handle to UIObject): nothing

Arguments

light_userdata: handle to UIObject

Returns

No Return

CmdlineChildren

Signature

CmdlineChildren(light_userdata:handle): {light_userdata:child_handles}

Arguments

light_userdata: handle

Returns

{light_userdata:child_handles}:

CmdlinePtr

Signature

CmdlinePtr(light_userdata:handle, integer:index(1-based)): light_userdata:child_handle

Arguments

light_userdata: handle
integer: index(1-based)

Returns

light_userdata: child_handle

CommandAt

Signature

CommandAt(light_userdata:handle): nothing

Arguments

light_userdata: handle

Returns

No Return

CommandCall

Signature

CommandCall(light_userdata:handle, light_userdata:dest_handle, boolean:focus_search_allowed(default:true)): nothing

Arguments

light_userdata: handle
light_userdata: dest_handle
boolean: focus_search_allowed(default:true)

Returns

No Return

CommandCreateDefaults

Signature

CommandCreateDefaults(light_userdata:handle): nothing

Arguments

light_userdata: handle

Returns

No Return

CommandDelete

Signature

CommandDelete(light_userdata:handle): nothing

Arguments

light_userdata: handle

Returns

No Return

CommandStore

Signature

CommandStore(light_userdata:handle): nothing

Arguments

light_userdata: handle

Returns

No Return

Compare

Signature

Compare(light_userdata:handle, light_userdata:handle): boolean:is_equal, string:what_differs

Arguments

light_userdata: handle
light_userdata: handle

Returns

boolean: is_equal
string: what_differs

Copy

Signature

Copy(light_userdata:dst_handle, light_userdata:src_handle[, light_userdata:undo]): nothing

Arguments

light_userdata: dst_handle
light_userdata: src_handle
light_userdata (optional): undo

Returns

No Return

Count Official Docs

Signature

Count(light_userdata:handle): integer:child_count

Description

The Count function returns an integer number indicating the number of child objects.

Arguments

light_userdata: handle

Returns

integer: child_count

Example

This example prints the selected sequence’s number of children (cues).

return function()
    local numberChildren = SelectedSequence():Count()
    Printf("The selected Sequence has " .. numberChildren .. " cues.")
end

Create

Signature

Create(light_userdata:handle, integer:child_index(1-based)[, string:class[, light_userdata:undo]]): light_userdata:child_handle

Arguments

light_userdata: handle
integer: child_index(1-based)
string (optional): class
light_userdata (optional): undo

Returns

light_userdata: child_handle

CurrentChild

Signature

CurrentChild(light_userdata:handle): light_userdata:current_child or nothing

Arguments

light_userdata: handle

Returns

light_userdata: current_child or nothing

Delete

Signature

Delete(light_userdata:handle, integer:child_index(1-based)[, light_userdata:undo]): nothing

Arguments

light_userdata: handle
integer: child_index(1-based)
light_userdata (optional): undo

Returns

No Return

Dump Official Docs

Signature

Dump(light_userdata:handle): string:information

Description

The Dump function returns a string with information about the object, for instance, the name, class, path of the object, its properties, and children.

Arguments

light_userdata: handle

Returns

string: information

Example

These examples all print information about the selected sequence in the Command Line History.

return function ()
    -- Dump() is called on a function
    Printf("=============== START OF DUMP ===============")
    SelectedSequence():Dump()
    Printf("================ END OF DUMP ================")
end

Export Official Docs

Signature

Export(light_userdata:handle, string:file_path, string:file_name): boolean:success

Description

The Export object Lua function exports an object into an XML file.

Arguments

light_userdata: handle
string: file_path
string: file_name

Returns

boolean: success

Example

This example exports the selected sequence into an XML file:

return function()
    --SelectedSequence() creates a handle to the selected sequence.
    local selectedSequence = SelectedSequence()
    if selectedSequence == nil then
        ErrPrintf("The selected sequence could not be found.")
        return
    end
    --The path is stored in a variable.
    local exportPath = GetPath(Enums.PathType.UserSequences)
    --The actual export function.
    local success = selectedSequence:Export(exportPath, "mySelectedSequence.xml")
    --Print some feedback.
    if success then
        Printf("The sequence is exported to: " .. exportPath)
    else
        ErrPrintf("The sequence could not be exported.")
    end
end

Find

Signature

Find(light_userdata:search_start_handle, string:search_name[, string:search_class_name]): light_userdata:found_handle

Arguments

light_userdata: search_start_handle
string: search_name
string (optional): search_class_name

Returns

light_userdata: found_handle

FindListItemByName

Signature

FindListItemByName(light_userdata:handle, string:value): integer:1-based index

Arguments

light_userdata: handle
string: value

Returns

integer: 1-based index

FindListItemByValueStr

Signature

FindListItemByValueStr(light_userdata:handle, string:value): integer:1-based index

Arguments

light_userdata: handle
string: value

Returns

integer: 1-based index

FindParent

Signature

FindParent(light_userdata:search_start_handle, string:search_class_name): light_userdata:found_handle

Arguments

light_userdata: search_start_handle
string: search_class_name

Returns

light_userdata: found_handle

FindRecursive

Signature

FindRecursive(light_userdata:search_start_handle, string:search_name[, string:search_class_name]): light_userdata:found_handle

Arguments

light_userdata: search_start_handle
string: search_name
string (optional): search_class_name

Returns

light_userdata: found_handle

FindWild

Signature

FindWild(light_userdata:search_start_handle, string:search_name): light_userdata:found_handle

Arguments

light_userdata: search_start_handle
string: search_name

Returns

light_userdata: found_handle

FSExtendedModeHasDots

Signature

FSExtendedModeHasDots(light_userdata:handle to UIGrid (or derived), {r, c}:cell): boolean

Arguments

light_userdata: handle to UIGrid (or derived)
{r, c}: cell

Returns

boolean:

Get Official Docs

Signature

Get(light_userdata:handle, string:property_name[, integer:role(Enums.Roles)]): light:userdata:child or string:property (if 'role' provided - always string)

Description

The Get function returns a string with information about a specified property of the object, for instance, the object’s name, class, or path.

Arguments

light_userdata: handle
string: property_name
integer (optional): role(Enums.Roles)

Returns

light: userdata:child or string:property (if ‘role’ provided - always string)

Example

This example prints information about the “Tracking” property of the selected sequence.

return function ()
    -- SelectedSequence() creates a handle to the selected sequence.
    local selectedSequence = SelectedSequence()
    -- Check if there is a selected sequence. If not, then exit the function.
    if selectedSequence == nil then
        ErrPrintf("The selected sequence could not be found.")
        return
    end
    -- Set a variable with the property name.
    local propertyName = "Tracking"
    -- Get the value of the property.
    local propertyValue = selectedSequence:Get(propertyName)
    local propertyValueString = selectedSequence:Get(propertyName, Enums.Roles.Edit)
    -- Return some feedback.
    if propertyValue ~= nil then
        Printf("The selected sequence's property " .. propertyName.. " has the value '" .. propertyValue .. "' and a string value of '" .. propertyValueString .. "'.")
    else
        ErrPrintf("The property could not be found.")
    end
end

GetAssignedObj

Signature

GetAssignedObj(light_userdata:handle): light_userdata:handle

Arguments

light_userdata: handle

Returns

light_userdata: handle

GetChildClass Official Docs

Signature

GetChildClass(light_userdata:handle): string:class_name

Description

The GetChildClass function returns a string with the name of the class of the object’s children.

Arguments

light_userdata: handle

Returns

string: class_name

Example

This example prints the class name of the selected sequences’ children.

return function()
    -- Gets the class name of children of the selected sequence.
    Printf("The class name is " .. SelectedSequence():GetChildClass())
end

GetClass Official Docs

Signature

GetClass(light_userdata:handle): string:class_name

Description

The GetClass function returns a string with information about the class for the object.

Arguments

light_userdata: handle

Returns

string: class_name

Example

This example prints the class name of the selected sequence.

return function()
    -- Gets the class name of the selected sequence.
    Printf("The class name is " .. SelectedSequence():GetClass())
end

GetDependencies Official Docs

Signature

GetDependencies(light_userdata:handle): {light_userdata:handle}

Description

The GetDependencies function returns a table with the objects’ dependencies.

Arguments

light_userdata: handle

Returns

{light_userdata:handle}:

Example

This example prints a dump of the selected sequence’s first object in the returned table.

return function()
    -- SelectedSequence() creates a handle to the selected sequence.
    local selectedSequence = SelectedSequence()
    -- Get the dependcies for the sequence.
    local seqDependencies = selectedSequence:GetDependencies()
    -- Check if there are any dependicies and output a relevant feedback.
    if seqDependencies ~= nil then
        -- There is a dependency table returned. Print a dump of the first table element.
        Printf("=============== START OF DUMP ===============")
        seqDependencies[1]:Dump()
        Printf("================ END OF DUMP ================")
    else
        Printf("No dependencies found")
    end
end

GetDisplay

Signature

GetDisplay(light_userdata:handle to UIObject): light_userdata:display_handle

Arguments

light_userdata: handle to UIObject

Returns

light_userdata: display_handle

GetDisplayIndex

Signature

GetDisplayIndex(light_userdata:handle to UIObject): integer:display_index

Arguments

light_userdata: handle to UIObject

Returns

integer: display_index

GetExportFileName

Signature

GetExportFileName(light_userdata:handle[, boolean:camel_case_to_file_name]): string:file_name

Arguments

light_userdata: handle
boolean (optional): camel_case_to_file_name

Returns

string: file_name

GetFader Official Docs

Signature

GetFader(light_userdata:handle, {[string:token(Fader*)], [integer:index]}): float:value[0..100]

Description

The GetFader function returns a float number indicating a fader position for the object.

Arguments

light_userdata: handle
{[string:token(Fader*)], [integer:index]}:

Returns

float: value[0..100

Example

This example prints the fader positions of the Master and Rate faders for the selected sequence.

return function()
    -- SelectedSequence() creates a handle to the selected sequence.
    local selectedSequence = SelectedSequence()
    -- Get the value for the Master fader.
    local faderMasterValue = selectedSequence:GetFader({})
    -- Get the value for the Rate fader.
    local faderRateValue = selectedSequence:GetFader({token="FaderRate"})
    -- Print feedback with the values.
    Printf("The selected sequence Master fader value is: ".. tostring(faderMasterValue))
    Printf("The selected sequence Rate fader value is: ".. tostring(faderRateValue))
end

GetFaderText Official Docs

Signature

GetFaderText(light_userdata:handle, {[string:token(Fader*)], [integer:index]}): string:text

Description

The GetFaderText function returns a text string indicating a fader value for the object.

Arguments

light_userdata: handle
{[string:token(Fader*)], [integer:index]}:

Returns

string: text

Example

This example prints the fader value text of the Master and Rate faders for the selected sequence.

return function()
    -- SelectedSequence() creates a handle to the selected sequence.
    local selectedSequence = SelectedSequence()
    -- Get the value for the Master fader. Since it is the default, no token needs to be defined.
    local faderMasterText = selectedSequence:GetFaderText({})
    -- Get the value for the Rate fader.
    local faderRateText = selectedSequence:GetFaderText({token="FaderRate"})
    -- Print feedback with the values.
    Printf("The selected sequence Master fader value text is: ".. tostring(faderMasterText))
    Printf("The selected sequence Rate fader value text is: ".. tostring(faderRateText))
end

GetLineAt

Signature

GetLineAt(light_userdata:handle, integer:line_number): string:line_content

Arguments

light_userdata: handle
integer: line_number

Returns

string: line_content

GetLineCount

Signature

GetLineCount(light_userdata:handle): integer:count

Arguments

light_userdata: handle

Returns

integer: count

GetListItemAdditionalInfo New

Signature

GetListItemAdditionalInfo(light_userdata:handle, integer:index): string:value

Arguments

light_userdata: handle
integer: index

Returns

string: value

GetListItemAppearance

Signature

GetListItemAppearance(light_userdata:handle, integer:index): {left={AppearanceData}, right={AppearanceData}}

Arguments

light_userdata: handle
integer: index

Returns

{left={AppearanceData}, right={AppearanceData}}:

GetListItemButton

Signature

GetListItemButton(light_userdata:handle, integer:index): light_userdata:button or nil if not visible

Arguments

light_userdata: handle
integer: index

Returns

light_userdata: button or nil if not visible

GetListItemName

Signature

GetListItemName(light_userdata:handle, integer:index): string:name

Arguments

light_userdata: handle
integer: index

Returns

string: name

GetListItemsCount

Signature

GetListItemsCount(light_userdata:handle): integer:amount of items in the list

Arguments

light_userdata: handle

Returns

integer: amount of items in the list

GetListItemValueI64

Signature

GetListItemValueI64(light_userdata:handle, integer:index): integer:value

Arguments

light_userdata: handle
integer: index

Returns

integer: value

GetListItemValueStr

Signature

GetListItemValueStr(light_userdata:handle, integer:index): string:value

Arguments

light_userdata: handle
integer: index

Returns

string: value

GetListSelectedItemIndex

Signature

GetListSelectedItemIndex(light_userdata:handle): integer:1-based index

Arguments

light_userdata: handle

Returns

integer: 1-based index

GetOverlay

Signature

GetOverlay(light_userdata:handle to UIObject): light_userdata:overlay_handle

Arguments

light_userdata: handle to UIObject

Returns

light_userdata: overlay_handle

GetReferences Official Docs

Signature

GetReferences(light_userdata:handle): {light_userdata:handle}

Description

The GetReferences function returns a table with handles for the objects referencing this object.

Arguments

light_userdata: handle

Returns

{light_userdata:handle}:

Example

This example prints a dump of the selected sequence’s first object in the returned table.

return function()
    -- SelectedSequence() creates a handle to the selected sequence.
    local selectedSequence = SelectedSequence()
    -- Get the references for the sequence.
    local seqReferences = selectedSequence:GetReferences()
    -- Check if there are any references and output a relevant feedback.
    if seqReferences ~= nil then
        -- There is a reference table returned. Print a dump of the first table element.
        Printf("=============== START OF DUMP ===============")
        seqReferences[1]:Dump()
        Printf("================ END OF DUMP ================")
    else
        Printf("No references found")
    end
end

GetScreen

Signature

GetScreen(light_userdata:handle to UIObject): light_userdata:handle

Arguments

light_userdata: handle to UIObject

Returns

light_userdata: handle

GetUIChild

Signature

GetUIChild(light_userdata:handle to UIObject, integer:index(1-based)): light_userdata:handle to UIObject

Arguments

light_userdata: handle to UIObject
integer: index(1-based)

Returns

light_userdata: handle to UIObject

GetUIChildrenCount

Signature

GetUIChildrenCount(light_userdata:handle to UIObject): integer:count

Arguments

light_userdata: handle to UIObject

Returns

integer: count

GetUIEditor Official Docs

Signature

GetUIEditor(light_userdata:handle): string:ui_editor_name

Description

The GetUIEditor function returns a text string with the name of the UI editor for the object.

Arguments

light_userdata: handle

Returns

string: ui_editor_name

Example

This example prints the name of the selected sequence’s editor.

return function()
    -- SelectedSequence() creates a handle to the selected sequence.
    local selectedSequence = SelectedSequence()
    -- Get the name of the editor for the sequence object.
    local seqEditor = selectedSequence:GetUIEditor()
    -- Print some feedback.
    if seqEditor ~= nil then
        Printf("The name of the editor is: " .. seqEditor)
    else
        Printf("The object doesn not appear to have an editor.")
    end
end

GetUISettings Official Docs

Signature

GetUISettings(light_userdata:handle): string:ui_settings_name

Description

The GetUISettings function returns a text string with the name of the UI settings for the object.

Arguments

light_userdata: handle

Returns

string: ui_settings_name

Example

This example prints the name of the selected sequence’s settings.

return function()
    -- SelectedSequence() creates a handle to the selected sequence.
    local selectedSequence = SelectedSequence()
    -- Get the name of the editor for the sequence object.
    local seqSettings = selectedSequence:GetUISettings()
    -- Print some feedback.
    if seqSettings ~= nil then
        Printf("The name of the settings is: " .. seqSettings)
    else
        Printf("The object doesn not appear to have an editor.")
    end
end

GridCellExists

Signature

GridCellExists(light_userdata:handle to UIGrid (or derived), {r, c}:cell): boolean

Arguments

light_userdata: handle to UIGrid (or derived)
{r, c}: cell

Returns

boolean:

GridGetBase

Signature

GridGetBase(light_userdata:handle to UIGrid (or derived)): light_userdata:handle to GridBase

Arguments

light_userdata: handle to UIGrid (or derived)

Returns

light_userdata: handle to GridBase

GridGetCellData

Signature

GridGetCellData(light_userdata:handle to UIGrid (or derived), {r, c}:cell): {text, color={text, back}}

Arguments

light_userdata: handle to UIGrid (or derived)
{r, c}: cell

Returns

{text, color={text, back}}:

GridGetCellDimensions

Signature

GridGetCellDimensions(light_userdata:handle to UIGrid (or derived), {r, c}:cell): {x, y, w, h}

Arguments

light_userdata: handle to UIGrid (or derived)
{r, c}: cell

Returns

{x, y, w, h}:

GridGetData

Signature

GridGetData(light_userdata:handle to UIGrid (or derived)): light_userdata:handle to GridData

Arguments

light_userdata: handle to UIGrid (or derived)

Returns

light_userdata: handle to GridData

GridGetDimensions

Signature

GridGetDimensions(light_userdata:handle to UIGrid (or derived)): {r, c}

Arguments

light_userdata: handle to UIGrid (or derived)

Returns

{r, c}:

GridGetParentRowId

Signature

GridGetParentRowId(light_userdata:handle to UIGrid (or derived), integer: rowId): parent row id (integer) or nil (if there's no parent)

Arguments

light_userdata: handle to UIGrid (or derived)
integer: rowId

Returns

parent row id (integer) or nil (if there's no parent):

GridGetScrollCell

Signature

GridGetScrollCell(light_userdata:handle to UIGrid (or derived)): {r, c}

Arguments

light_userdata: handle to UIGrid (or derived)

Returns

{r, c}:

GridGetScrollOffset

Signature

GridGetScrollOffset(light_userdata:handle to UIGrid (or derived)): {v = {index, offset}, h={index, offset}}

Arguments

light_userdata: handle to UIGrid (or derived)

Returns

{v = {index, offset}, h={index, offset}}:

GridGetSelectedCells

Signature

GridGetSelectedCells(light_userdata:handle to UIGrid (or derived)): array of {r, c, r_UniqueId, r_GroupId, c_UniqueId, c_GroupId} cells in the selection

Arguments

light_userdata: handle to UIGrid (or derived)

Returns

array of {r, c, r_UniqueId, r_GroupId, c_UniqueId, c_GroupId} cells in the selection:

GridGetSelection

Signature

GridGetSelection(light_userdata:handle to UIGrid (or derived)): light_userdata:handle to GridSelection

Arguments

light_userdata: handle to UIGrid (or derived)

Returns

light_userdata: handle to GridSelection

GridGetSettings

Signature

GridGetSettings(light_userdata:handle to UIGrid (or derived)): light_userdata:handle to GridSettings

Arguments

light_userdata: handle to UIGrid (or derived)

Returns

light_userdata: handle to GridSettings

GridIsCellReadOnly

Signature

GridIsCellReadOnly(light_userdata:handle to UIGrid (or derived), {r, c}:cell): boolean

Arguments

light_userdata: handle to UIGrid (or derived)
{r, c}: cell

Returns

boolean:

GridIsCellVisible

Signature

GridIsCellVisible(light_userdata:handle to UIGrid (or derived), {r, c}:cell): boolean

Arguments

light_userdata: handle to UIGrid (or derived)
{r, c}: cell

Returns

boolean:

GridMoveSelection

Signature

GridMoveSelection(light_userdata:handle to UIGrid (or derived), x, y): nothing

Arguments

light_userdata: handle to UIGrid (or derived)
x:
y:

Returns

No Return

GridScrollCellIntoView

Signature

GridScrollCellIntoView(light_userdata:handle to UIGrid (or derived), {r, c}:cell): nothing

Arguments

light_userdata: handle to UIGrid (or derived)
{r, c}: cell

Returns

No Return

GridSetColumnSize

Signature

GridSetColumnSize(light_userdata:handle to UIGrid (or derived), integer: columnId, integer:size in pixels): nothing

Arguments

light_userdata: handle to UIGrid (or derived)
integer: columnId
integer: size in pixels

Returns

No Return

GridsGetColumnById

Signature

GridsGetColumnById(light_userdata:handle to UIGrid (or derived), integer: columnId): column index or nil (if there's no such visible column)

Arguments

light_userdata: handle to UIGrid (or derived)
integer: columnId

Returns

column index or nil (if there's no such visible column):

GridsGetExpandHeaderCell

Signature

GridsGetExpandHeaderCell(light_userdata:handle to UIGrid (or derived)): {r, c} or nil

Arguments

light_userdata: handle to UIGrid (or derived)

Returns

{r, c} or nil:

GridsGetExpandHeaderCellState

Signature

GridsGetExpandHeaderCellState(light_userdata:handle to UIGrid (or derived)): boolean or nil

Arguments

light_userdata: handle to UIGrid (or derived)

Returns

boolean or nil:

GridsGetLevelButtonWidth

Signature

GridsGetLevelButtonWidth(light_userdata:handle to UIGrid (or derived), {r, c}:cell): width in pixels or nil

Arguments

light_userdata: handle to UIGrid (or derived)
{r, c}: cell

Returns

width in pixels or nil:

GridsGetRowById

Signature

GridsGetRowById(light_userdata:handle to UIGrid (or derived), integer: rowId): row index or nil (if there's no such visible row)

Arguments

light_userdata: handle to UIGrid (or derived)
integer: rowId

Returns

row index or nil (if there's no such visible row):

HasActivePlayback Official Docs

Signature

HasActivePlayback(light_userdata:handle): boolean:result

Description

The HasActivePlayback Lua function returns a boolean indicating if an object has a currently active playback, for instance, if a sequence has an active cue.

Arguments

light_userdata: handle

Returns

boolean: result

Example

To return the information if the selected sequence has an active playback, create a plugin with this code:

return function()
    -- Stores the handle of the selected sequence.
    local selectedSequence = SelectedSequence()

    -- The following 'if' gives different feedback based on the playback status.
    if selectedSequence:HasActivePlayback() then
        Printf("Sequence '" ..selectedSequence.name.. "' has active playback.")
    else
        Printf("Sequence '" ..selectedSequence.name.. "' has NO active playback.")
    end
end

HasDependencies

Signature

HasDependencies(light_userdata:handle): boolean:result

Arguments

light_userdata: handle

Returns

boolean: result

HasEditSettingUI

Signature

HasEditSettingUI(light_userdata:handle): boolean:result

Arguments

light_userdata: handle

Returns

boolean: result

HasEditUI

Signature

HasEditUI(light_userdata:handle): boolean:result

Arguments

light_userdata: handle

Returns

boolean: result

HasParent

Signature

HasParent(light_userdata:handle, handle:object_to_check): nothing

Arguments

light_userdata: handle
handle: object_to_check

Returns

No Return

HasReferences

Signature

HasReferences(light_userdata:handle): boolean:result

Arguments

light_userdata: handle

Returns

boolean: result

HookDelete

Signature

HookDelete(light_userdata:handle to UIObject, function:callback to invoke on deletion[, any:argument to pass by]): boolean:true on success, nil on failure

Arguments

light_userdata: handle to UIObject
function: callback to invoke on deletion
any (optional): argument to pass by

Returns

boolean: true on success
nil on failure:

Import Official Docs

Signature

Import(light_userdata:handle, string:file_path, string:file_name): boolean:success

Description

The Import object Lua function imports an object written in XML format.

Arguments

light_userdata: handle
string: file_path
string: file_name

Returns

boolean: success

Example

This example imports the content of an XML file into the selected sequence. The file is called “MySelectedSequence”, and it is located at ”../gma3_library/datapools/sequences”. The file can be created using the example in the Export object function.

return function()
    --SelectedSequence() creates a handle to the selected sequence.
    -- The imported object will be merged into this sequence.
    local selectedSequence = SelectedSequence()
    -- Check if there is a selected sequence - if not then exit the function.
    if selectedSequence == nil then
        ErrPrintf("The selected sequence could not be found.")
        return
    end
    --The path is stored in a variable.
    local path = GetPath(Enums.PathType.UserSequences)
    --The actual import function.
    local success = selectedSequence:Import(path, "mySelectedSequence.xml")
    --Print some feedback.
    if success then
        Printf("The sequence is imported from: " .. path .. GetPathSeparator() .. "mySelectedSequence.xml")
    else
        ErrPrintf("The object could not be imported.")
    end
end

Index

Signature

Index(light_userdata:handle): integer:index

Arguments

light_userdata: handle

Returns

integer: index

InputCallFunction

Signature

InputCallFunction(light_userdata:handle, string:function name[, ...parameters to function]): <depends on function>

Arguments

light_userdata: handle
string: function name
...parameters to function (optional):

Returns

<depends on function>:

InputHasFunction

Signature

InputHasFunction(light_userdata:handle, string:function name): true or nil

Arguments

light_userdata: handle
string: function name

Returns

true or nil:

InputRun

Signature

InputRun(light_userdata:handle): nothing

Arguments

light_userdata: handle

Returns

No Return

InputSetAdditionalParameter

Signature

InputSetAdditionalParameter(light_userdata:handle, string:parameter name, string:parameter value): nothing

Arguments

light_userdata: handle
string: parameter name
string: parameter value

Returns

No Return

InputSetEditTitle

Signature

InputSetEditTitle(light_userdata:handle, string:name_value): nothing

Arguments

light_userdata: handle
string: name_value

Returns

No Return

InputSetMaxLength

Signature

InputSetMaxLength(light_userdata:handle, integer:length): nothing

Arguments

light_userdata: handle
integer: length

Returns

No Return

InputSetTitle

Signature

InputSetTitle(light_userdata:handle, string:name_value): nothing

Arguments

light_userdata: handle
string: name_value

Returns

No Return

InputSetValue

Signature

InputSetValue(light_userdata:handle, string:value): nothing

Arguments

light_userdata: handle
string: value

Returns

No Return

Insert

Signature

Insert(light_userdata:handle, integer:child_index(1-based)[, string:class[, light_userdata:undo[, integer:count]]]): light_userdata:child_handle

Arguments

light_userdata: handle
integer: child_index(1-based)
string (optional): class
light_userdata (optional): undo
integer (optional): count

Returns

light_userdata: child_handle

IsClass

Signature

IsClass(light_userdata:handle): boolean:result

Arguments

light_userdata: handle

Returns

boolean: result

IsEmpty

Signature

IsEmpty(light_userdata:handle): boolean:object_is_empty

Arguments

light_userdata: handle

Returns

boolean: object_is_empty

IsEnabled

Signature

IsEnabled(light_userdata:handle to UIObject): bool:is enabled

Arguments

light_userdata: handle to UIObject

Returns

bool: is enabled

IsListItemEmpty

Signature

IsListItemEmpty(light_userdata:handle, integer:index): nothing

Arguments

light_userdata: handle
integer: index

Returns

No Return

IsListItemEnabled

Signature

IsListItemEnabled(light_userdata:handle, integer:index): nothing

Arguments

light_userdata: handle
integer: index

Returns

No Return

IsLocked

Signature

IsLocked(light_userdata:handle): boolean:object_is_locked

Arguments

light_userdata: handle

Returns

boolean: object_is_locked

IsValid

Signature

IsValid(light_userdata:handle): boolean:result

Arguments

light_userdata: handle

Returns

boolean: result

IsVisible

Signature

IsVisible(light_userdata:handle to UIObject): bool:is visible

Arguments

light_userdata: handle to UIObject

Returns

bool: is visible

Load

Signature

Load(light_userdata:handle, string:file_path, string:file_name): boolean:success

Arguments

light_userdata: handle
string: file_path
string: file_name

Returns

boolean: success

MaxCount

Signature

MaxCount(light_userdata:handle): integer:child_count

Arguments

light_userdata: handle

Returns

integer: child_count

OverlaySetCloseCallback

Signature

OverlaySetCloseCallback(light_userdata:handle to Overlay, callbackName:string[, ctx:anything]): nothing

Arguments

light_userdata: handle to Overlay
callbackName: string
ctx (optional): anything

Returns

No Return

Parent

Signature

Parent(light_userdata:handle): light_userdata:parent_handle

Arguments

light_userdata: handle

Returns

light_userdata: parent_handle

PrepareAccess

Signature

PrepareAccess(light_userdata:handle): nothing

Arguments

light_userdata: handle

Returns

No Return

PropertyCount

Signature

PropertyCount(light_userdata:handle): integer:property_count

Arguments

light_userdata: handle

Returns

integer: property_count

PropertyInfo

Signature

PropertyInfo(light_userdata:handle, integer:property_index): {'ReadOnly'=boolean:read_only_flag, 'ExportIgnore'=boolean:export_ignore_flag, 'ImportIgnore'=boolean:import_ignore_flag, 'EnumCollection'=string:enum_collection_name}

Arguments

light_userdata: handle
integer: property_index

Returns

{'ReadOnly'=boolean:read_only_flag, 'ExportIgnore'=boolean:export_ignore_flag, 'ImportIgnore'=boolean:import_ignore_flag, 'EnumCollection'=string:enum_collection_name}:

PropertyName

Signature

PropertyName(light_userdata:handle, integer:property_index): string:property_name

Arguments

light_userdata: handle
integer: property_index

Returns

string: property_name

PropertyType

Signature

PropertyType(light_userdata:handle, integer:property_index): string:property_type

Arguments

light_userdata: handle
integer: property_index

Returns

string: property_type

Ptr Official Docs

Signature

Ptr(light_userdata:handle, integer:index(1-based)): light_userdata:child_handle

Description

The Ptr Lua function returns the handle to a child object.

Arguments

light_userdata: handle
integer: index(1-based)

Returns

light_userdata: child_handle

Example

This example prints the data connected to the first child of the selected sequence. It uses the Dump() function.

return function()
    -- SelectedSequence() creates a handle to the selected sequence.
    local selectedSequence = SelectedSequence()
    -- Check that a handle was returned - if not then exit function.
    if selectedSequence == nil then
        ErrPrintf("There is no selected sequence.")
        return
    end
    -- Get a handle to the first child object.
    local firstChild = selectedSequence:Ptr(1)
    -- Print some feedback.
    if firstChild ~= nil then
        Printf("=============== START OF DUMP ===============")
        firstChild:Dump()
        Printf("================ END OF DUMP ================")
    else
        ErrPrintf("The object do not have a child object.")
    end
end

Remove

Signature

Remove(light_userdata:handle, integer:child_index(1-based)[, light_userdata:undo]): nothing

Arguments

light_userdata: handle
integer: child_index(1-based)
light_userdata (optional): undo

Returns

No Return

RemoveListItem

Signature

RemoveListItem(light_userdata:handle, string:name): nothing

Arguments

light_userdata: handle
string: name

Returns

No Return

Resize

Signature

Resize(light_userdata:handle, integer:size): nothing

Arguments

light_userdata: handle
integer: size

Returns

No Return

Save

Signature

Save(light_userdata:handle, string:file_path, string:file_name): boolean:success

Arguments

light_userdata: handle
string: file_path
string: file_name

Returns

boolean: success

ScrollDo

Signature

ScrollDo(light_userdata:handle, integer:scroll type (see 'ScrollType' enum), integer:scroll entity (item or area, see 'ScrollParamEntity' enum), integer:value type (absolute or relative, see 'ScrollParamValueType' enum), number: value to scroll (items - 1-based), boolean: updateOpposite side): boolean:true scroll

Arguments

light_userdata: handle
integer: scroll type (see ‘ScrollType’ enum)
integer: scroll entity (item or area, see ‘ScrollParamEntity’ enum)
integer: value type (absolute or relative, see ‘ScrollParamValueType’ enum)
number: value to scroll (items - 1-based)
boolean: updateOpposite side

Returns

boolean: true scroll

ScrollGetInfo

Signature

ScrollGetInfo(light_userdata:handle, integer:scroll type (see 'ScrollType' enum)): {index(1-based), offset, visibleArea, totalArea, itemsCount, itemsOnPage} or nil

Arguments

light_userdata: handle
integer: scroll type (see ‘ScrollType’ enum)

Returns

{index(1-based), offset, visibleArea, totalArea, itemsCount, itemsOnPage} or nil:

ScrollGetItemByOffset

Signature

ScrollGetItemByOffset(light_userdata:handle, integer:scroll type (see 'ScrollType' enum), integer:offset): integer:1-based item index

Arguments

light_userdata: handle
integer: scroll type (see ‘ScrollType’ enum)
integer: offset

Returns

integer: 1-based item index

ScrollGetItemOffset

Signature

ScrollGetItemOffset(light_userdata:handle, integer:scroll type (see 'ScrollType' enum), integer:1-based item idx): integer:offset of the item or nil

Arguments

light_userdata: handle
integer: scroll type (see ‘ScrollType’ enum)
integer: 1-based item idx

Returns

integer: offset of the item or nil

ScrollGetItemSize

Signature

ScrollGetItemSize(light_userdata:handle, integer:scroll type (see 'ScrollType' enum), integer:1-based item idx): integer:size of the item of nil

Arguments

light_userdata: handle
integer: scroll type (see ‘ScrollType’ enum)
integer: 1-based item idx

Returns

integer: size of the item of nil

ScrollIsNeeded

Signature

ScrollIsNeeded(light_userdata:handle, integer:scroll type (see 'ScrollType' enum)): boolean:true if scroll of the requested type is needed

Arguments

light_userdata: handle
integer: scroll type (see ‘ScrollType’ enum)

Returns

boolean: true if scroll of the requested type is needed

SelectListItemByIndex

Signature

SelectListItemByIndex(light_userdata:handle, integer:index(1-based)): nothing

Arguments

light_userdata: handle
integer: index(1-based)

Returns

No Return

SelectListItemByName

Signature

SelectListItemByName(light_userdata:handle, string:name_value): nothing

Arguments

light_userdata: handle
string: name_value

Returns

No Return

SelectListItemByValue

Signature

SelectListItemByValue(light_userdata:handle, string:value): nothing

Arguments

light_userdata: handle
string: value

Returns

No Return

Set

Signature

Set(light_userdata:handle, string:property_name, string:property_value[, integer:override_change_level(Enums.ChangeLevel)]): nothing

Arguments

light_userdata: handle
string: property_name
string: property_value
integer (optional): override_change_level(Enums.ChangeLevel)

Returns

No Return

SetChildren

Signature

SetChildren(light_userdata:handle_of_parent, string:property_name, string:property_value[, boolean:recursive (default: false)]): nothing

Arguments

light_userdata: handle_of_parent
string: property_name
string: property_value
boolean (optional): recursive (default: false)

Returns

No Return

SetChildrenRecursive

Signature

SetChildrenRecursive(light_userdata:handle_of_parent, string:property_name, string:property_value[, boolean:recursive (default: false)]): nothing

Arguments

light_userdata: handle_of_parent
string: property_name
string: property_value
boolean (optional): recursive (default: false)

Returns

No Return

SetContextSensHelpLink

Signature

SetContextSensHelpLink(light_userdata:handle to UIObject, string:topic name): nothing

Arguments

light_userdata: handle to UIObject
string: topic name

Returns

No Return

SetEmptyListItem

Signature

SetEmptyListItem(light_userdata:handle, integer:index[, bool:empty(default:true)]): nothing

Arguments

light_userdata: handle
integer: index
bool (optional): empty(default:true)

Returns

No Return

SetEnabledListItem

Signature

SetEnabledListItem(light_userdata:handle, integer:index[, bool:enable(default:true)]): nothing

Arguments

light_userdata: handle
integer: index
bool (optional): enable(default:true)

Returns

No Return

SetFader Official Docs

Signature

SetFader(light_userdata:handle, {[float:value[0..100]], [boolean:faderEnabled], [string:token(Fader*)]}): nothing

Description

The SetFader function sets a fader to a specified level. It must be used on an object that has faders.

Arguments

light_userdata: handle
{[float:value[0..100]], [boolean:faderEnabled], [string:token(Fader*)]}:

Returns

No Return

Example

This example changes the selected sequences’ Master fader to 100% and the Time fader to 5 seconds and enables the time fader.

return function()
    -- SelectedSequence() creates a handle to the selected sequence.
    local selectedSequence = SelectedSequence()
    -- Set the master fader to 100. The FaderMaster is the default token, so it can be omitted.
    selectedSequence:SetFader({value=100.0})
    -- Set the time fader to 5 seconds and enable the fader.
    selectedSequence:SetFader({value=50.0, faderEnabled=1, token="FaderTime"})
end

SetListItemAdditionalInfo New

Signature

SetListItemAdditionalInfo(light_userdata:handle, integer:index, string:value): nothing

Arguments

light_userdata: handle
integer: index
string: value

Returns

No Return

SetListItemAppearance

Signature

SetListItemAppearance(light_userdata:handle, integer:index, {[left={...AppearanceData...}][right={...AppearanceData...}]}): nothing

Arguments

light_userdata: handle
integer: index
{[left={...AppearanceData...}][right={...AppearanceData...}]}:

Returns

No Return

SetListItemName

Signature

SetListItemName(light_userdata:handle, integer:index, string:name): nothing

Arguments

light_userdata: handle
integer: index
string: name

Returns

No Return

SetListItemValueStr

Signature

SetListItemValueStr(light_userdata:handle, integer:index, string:value): nothing

Arguments

light_userdata: handle
integer: index
string: value

Returns

No Return

SetPositionHint

Signature

SetPositionHint(light_userdata:handle, integer:x, integer:y): nothing

Arguments

light_userdata: handle
integer: x
integer: y

Returns

No Return

ShowModal

Signature

ShowModal(light_userdata:handle, callback:function): nothing

Arguments

light_userdata: handle
callback: function

Returns

No Return

ToAddr Official Docs

Signature

ToAddr(light_userdata:handle,boolean:with_name[, boolean:use_visible_addr]): string:address

Description

The ToAddr Lua object function converts a handle to an address string that can be used in commands.

Arguments

light_userdata: handle
boolean: with_name
boolean (optional): use_visible_addr

Returns

string: address

Example

This example returns the address of the first sequence of the selected data pool, prints the address in the Command Line History, and creates a grandMA3 command with a “Go” keyword in front of the address. This command is sent to the grandMA3 command line.

return function()
    -- Stores the handle in a variable.
    local mySequence = DataPool().Sequences[1]
    if mySequence ~= nil then
        -- Converts the handle to the address and store in variable.
        local mySequenceAddressName = mySequence:ToAddr(true)
        local mySequenceAddress = mySequence:ToAddr(false)
        -- Print the address to the Command Line History.
        Printf("The named address of the sequence is: " .. mySequenceAddressName)
        Printf("The system address of the sequence is: " .. mySequenceAddress)
        -- Send a 'Go' command with the address appended.
        Cmd("Go %s", mySequenceAddress)
    else
        ErrPrintf("The sequence could not be found")
    end
end

UIChildren

Signature

UIChildren(light_userdata:handle to UIObject): {light_userdata:child_handles}

Arguments

light_userdata: handle to UIObject

Returns

{light_userdata:child_handles}:

UILGGetColumnAbsXLeft

Signature

UILGGetColumnAbsXLeft(light_userdata:handle to UILayoutGrid, integer:index): integer:x

Arguments

light_userdata: handle to UILayoutGrid
integer: index

Returns

integer: x

UILGGetColumnAbsXRight

Signature

UILGGetColumnAbsXRight(light_userdata:handle to UILayoutGrid, integer:index): integer:x

Arguments

light_userdata: handle to UILayoutGrid
integer: index

Returns

integer: x

UILGGetColumnWidth

Signature

UILGGetColumnWidth(light_userdata:handle to UILayoutGrid, integer:index): integer:size

Arguments

light_userdata: handle to UILayoutGrid
integer: index

Returns

integer: size

UILGGetRowAbsYBottom

Signature

UILGGetRowAbsYBottom(light_userdata:handle to UILayoutGrid, integer:index): integer:y

Arguments

light_userdata: handle to UILayoutGrid
integer: index

Returns

integer: y

UILGGetRowAbsYTop

Signature

UILGGetRowAbsYTop(light_userdata:handle to UILayoutGrid, integer:index): integer:y

Arguments

light_userdata: handle to UILayoutGrid
integer: index

Returns

integer: y

UILGGetRowHeight

Signature

UILGGetRowHeight(light_userdata:handle to UILayoutGrid, integer:index): integer:size

Arguments

light_userdata: handle to UILayoutGrid
integer: index

Returns

integer: size

WaitChildren

Signature

WaitChildren(light_userdata:handle to UIObject, integer:expected amount of children[, number:seconds to wait]): boolean:true on success, nil on timeout or if object doesn't exist

Arguments

light_userdata: handle to UIObject
integer: expected amount of children
number (optional): seconds to wait

Returns

boolean: true on success
nil on timeout or if object doesn't exist:

WaitInit

Signature

WaitInit(light_userdata:handle to UIObject[, number:seconds to wait[, bool:force to re-init, default - false]]): boolean:true on success, nil on timeout or if object doesn't exist

Arguments

light_userdata: handle to UIObject
number (optional): seconds to wait
bool (optional): force to re-init
default - false (optional):

Returns

boolean: true on success
nil on timeout or if object doesn't exist: