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
Examples
Upon any event you can either trigger an action or run a script, like this:
- <!-- runs an action when parameter changes -->
- <ACTION_TRIGGER event_id="demo_param.value_changed" action_id="..." />
- <!-- runs a script when timer is elapsed -->
- <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.
- <!-- demo parameter to change -->
- <PARAM id="demo_param" min="0" max="10" default="0" persistent="true" />
- <!-- a control to display and change the parameter -->
- <PARAM_TEXT_CONTROL param_id="demo_param" content="value: {value}" positions_count="11" />
- <!-- trigger a script when parameter changes or GUI is (re-)loaded -->
- <ACTION_TRIGGER event_id="demo_param.value_changed;window.loaded.value_changed"
- condition_formula="window.loaded == 1"
- script="
- /* get the parameter value into a script variable */
- double d = demo_param;
- /* set the default widget opacity */
- w_red.opacity = 0.1;
- w_blue.opacity = 0.1;
- /* display proper widget when parameter is odd or even */
- if ((d % 2) == 0) {
- w_red.opacity = 1;
- } else {
- w_blue.opacity = 1;
- }
- " requires="demo_param;w_red.opacity;w_blue.opacity" />
- <!-- a couple widgets to display -->
- <ROW spacing="5">
- <WIDGET id="w_red" background_color="#fe8a71" width="40" height="40" />
- <WIDGET id="w_blue" background_color="#0e9aa7" width="40" height="40" />
- </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.
- <!-- demo parameter to change -->
- <PARAM id="demo_param" min="0" max="10" default="0" persistent="true" />
- <!-- a control to display and change the parameter -->
- <PARAM_TEXT_CONTROL param_id="demo_param" content="value: {value}" positions_count="11" />
- <!-- make demo_param affect other parameters -->
- <PARAM_LINK from="demo_param" to="w_red.opacity" formula="0.1 + ((x%2)=0)" />
- <PARAM_LINK from="demo_param" to="w_blue.opacity" formula="0.1 + ((x%2)!=0)" />
- <!-- a couple widgets to display -->
- <ROW spacing="5">
- <WIDGET id="w_red" background_color="#fe8a71" width="40" height="40" />
- <WIDGET id="w_blue" background_color="#0e9aa7" width="40" height="40" />
- </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:
- <!-- runs when a GUI is loaded (each time a plugin window is opened) -->
- <ACTION_TRIGGER event_id="window.loaded.value_changed" condition_formula="window.loaded==1"
- script="..." requires="..." />
- <!-- trigger action on right-click (mouse down event) -->
- <ACTION_TRIGGER event_id="w_mouse_track.mouse_down.value_changed" condition_formula="w_mouse_track.mouse_down==2" script=" ... " />
- <!-- widget should be set as 'mouse_sensitive' -->
- <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.