Events are a feature in the scripting system that allow you to execute sections of script when specific triggers occur, simply by listing said trigger inside the script itself. This allows you to create more dynamic scripts that react to more than just a single Translation, or even omit the need for setting up a translation entirely. A script can list as many events as you want, including the same event multiple times.
Usage
Events can be listed anywhere inside a script file with no indentation. All the lines of script that follow an event will be considered as part of that event response, until a new event or script header is reached in the script. All script commands to be included in an event’s script block should be nested within the event through indentation.
The syntax for including an event is as follows:
event [<event name>]
Examples:
event midi print A MIDI event just occured!
$text = This is the default entry point for scripts. This will run when the run button is clicked. print $text event midi $text = This is a MIDI event entry point in this script. This will only run when the midi event is triggered. print $text
Event parameters
Events can also list parameters to filter more specific conditions to be met before the script can be ran. These parameters are listed behind the event name just like command parameters and are always optional. The valid parameters that can be listed behind an event will depend on the event being used.
For example, the MIDI event offers the following syntax:
midi (<eventType>) (<note number/control number/program/pitchbend value>) (<velocity/control value>)
Example:
event midi note 56 127 print Note 56 was hit really hard! event midi note 56 0 print Note 56 has been lifted!
Event variables
Much like with scripts triggered by translations, events will also provide additional context about the event in the form of a script variable named $trigger. This variable is an object map in which various attributes of the event are listed by their names. The different attributes that will be included will depend on the type of event and can also vary with further conditions of the event.
As an example, the MIDI event will include a ‘controlvalue’ attribute in the trigger map if the MIDI event was a control change.
event midi controlchange 20 setvolume global ($trigger controlvalue)
Event returns
Some events also take a return value into consideration. This means that the ‘return’ command can be used to provide data to the event’s internal handler to act upon. What returns are valid and what the event handler will do with it will depend on the event.
For the MIDI event, a return of true is accepted to mark the MIDI event as silenced, preventing it from triggering any translations, being recorded by the recorder, triggering any other MIDI events, and being sent to the CoyoteMIDI outputs.
Example:
event midi controlchange 1
if (keystate LCTRL)
midi controlchange 7 ($trigger controlvalue)
return true