Lua Action Callback Function

When a Lua callback function is invoked by the Lua action it will be invoked with a single parameter as in the following prototype:

script_function_name(mapargs)

The function argument mapargs , is a Lua table whose keys provide the context in which the action is being invoked along with any action specific argument and parameters. This context includes the application, screen and control the action was associated with, the currently focused control, any arguments provided to the action as well as all of the event data that cause the action to fire.

By default the context is populated with keys lazily which can improve callback performance, but can make certain meta-operations a challenge such as deep table duplication or serialization. By accessing one of the members of the context listed below you will trigger the table to be populated. For most situations, this is completely transparent. Alternatively you can use a command line option to Lua to always pre-populate the table for Lua callbacks:

-olua,lazy_context=0

The following keys are available inside the context’s table but may be nil if not applicable for the context.

context_app

The application context of the current action

context_screen

The screen context of the current action (the current screen)

context_layer

The layer context of the current action (the current layer)

context_group

The group context of the current action (the current group)

context_control

The control context of the current action (the current control)

context_row

If the context_control is a table then this is the row index of the current cell

context_col

If the context_control is a table then this is the column index of the current cell

active_context

The fully qualified name of the model object that invoked the action. If that object is the application, this will be the empty string.

context_event

The name of the event the triggered the action

context_event_data

A pointer to a Lua table containing any event data. The event data is different for each event and is defined in the event definition.

A Lua type called 'context' has been defined inside Storyboard's custom Lua module 'gre' to represent the mapargs object for the purpose of auto completion inside the editor. However since Lua is untyped by default, a Doxygen comment describing the mapargs parameter must be added to a function in order to get auto completion on it, as follows:

--- @param gre#context mapargs
function CBMyFunc( mapargs )
    -- I now have auto completion on mapargs
end
                 

Functions created by Storyboard will automatically be prepended with this comment.

Example of using context data:

--- @param gre#context mapargs
function CBGetContext( mapargs )
    print("Triggered by event : " .. mapargs.context_event)
    print("Event was targeting : " .. mapargs.active_context)
end
            
Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments

0 comments

Article is closed for comments.