Tutorial
DSP
KUIML
How-to
Scripts
KUIMLReferenceScripting
August 23, 2025

Scripting

Engine

KUIML uses AngelScript for its scripting engine, with the following add-ons:

Also, strings use double quotes only. Simple quotes are reserved for a single character, like in C or C++.

Related KUIML Elements

Separate script files can be loaded in KUIML using the SCRIPT element.

Separate build-time scripts/functions can be loaded via SKIN build_time_script_include attribute to provide additional functionality for VARIABLE built-time scripting.

Scripts can also be written directly (inline) as attributes of the SCRIPT, ACTION_TRIGGER or ACTION (Script type), GL_OBJECT_3D, CANVAS and VARIABLE elements. Some characters (like &, ", <) need to be escaped in Inline scripts. See our online script converter.

Data model (PARAMs, STRINGS, ACTIONS, etc) can be exposed to scripts using the EXPOSED_OBJECTS element, and also via requires and exposed attributes in particular elements.

How it works

Once the structure of the user interface and data model have been described using KUIML elements and connected together with links (see build-time/runtime), it is possible to write scripts that perform more complex actions on the data model on behalf of the end-user. Most of the elements and their attributes are available to the scripting engine (see the "E (exposed)" column in the attributes list in the elements reference).

  1. <!-- create a param and a string -->
  2. <PARAM id="demo_param" min="0" max="20" default="10" />
  3. <STRING id="demo_string" default="Hello, World!" />

  5. <!-- display string and param values -->
  6. <TEXT string_id="demo_string" width="100" />
  7. <PARAM_TEXT param_id="demo_param" />

  9. <!-- a widget to draw a line -->
  10. <WIDGET id="widget_line" width="100" height="3" background_color="#DD0000" />

  12. <!-- a simple button to run an action -->
  13. <SYSTEM_ACTION_BUTTON action_id="run_my_script" width="100" />

  15. <!-- demo action to change color of the line -->
  16. <ACTION id="change_color" type="Script" script=" 
  17. widget_line.background_color.r = rand(0,1);
  18. widget_line.background_color.g = rand(0,1);
  19. widget_line.background_color.b = rand(0,1);
  20.  " requires="widget_line.background_color.*" />

  22. <!-- demo action to run when button is clicked -->
  23. <ACTION id="run_my_script" type="Script" script=" 
  24. /* update STRING - looks like a simple string, actually is a Kt::String */
  25. demo_string = &quot;Param was: &quot; + demo_param;

  27. /* update PARAM - looks like a simple variable, actually is a Kt::Param */
  28. demo_param++;

  30. /* run an ACTION - looks like a simple function, actually is a Kt::Action */
  31. change_color();
  32.  " name="Run script" requires="demo_string;demo_param;change_color" />

You can see in the code, that accessing PARAM or STRING or ACTION from the script is easy and looks identical to accessing a regular variable (double, string) or a function calls. However, they are represented as a different types of objects. It can be important to understand if you want to pass them as an argument to a function, or run some specific operations, that are possible only with real strings or doubles (or with actual kuiml objects).

KUIML model elements like PARAM, STRING, ACTION, CURVE, SURFACE and events are made available to the scripting engine using the following classes (they are all reference types):

  • Kt::Param : behaves like a double, supporting most common operators (++,–,+=,-=,*=,/= etc.)
    There's also a parent Kt::ConstParam for read-only params.
  • Kt::String : behaves like a native string, implements basic operations, such as concatenation (+=)
    There's also a parent Kt::ConstString for read-only strings.
  • Kt::Curve : acts as a unary function double f(double x). double v=curve(10.0); Can be copied with =
    There's also a parent Kt::ConstCurve for read-only curves.
  • Kt::Surface : acts as a binary function double f(double x,double y); double v=surface(10.0, 20.0); Can be copied with =. There's also a parent Kt::ConstSurface for read-only surfaces.
  • Kt::Action : simple function f(); Can be called via f()
  • Kt::Event : supports += and -= operators to register callback functions.
  • Kt::Object is just a base class for all the objects (listed above) in the scripting engine. Inherited by Kt::Action, Kt::ConstCurve, Kt::ConstParam, Kt::ConstString, Kt::ConstSurface, and Kt::Event.

Here's an example on how it can be useful to understand. We make two identical functions, call them seemingly identically, the only difference is the type of argument they receive.

  1. <!-- create a param -->
  2. <PARAM id="demo_param" min="0" max="20" default="10" />

  4. <!-- display param value -->
  5. <PARAM_TEXT param_id="demo_param" />

  7. <!-- two demo functions -->
  8. <SCRIPT script=" 
  9. void updateParam(double param) {
  10. param++;
  11. }
  12. void trulyUpdateParam(Kt::Param@ param) {
  13. param++;
  14. }
  15.  " />

  17. <!-- demo action to run when button is clicked -->
  18. <ACTION id="run_my_script" type="Script" script=" 
  19. updateParam(demo_param); /* this doesn't really update param */
  20. trulyUpdateParam(demo_param); /* this works as expected */
  21.  " name="Run script" requires="demo_param" />

  23. <!-- a simple button to run an action -->
  24. <SYSTEM_ACTION_BUTTON action_id="run_my_script" width="100" />

Another example how to create an empty "placeholder" reference in the script (Kt::Param@), and then attach it to real parameters.

  1. <!-- create a param -->
  2. <PARAM id="demo_param1" min="0" max="20" default="10" />
  3. <PARAM id="demo_param2" min="0" max="20" default="10" />

  5. <!-- display param value -->
  6. <PARAM_TEXT param_id="demo_param1" />
  7. <PARAM_TEXT param_id="demo_param2" />

  9. <!-- demo action to run when button is clicked -->
  10. <ACTION id="run_my_script" type="Script" script=" 
  11. Kt::Param@ param;
  12. @param = demo_param1; /* reference first param */
  13. param++;
  14. @param = demo_param2; /* reference second param */
  15. param++;
  16.  " name="Run script" requires="demo_param1;demo_param2" />

  18. <!-- a simple button to run an action -->
  19. <SYSTEM_ACTION_BUTTON action_id="run_my_script" width="100" />

Access params as array

Though KUIML doesn't support arrays, we can use script arrays and use a nice trick to link script array to actual params.

  1. <!-- how much params in array we need -->
  2. <VARIABLE id="ARRAY_SIZE" value="10" />

  4. <!-- create a placeholder script array of references to params -->
  5. <SCRIPT script=" 
  6. array&lt;Kt::Param@> my_params($ARRAY_SIZE$);
  7.  " />

  9. <!-- repeat several times, updating $index$ variable -->
  10. <REPEAT count="$ARRAY_SIZE$">
  11. <!-- create a param -->
  12. <PARAM id="demo_param$index$" min="0" max="40" default="10" />
  13. <!-- link each param to an script array of Kt::Param@ -->
  14. <ACTION_TRIGGER event_id="window.loaded.value_changed" condition_formula="window.loaded==1" script="@my_params[$index$] = demo_param$index$;" requires="demo_param$index$" />
  15. </REPEAT>

  17. <!-- display param values -->
  18. <ROW spacing="1" height="60">
  19. <REPEAT count="$ARRAY_SIZE$" height="50">
  20. <COLUMN width="25" v_align="bottom">
  21. <!-- draw a vertical line -->
  22. <WIDGET id="w_column_$index$" width="20" height="30" background_color="#FF99CC" />
  23. <!-- display text value -->
  24. <PARAM_TEXT param_id="demo_param$index$" font_size="10" />
  25. </COLUMN>
  26. <!-- link param value to widget height and color -->
  27. <PARAM_LINK from="demo_param$index$" to="w_column_$index$.height" />
  28. <PARAM_LINK from="demo_param$index$" to="w_column_$index$.background_color.r" formula="x/40" />
  29. </REPEAT>
  30. </ROW>

  32. <!-- access params as items in an array -->
  33. <ACTION id="run_my_script" type="Script" script=" 
  34. for(uint i=0; i &lt; my_params.length; i++) {
  35. my_params[i] = rand(0,40);
  36. }
  37.  " name="Run script" />

  39. <!-- a simple button to run an action -->
  40. <SYSTEM_ACTION_BUTTON action_id="run_my_script" width="100" />

Search in a string

To do some string-related operations you usually need to convert Kt::String to a regular string.

  1. <!-- create a kuiml string -->
  2. <STRING id="my_string" default="Hello!" />

  4. <!-- trying to search in a string when it changes -->
  5. <ACTION_TRIGGER event_id="my_string.value_changed" script=" 
  6. /* first we convert Kt::String to a regular string */
  7. string s = my_string;
  8. /* now we can search in its contents */
  9. if (s.findFirst(&quot;World&quot;)>-1) {
  10. my_string = &quot;Welcome!&quot;;
  11. }
  12.  " name="Run script" requires="my_string" />

  14. <!-- display and edit a string -->
  15. <TEXT_FIELD string_id="my_string" width="100" />

Creating shorthands using auto

In this example we show how to create references to random KUIML object (using "auto" class), how to reference to a PARAM and a STRING, how to change a reference on the fly.

  1. <!-- widget for the demo -->
  2. <WIDGET id="my_widget" width="40" height="40" background_color="#000000" mouse_sensitive="true" />

  4. <!-- add global script variables -->
  5. <SCRIPT script=" 
  6. array&lt;double> phase = {0, 0.4, 0.8, 1};
  7.  " />

  9. <!-- a timer and an action -->
  10. <TIMER id="forever_timer" refresh_time_ms="20" />
  11. <ACTION_TRIGGER event_id="forever_timer.elapsed"
  12. script=" 

  14. /* create an alias/reference to background_color (unknown type object) */
  15. auto bg = my_widget.background_color;

  17. /* update widget's background_color */
  18. bg.r = cos(phase[0])/2 + 0.5;
  19. bg.g = cos(phase[1])/2 + 0.5;
  20. bg.b = cos(phase[2])/2 + 0.5;

  22. /* create a reference to widget itself */
  23. auto w = my_widget;
  24. w.width = w.height + w.height * (cos(phase[3])+1)*grow_param;

  26. /* create a reference to a PARAM (just because we can) */
  27. Kt::Param@ sp = speed_param;

  29. /* update phase for each color */
  30. phase[0] += 0.04*sp; /* acts as a double, though is Kt::Param@) */
  31. phase[1] += 0.08*sp;
  32. phase[2] += 0.02*speed_param; /* we can use PARAM directly */
  33. phase[3] += 0.1*speed_param;

  35. /* format hex value to a string */
  36. string hex = formatUInt(uint(bg.r*255), &quot;0H&quot;, 2);
  37. hex += formatUInt(uint(bg.g*255), &quot;0H&quot;, 2);
  38. hex += formatUInt(uint(bg.b*255), &quot;0H&quot;, 2);

  40. /* let's create a reference to a STRING */
  41. Kt::String@ str = output_string;

  43. /* add some randomness just for fun */
  44. if (rand(0,100)>95) {
  45. /* change reference to another STRING */
  46. @str = output_string2;
  47. }

  49. /* update STRING contents */
  50. str = &quot;color: #&quot; + hex;

  52.  " requires="my_widget.background_color.*;my_widget.height;my_widget.width;grow_param;speed_param;output_string;output_string2" />

  54. <!-- param and control -->
  55. <PARAM id="speed_param" min="0" max="4" default="1" />
  56. <PARAM id="grow_param" min="0" max="3" default="0.4" />
  57. <ROW spacing="10">
  58. <PARAM_TEXT_CONTROL param_id="speed_param" content="Speed: {value}" pixel_range="400" value_format="0.2" />
  59. <PARAM_TEXT_CONTROL param_id="grow_param" content="Grow: {value}" pixel_range="400" value_format="0.2" />
  60. </ROW>

  62. <!-- string and output -->
  63. <STRING id="output_string" default="" />
  64. <TEXT_FIELD string_id="output_string" width="300" font_size="12" />
  65. <STRING id="output_string2" default="" />
  66. <TEXT_FIELD string_id="output_string2" font_size="12" />

Binding functions to events

In scripts you can access Kt::Event objects and bind or unbind script functions to it (in KUIML you can do similar things with ACTION_TRIGGER). Here's a simple demo.

  1. <!-- create a param -->
  2. <PARAM id="demo_param" min="0" max="100000" default="10" />

  4. <!-- display param value -->
  5. <PARAM_TEXT param_id="demo_param" />

  7. <!-- draw a demo line -->
  8. <WIDGET id="demo_widget" background_color="#0000DD" width="20" height="5" />

  10. <!-- a timer and an action -->
  11. <TIMER id="forever_timer" refresh_time_ms="200" />
  12. <ACTION_TRIGGER event_id="forever_timer.elapsed"
  13. script=" demo_param+=rand(-20,20); " requires="demo_param" />

  15. <!-- several script functions -->
  16. <SCRIPT script=" 
  17. /* a function to change the width of the widget */
  18. void updateWidget(){
  19. demo_widget.width = demo_param;
  20. }

  22. /* bind a script function to an event */
  23. void bind(){
  24. demo_param.value_changed += updateWidget;
  25. }

  27. /* unbind a script function from an event */
  28. void unbind(){
  29. demo_param.value_changed -= updateWidget;
  30. }
  31.  " requires="demo_param.value_changed;demo_widget.width" />

  33. <!-- demo actions to run when button is clicked -->
  34. <ACTION id="do_bind" type="Script" script="bind();" name="Bind" />
  35. <ACTION id="do_unbind" type="Script" script="unbind();" name="Unbind" />

  37. <!-- a simple buttons to run actions -->
  38. <SYSTEM_ACTION_BUTTON action_id="do_bind" width="100" />
  39. <SYSTEM_ACTION_BUTTON action_id="do_unbind" width="100" />

Accessing param default values

Sometimes you may need to access PARAM "default" attribute from script. In AngelScript "default" is a reserved word, so use "defaultValue" instead.

  1. <!-- create a param -->
  2. <PARAM id="demo_param" min="0" max="20" default="10" />

  4. <!-- display param defaultvalue -->
  5. <PARAM_TEXT_CONTROL param_id="demo_param.default" />

  7. <!-- demo action to run when button is clicked -->
  8. <ACTION id="run_my_script" type="Script" script=" 
  9. /* this will not work, cause 'default' is a reserved word in AngelScript */
  10. /* demo_param.default = rand(0,20); */

  12. /* instead of .default use .defaultValue */
  13. demo_param.defaultValue = rand(0,20);

  15.  " name="Run script" requires="demo_param.default" />

  17. <!-- a simple button to run an action -->
  18. <SYSTEM_ACTION_BUTTON action_id="run_my_script" width="100" />

Objects Exposure

For performance reasons, the KUIML engine does not create script objects for all elements that could be exposed by the data model.

So it is necessary to explicitely describe the objects that will be used by scripts so that they are properly exposed. See the "requires" attribute of the SCRIPT and EXPOSED_OBJECTS element.

You can of course expose all objects using the '*' wildcard to start writing the scripts, but exposed elements should definitely be filtered before releasing, or customers may encounter performance issues, especially with complex user interfaces with multiple elements.

Comments

Please, authorize to view and post comments.