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	Description	Default
	event_id	Identifier of the event that triggers the actionFor example: "param1.value_changed" or "timer1.elapsed". You can combine multiple events using ";"	empty
	action_id	Identifier of the target action to be executed when the event is fired	empty
	script	Script to be executed when the event is fired. Replaces action_id if present	empty
	requires	List of objects expected by the script.Forces the KUIML engine to expose the listed objects to the scripting engine.	empty
	condition_formula	Mathematical 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	empty
	async	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)	'false'
Common attributes
	id	Identifier of the elementThe id of an element has to be globally unique. Two elements cannot have the same identifier	empty

	Name	Value type	Default	Description	Comment
	event_id	event id	empty	Identifier of the event that triggers the action	For example: "param1.value_changed" or "timer1.elapsed". You can combine multiple events using ";"
	action_id	action id	empty	Identifier of the target action to be executed when the event is fired
	script	script	empty	Script to be executed when the event is fired. Replaces action_id if present
	requires	list of ';' separated identifiers or wildcards	empty	List of objects expected by the script.	Forces the KUIML engine to expose the listed objects to the scripting engine.
	condition_formula	Math Formula	empty	Mathematical 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 0	Be careful with condition formulas when using synchronous execution as the data referenced in the formula may have not been updated yet
	async	boolean	'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 triggered	Using 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 attributes
	id	identifier	empty	Identifier of the element	The 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:

* 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.

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.

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:

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