Custom Lua UI by Instance

CVEDIA-RT Lua scripting engine is composed of two main groups, a UI thread that run all UI related scripts, and instance threads that are run independently on each instance.

Usually the UI thread run alls the default scripts for each UI plugin, this thread starts from the [EXE_ROOT_FOLDER]/assets/lua/ui/main.lua script and loads all the subsequent scripts from it. This causes a problem when the user needs to differentiate the UI between different instances, as he should be able to customize all the scripting without having to change the core Lua files.

Customizing UI scripts for plugins

It's possible to customize a script that can run inside a specific plugin for a specific instance, for this to happen the script must be configured inside the instance json config file under the Plugin configuration

The lua_ui_includes property will define all the scripts that contain the specified functions to run.

The lua_on_render_ui property will define the function that will be called on every iteration while the plugin is running.

Example, configuring custom UI for Input plugin:

"Input": {
     "config": {
        "lua_ui_includes": ["assets/lua/ui_input.lua"],
        "lua_on_render_ui": "onRenderCustomUI"
      }
    }
}

This will look for the ui_input.lua script on the set folder and run the onRenderCustomUI function:

---@param ptr inputmanaged
function Input.onRenderCustomUI(ptr)

    local plugin = inputmanaged.get(ptr)
    local shm = ui.getSharedMemory()
    local name = plugin:getName()

    local wkey = "show_" .. name .. "_window"
    if (shm[wkey]) then
        if (ui.Begin(name, wkey)) then          
            ui.showDefaultInputConfigMenu(plugin, {})
            if ui.CollapsingHeader("Extra Group") then
                if ui.SmallButton("OK") then
                    print("OK")
                end
            end
            ui.End()
        end
    end
end

This example function will show the default Input UI configuration as well as a new collapsing header named "Extra Group" that contains an "OK" Button

Customizing UI scripts for Instances

It's possible to customize a script that can run for a specific instance, for this to happen the script must be configured inside the instance json config file under the Global configuration

The lua_ui_includes property will define all the scripts that contain the specified functions to run.

The lua_on_render_ui property will define the function that will be called on every iteration while the instance is running.

Example, configuring custom UI for instance:

 "Global": {
  "config": {
   "lua_ui_includes": ["assets/lua/instance_ui.lua"],
   "lua_on_render_ui": "DemoUI"   
  }
 }

This will look for the instance_ui.lua script on the set folder and run the DemoUI function:

---@param instance_name string
function DemoUI(instance_name)    

    if (ui.Begin(instance_name .. ":UI", instance_name .. ":UI")) then        
        if ui.SmallButton("OK") then
            print("OK")
        end
    end
end

This example function will show a new window when the instance is selected, that contains an "OK" Button

Sharing variables between scripts

This scripts will run on the UI thread, this thread uses the SharedMemory internal application dictionary to share data, for that, when inside this functions the user will need to run the following functions to the SharedMemory:

Inside the UI thread

---  Get the shared memory object
--- @return table shm Table with shared memory object (Readonly, use SetSharedMemoryEntry to save)
function ui.getSharedMemory() end

---  Get the shared memory entry for a given property
--- @param entry string Entry property name to get
--- @return any entry Shared memory object value
function ui.getSharedMemoryEntry(entry) end

---  Set the shared memory entry for a given property
--- @param entry string Entry property name to set
--- @param obj any Value to set (any Lua object)
function ui.SetSharedMemoryEntry(entry,obj) end