PLUG'N SCRIPT
rapid plugin development
Tutorial
DSP
KUIML
How-to
Scripts
  • Tutorial
  • Element Reference
Language basics
  • SKIN
  • DUMMY
  • INCLUDE
  • INCLUDE_ONCE
  • DEFINE
  • UNDEFINE
  • VARIABLE
  • LOCAL_VARIABLE
  • TEMPLATE
  • TEMPLATE_INNER_CONTENT
  • REPEAT
Data model
  • PARAM
  • ACTION
    • Action types
  • ACTION_TRIGGER
UI Layout and positioning
  • CELL
  • TABLE
UI Widgets
  • TEXT
  • TEXT_FIELD
  • TEXT_EDIT_BOX
  • CANVAS
    • Graphics API
  • svg
Common attrubutes
  • For all elements
  • Widgets
  • Param Widgets
  • Param Controls
  • Param Info Viewers
  • Text Widgets
  • Surface Viewers
  • Curve Viewers
  • 3D Objects
  • Parameters mapping
KUIMLElement ReferenceACTION_TRIGGER
December 05, 2022

ACTION_TRIGGER

This element connects an event to an action: whenever the event is triggered, the action is executed. 

Attributes brief detailed show all inherited

Name DescriptionDefault
event_idIdentifier of the event that triggers the actionFor example: "param1.value_changed" or "timer1.elapsed". You can combine multiple events using ";"empty
action_idIdentifier of the target action to be executed when the event is firedempty
scriptScript to be executed when the event is fired. Replaces action_id if presentempty
requiresList of objects expected by the script.Forces the KUIML engine to expose the listed objects to the scripting engine.empty
condition_formulaMathematical formula used as a condition to execute the action (can reference any object defined in the model). The action is executed only if the formula does not return 0Be careful with condition formulas when using synchronous execution as the data referenced in the formula may have not been updated yetempty
asyncWhen true, both the action and conditions are triggered asynchronously. When false, the condition is evaluated and the action is executed synchronously, as soon as the event is triggeredUsing synchronous trigger may cause the action to be executed while parts of the data model depending on the source event has not been entirely updated. On the other hand, asynchronous trigger will happen later, so the condition may have changed (if relying for example on the state of another action)'false'
Common attributesRead about `common`
idIdentifier of the elementThe id of an element has to be globally unique. Two elements cannot have the same identifierempty
Name Value type Default Description Comment
event_idevent idemptyIdentifier of the event that triggers the actionFor example: "param1.value_changed" or "timer1.elapsed". You can combine multiple events using ";"
action_idaction idemptyIdentifier of the target action to be executed when the event is fired
scriptscriptemptyScript to be executed when the event is fired. Replaces action_id if present
requireslist of ';' separated identifiers or wildcardsemptyList of objects expected by the script.Forces the KUIML engine to expose the listed objects to the scripting engine.
condition_formulaMath FormulaemptyMathematical formula used as a condition to execute the action (can reference any object defined in the model). The action is executed only if the formula does not return 0Be careful with condition formulas when using synchronous execution as the data referenced in the formula may have not been updated yet
asyncboolean'false'When true, both the action and conditions are triggered asynchronously. When false, the condition is evaluated and the action is executed synchronously, as soon as the event is triggeredUsing synchronous trigger may cause the action to be executed while parts of the data model depending on the source event has not been entirely updated. On the other hand, asynchronous trigger will happen later, so the condition may have changed (if relying for example on the state of another action)
Common attributesRead about `common`
ididentifieremptyIdentifier of the elementThe id of an element has to be globally unique. Two elements cannot have the same identifier

Examples

Upon any event you can either trigger an action or run a script, like this:

  1. <!-- runs an action when parameter changes -->
  2. <ACTION_TRIGGER event_id="demo_param.value_changed" action_id="..." />

  3. <!-- runs a script when timer is elapsed -->
  4. <ACTION_TRIGGER event_id="demo_timer.elapsed" script="..." requires="..." />

* Note: don't forget to add parameters used in script to "requires" attribute. It "exposes" these attributes from the KUIML engine to the scripting engine so you can use them. It's enough to mention used objects once in any "requires" field somewhere in the current skin or a special EXPOSED_OBJECTS element.

