Tutorial
DSP
KUIML
How-to
Scripts
KUIMLTutorialParams 101
March 31, 2021

Params 101

PARAM is probably the most important element in KUIML, as KUIML is a data-driven language. Almost everything is related to PARAMs, and PARAMs are everywhere.

Params created explicitly

You can create PARAM explicitly in the GUI, like this:

  1. <PARAM id="drive" min="0" max="100" default="50" />

After that you can display/control param value using many different WIDGETs, for example this way:

  1. <PARAM_TEXT_CONTROL param_id="drive" />

Auto-created params

When you add any element like CELL, or WIDGET, or TEXT (or something else), it also allows you later access some exposed attributes as PARAMs (or sometimes as STRINGs), for example:

  1. <CELL id="c1" display="true">
  2. <TEXT id="tx1" value="Text sample" opacity="0.5" />
  3. </CELL>

Now we can access parameters like c1.display and tx1.opacity and control or view them. Even if you don't explicitly add those attributes, every CELL by default has a ".display", ".width", ".h_offset" and other exposed parameters, and so does TEXT and other widgets.

Take a look at this example:

  1. <ROW>
  2. <CELL id="c1">
  3. <TEXT value="Hide me or " font_weight="bold" />
  4. </CELL>
  5. <CELL>
  6. <TEXT id="tx1" value="change my .opacity" text_color="#DD0000" font_weight="bold" />
  7. </CELL>
  8. </ROW>

  10. <ROW spacing="10" v_margin="5">
  11. <!-- now you can change c1.display -->
  12. <PARAM_TEXT param_id="c1.display" content="Display: {text_value}">
  13. <INVISIBLE_PARAM_BUTTON param_id="c1.display" positions_count="2" width="100%" height="100%" cursor="system::hand" />
  14. </PARAM_TEXT>
  15. <!-- and text opacity -->
  16. <PARAM_TEXT_CONTROL param_id="tx1.opacity" content="Opacity: {value}" cursor="system::size_v" />
  17. </ROW>

This is how we can change element parameters on the fly.

Some attributes like text_color or font_weight are unfortunately not exposed (at least in the current KUIML version) and thus they cannot be changed on the fly. One of the solutions to this is to create two elements with different attributes on top of each other, and display only one you need at the moment.

Parameter linking

The cool thing is that you can link params to each other using PARAM_LINK.

Let's add this line to the example above:

  1. <PARAM_LINK from="tx1.opacity" to="c1.display" />

This way when tx1.opacity is 0, the c1 cell will also be hidden (because c1.display will also be 0).

We could easily make it reverse (when tx.opacity is 0 c1.display is 1):

  1. <PARAM_LINK from="tx1.opacity" to="c1.display" reverse="true" />

Or we could even use some formulas for linking, 

  1. <PARAM_LINK from="tx1.opacity" to="c1.display" formula="if ((x>0.4)*(x&lt;0.6), 1, 0)" />

This way c1.display will be set to 1 when tx1.opacity is between 0.4 and 0.6.

Multiple linking

PARAM_MULTI_LINK allows even more control so that you can link a single param to multiple other PARAMs, or get a PARAM value as a sum of other PARAMs, etc. Here's a simple example:

  1. <!-- make several widgets -->
  2. <ROW spacing="5">
  3. <WIDGET id="blue" background_color="#5799F0" width="20" height="20" />
  4. <WIDGET id="magenta" background_color="#BC69FB" width="20" height="20" />
  5. <WIDGET id="purple" background_color="#FB78D5" width="20" height="20" />
  6. <WIDGET id="red" background_color="#FB6E6E" width="20" height="20" />
  7. <WIDGET id="orange" background_color="#FBB469" width="20" height="20" />
  8. </ROW>

  10. <!-- create a param to control them -->
  11. <PARAM id="which_mode" min="0" max="2" type="integer" value_format=".0" />
  12. <PARAM_TEXT_CONTROL param_id="which_mode" margin="5" cursor="system::size_v" font_size="20" content="mode: {value}" value_format=".0" />

  14. <!-- link that param to multiple other params -->
  15. <PARAM_MULTI_LINK from="which_mode" to="blue.opacity;magenta.opacity" formula="(x>=1) + 0.2" />
  16. <PARAM_MULTI_LINK from="which_mode" to="purple.opacity;red.opacity;orange.opacity" formula="(x>=2) + 0.2" />

Here's the result:

There is also a PARAM_CONNECTION element that ensures that both PARAMs have the same value. The PARAM_TO_STRING_LINK element allows you to convert param value to text value. In short, param linking is a very powerful thing, and one of the coolest features of KUIML. It can replace a lot of scripting and make things more stable and simple.

There are more examples on using parameters on the PARAM page.

Element Reference

Comments