A new event notification system allows different objects to emit and/or listen for events. The event pool tracks all registered objects and possible events from the command line. To enable debugging of the new event system, send the following command:

// activate / deactivate debugging (prints message on console for each fired event):
send EVENT_POOL*DEBUGGING SET 1

Other commands allow the event pool to fetch a list of registered objects which emit events:

Generic Viz Engine Commands

// get list of all objects which have registered some events (which may be fired at some time)
send EVENT_POOL*REGISTERED_OBJECTS GET
 
// get list of all registered events of a specific object
send EVENT_POOL*REGISTERED_EVENTS GET $objectname
// example:
send EVENT_POOL*REGISTERED_EVENTS GET #727*STAGE
 
// get list of all registered objects+events and number of registered callbacks:
send EVENT_POOL LIST

Built-In Events

For now, the following objects have built-in events:

  • Stage: (onStarted, onStopped, onDirectorStarted, onDirectorStopped)

  • Superchannels: (onArmed, onDisarmed, onTransitionStarted, onTransitionStopped) and its subchannels (onAssigned, onLoaded, onCleared)

  • Gfx channels: (onPreSetObject, onPostSetObject)

  • Editors: (onPreSetObject, onPostSetObject)

  • Scripts: (defined by the script itself)

Additionally, Super Channels and Scripts can be configured to listen on events.

Technical Notes

Generally, an event can have an arbitrary name (for example, onLoaded) and can be sent by any object. Scripts and objects can also listen for specific events and are notified whenever that event has been triggered.

Additional notes:

  • Potential events must be registered by sending objects before they are emitted (because listeners can only register to known events).

  • The name of an object can be chosen by the object itself on creation (for example, SUPERCHANNEL1 or script1) but it is always preceded by the object id of the scene. Example: #199*SUPERCHANNEL1. 

Note: Aliases like MAIN_SCENE are not allowed.

  • When registering for an event, wildcards are allowed. The object name, the event name, or both can be wildcarded:

    ' Register for all events called "onLoaded"
    eventpool.registerAsListener("*", "onLoaded")
     
    ' Register for all events from a specific sender:
    eventpool.registerAsListener("#" & sceneid & "*SUPERCHANNEL1/A", "*")
     
    ' Register as listener for all events
    eventpool.registerAsListener("*", "*")

  • A KeyValueMap (Stringmap for scripts) can be attached to an emitted event.

Sample Scripts

Scripts can be used to emit events and to listen for specific events. See the sample scripts below.

Emit Events

Sample Script to Emit Events

sub OnInit()
Dim events as Array[String]
events.push("OnTriggered")
Eventpool.registerEvents("script1", events)
 
' use commands EVENT_POOL*REGISTERED_OBJECTS GET and
' EVENT_POOL*REGISTERED_EVENTS GET sceneID*script1 to
' verify that events are registered when script is active
' and that they are automatically unregistered when script
' is stopped/modified
 
' use EVENT_POOL*DEBUGGING SET 1 to
' see which events have been fired
end sub
 
sub OnInitParameters()
RegisterPushButton("test-button", "press here", 1)
end sub
 
sub OnExecAction(buttonId as Integer)
if (buttonId = 1) then
Dim params As StringMap
 
' now emit our event
Eventpool.emitEvent("OnTriggered", params)
 
' this fails, because we have not registered the event:
'Eventpool.emitEvent("OnBlabla", params)
 
end if
end sub

Listen for Events

Sample Script to React on Events

sub OnInit()
dim sceneid as String
sceneid = cstr(scene.vizid)
' Register as listener for three events of Super Channel1 / subchannel A
eventpool.registerAsListener("#" & sceneid & "*SUPERCHANNEL1/A", "onLoaded")
eventpool.registerAsListener("#" & sceneid & "*SUPERCHANNEL1/A", "onAssigned")
eventpool.registerAsListener("#" & sceneid & "*SUPERCHANNEL1/A", "onCleared")
 
'' Wildcards are also possible
' Register for all events called "onLoaded"
' eventpool.registerAsListener("*", "onLoaded")
 
' Register for all events from a specific sender:
' eventpool.registerAsListener("#" & sceneid & "*SUPERCHANNEL1/A", "*")
 
' Register as listener for all events
' eventpool.registerAsListener("*", "*")
 
end sub
 
sub OnEvent(objectName As String, event as String, arguments as StringMap)
'println("GOT EVENT!")
'println(objectName)
'println(event)
'println(arguments)
 
if (event=="onCleared") then
material.color.red = 255
material.color.green = 0
elseif (event=="onAssigned") then
material.color.red = 100
material.color.green = 100
elseif (event == "onLoaded") then
material.color.red = 0
material.color.green = 255
end if
end sub