Trigger with condition

You can make a more complex trigger adding "condition_formula", so the action will be triggered only if this formula returns non 0 value.

  1. <!-- demo parameter to change -->
  2. <PARAM id="demo_param" min="0" max="10" default="0" persistent="true" />
  3. <!-- a control to display and change the parameter -->
  4. <PARAM_TEXT_CONTROL param_id="demo_param" content="value: {value}" positions_count="11" />

  5. <!-- trigger a script when parameter changes or GUI is (re-)loaded -->
  6. <ACTION_TRIGGER event_id="demo_param.value_changed;window.loaded.value_changed"
  7. condition_formula="window.loaded == 1"
  8. script=" 
  9. /* get the parameter value into a script variable */
  10. double d = demo_param;
  11. /* set the default widget opacity */
  12. w_red.opacity = 0.1;
  13. w_blue.opacity = 0.1;
  14. /* display proper widget when parameter is odd or even */
  15. if ((d % 2) == 0) {
  16. w_red.opacity = 1;
  17. } else {
  18. w_blue.opacity = 1;
  19. }
  20.  " requires="demo_param;w_red.opacity;w_blue.opacity" />

  21. <!-- a couple widgets to display -->
  22. <ROW spacing="5">
  23. <WIDGET id="w_red" background_color="#fe8a71" width="40" height="40" />
  24. <WIDGET id="w_blue" background_color="#0e9aa7" width="40" height="40" />
  25. </ROW>

Note that we've also used an "window.loaded.value_changed" event to trigger the script also when the GUI is loaded, so that we get proper widgets visible from start.

By the way, try PARAM_LINK

Often it's possible to avoid scripts and to use PARAM_LINK element to trigger changes of some param when another parameter changes. For example, we can rewrite the same example like this.

  1. <!-- demo parameter to change -->
  2. <PARAM id="demo_param" min="0" max="10" default="0" persistent="true" />
  3. <!-- a control to display and change the parameter -->
  4. <PARAM_TEXT_CONTROL param_id="demo_param" content="value: {value}" positions_count="11" />

  5. <!-- make demo_param affect other parameters -->
  6. <PARAM_LINK from="demo_param" to="w_red.opacity" formula="0.1 + ((x%2)=0)" />
  7. <PARAM_LINK from="demo_param" to="w_blue.opacity" formula="0.1 + ((x%2)!=0)" />

  8. <!-- a couple widgets to display -->
  9. <ROW spacing="5">
  10. <WIDGET id="w_red" background_color="#fe8a71" width="40" height="40" />
  11. <WIDGET id="w_blue" background_color="#0e9aa7" width="40" height="40" />
  12. </ROW>

Editor's note on async

Be careful with "async" in ACTION_TRIGGER or TIMER set to true, as it may lead to crashes. Setting this to true can sometimes can help you run an action later when other parameters and objects are fully updated, but at the same time it may crash, probably due to the fact that the objects you're trying to access asyncronously were already destroyed. 

Regular or delayed events

See TIMER for examples on triggering events regularly or after a while.

Where to find event names?

Most of the objects (parameters, strings, curves, etc) expose some_object.value_changed events and TIMERs expose some_timer.elapsed. Objects may also have events on some of its attributes changes. Here's a list of some examples:

  1. <!-- runs when a GUI is loaded (each time a plugin window is opened) -->
  2. <ACTION_TRIGGER event_id="window.loaded.value_changed" condition_formula="window.loaded==1"
  3. script="..." requires="..." />

  4. <!-- trigger action on right-click (mouse down event) -->
  5. <ACTION_TRIGGER event_id="w_mouse_track.mouse_down.value_changed" condition_formula="w_mouse_track.mouse_down==2" script=" ... " />

  6. <!-- widget should be set as 'mouse_sensitive' -->
  7. <WIDGET id="w_mouse_track" background_color="#000000" width="20" height="20" mouse_sensitive="true" />

Take a look at widget attributes and events to find events like mouse_over, key_pressed and more.

2020 © Plug'n Script and KUIML by Blue Cat Audio  |  Site by LetiMix