Action types
The KUIML engine exposes the following built-in actions, to be used with the ACTION element.
General purpose
Script brief detailed show all inherited
Name | Description | |
---|---|---|
script | The script to be executed. | |
requires | List of objects expected by the script. |
When triggered, executes a script. Useful to make your GUI more dynamic: with the script you can change many KUIML attributes on the fly, display and hide widgets, track keyboard and mouse state, etc.
- <!-- action that runs a script -->
- <ACTION id="run_my_script" type="Script"
- name="Run a demo script"
- script="
- string s = "Script executed ";
- run_count++;
- out_string = s + run_count + " times"; "
- requires="out_string;run_count" />
- <!-- add a script variable that action can access -->
- <SCRIPT script="int run_count = 0;" />
- <!-- string to output results -->
- <STRING id="out_string" default="Not executed" />
- <TEXT_FIELD width="300" string_id="out_string" />
- <CELL height="7" /> <!-- adds some vertical space -->
- <!-- a simple 'button' -->
- <WIDGET id="demo_button" background_color="#000088" text_color="#FFFFFF" >
- <TEXT value="Click me" width="100" height="40">
- <INVISIBLE_ACTION_BUTTON id="demo_inv_act_button" action_id="run_my_script" width="100%" height="100%" />
- </TEXT>
- </WIDGET>
- <!-- trick to make the button move slighly when the mouse is down -->
- <PARAM_MULTI_LINK from="demo_inv_act_button.mouse_down" to="demo_button.v_offset;demo_button.h_offset" />
We can use a SCRIPT element to add functions or variables that will be "global", or more precisely available to all ACTIONs within the current scope (current skin or current KUIML_WIDGET subskin).
System
CopyObject brief detailed show all inherited
Name | Description | |
---|---|---|
object_id | Identifier of the object to be stored into the clipboard. | |
applicative_type | Optional string to qualify the applicative use of the object. | |
copy_context | Optional string to define the serialization context used for the copy operation. |
Copies the selected object into the system cliboard.
PasteObject brief detailed show all inherited
Name | Description | |
---|---|---|
object_id | Identifier of the object to be pasted from the clipboard. | |
applicative_type | Optional string to qualify the applicative use of the object. | |
paste_context | Optional string to define the serialization context used for the paste operation. |
Pastes the contents of the system clipboard into the selected object.
Copying text to clipboard
- <!-- actions to copy/paste to clipboard-->
- <ACTION type="CopyObject"
- id="demo_CopyObject"
- object_id="demo_string"
- applicative_type="system::text"
- name="Copy to clipboard"
- />
- <ACTION type="PasteObject"
- id="demo_PasteObject"
- object_id="demo_string"
- applicative_type="system::text"
- name="Paste from clipboard"
- />
- <!-- add a demo string-->
- <STRING id="demo_string" default="Some text"/>
- <ROW margin="20">
- <TEXT_EDIT_BOX string_id="demo_string" width="300" />
- </ROW>
- <!-- display built-in system buttons -->
- <ROW>
- <SYSTEM_ACTION_BUTTON action_id="demo_CopyObject" width="150" />
- <SYSTEM_ACTION_BUTTON action_id="demo_PasteObject" width="170" />
- </ROW>
LoadObject brief detailed show all inherited
Name | Description | |
---|---|---|
object_id | Identifier of the object to be loaded. | |
file_path_string_id | The identifier of the string object where the path to the file is stored. | |
root_path | List of root directories for all paths, separated by ';'. Relative paths will be "absolutized" using these root paths until the file is found. | |
root_path_index_param_id | undocumented | |
applicative_type | Optional string to qualify the applicative use of the object. | |
load_context | Optional string to define the serialization context used for the load operation. |
Loads the content of a file into the selected object.
SaveObject brief detailed show all inherited
Name | Description | |
---|---|---|
object_id | Identifier of the object to be saved. | |
file_path_string_id | The identifier of the string object where the path to the file is stored. | |
root_path | List of root directories for all paths, separated by ';'. Relative paths will be "absolutized" using these root paths until the file can be saved. | |
applicative_type | Optional string to qualify the applicative use of the object. | |
save_context | Optional string to define the serialization context used for the save operation. |
Saves the content of an object into a file.
Examples of saving and loading objects
With these four action types you can copy/paste or save/load values of parameters, strings and other objects (for example a "preset" within a section of a plugin). By combining string and parameters into a GROUP you can operate with all of them at once.
- <!-- actions to copy/paste, load/save objects -->
- <ACTION type="CopyObject"
- id="demo_CopyObject"
- object_id="demo_group"
- applicative_type=""
- copy_context=""
- name="Copy Object"
- />
- <ACTION type="PasteObject"
- id="demo_PasteObject"
- object_id="demo_group"
- applicative_type=""
- paste_context=""
- name="Paste Object"
- />
- <ACTION type="SaveObject"
- id="demo_SaveObject"
- object_id="demo_group"
- applicative_type=""
- file_path_string_id="demo_string_path"
- root_path=""
- root_path_index_param=""
- save_context=""
- name="Save Object"
- />
- <ACTION type="LoadObject"
- id="demo_LoadObject"
- object_id="demo_group"
- applicative_type=""
- file_path_string_id="demo_string_path"
- root_path=""
- load_context=""
- name="Load Object"
- />
- <!-- add some demo strings and parameters -->
- <STRING id="class" default="AmpSimulator"/>
- <STRING id="name" default="JCM-800" />
- <PARAM id="gain" min="0" max="12" default="10" />
- <!-- and put them into a group for easy save/load operation -->
- <!-- object_aliases attribute is optional -->
- <GROUP id="demo_group"
- object_ids="class;name;gain"
- object_aliases="the_class;the_name;the_gain"
- />
- <!-- now add some widgets to display data and buttons -->
- <WIDGET layout_type="row" spacing="10" background_color="#DDEEFF" margin="20" >
- <TEXT_EDIT_BOX string_id="class" width="110" />
- <TEXT_EDIT_BOX string_id="name" width="110" />
- <PARAM_TEXT_CONTROL param_id="gain"/>
- </WIDGET>
- <CELL height="20" /> <!-- add some vertical space -->
- <!-- display built-in system buttons -->
- <ROW>
- <SYSTEM_ACTION_BUTTON action_id="demo_CopyObject" width="150" />
- <SYSTEM_ACTION_BUTTON action_id="demo_PasteObject" width="150" />
- </ROW>
- <CELL height="10" /> <!-- add some vertical space -->
- <ROW>
- <SYSTEM_ACTION_BUTTON action_id="demo_SaveObject" width="150" />
- <SYSTEM_ACTION_BUTTON action_id="demo_LoadObject" width="150" />
- </ROW>
- <CELL height="10" /> <!-- add some vertical space -->
- <!-- string with filename to save object to -->
- <STRING id="demo_string_path" default="$_DIR_$test_SaveObject.txt" />
- <TEXT_FIELD string_id="demo_string_path" width="300" text_h_align="right" />
If you open the file where the object was saved to, you'll see something like this:
- <?xml version="1.0" encoding="UTF-8"?>
- <Export applicative_type="" data_type="{0779F8E6-34E0-4DA5-9307-ECC37BE0FA8A}">
- <content the_gain="10" the_name="JCM-900" the_class="AmpSim"/>
- </Export>
Note on "_context" attribute
It may have the same values as the persistence_context (see PARAM), or custom values, but that's not used yet. The idea is to make sure of what is saved. So if you have for example some data that has persistence_context="-Init" and in the copy_context you put "Init" then this data will not be saved. It just defines the saving/loading context. You could use your own keywords on both sides in fact.
OpenDirectory brief detailed show all inherited
Name | Description | |
---|---|---|
url | The location of the file to open. | |
url_string_id | Identifier of the string object containing the file to open. |
Open the directory containing the selected file in the file explorer of the system (Explorer on Windows and the Finder Mac).
- <!-- open directory -->
- <ACTION type="OpenDirectory"
- id="demo_OpenDirectory"
- url="$PLUGIN_DATA_PATH$"
- _url_string_id="can_use_string_id_instead_of_static_url"
- name="Open directory"
- />
- <!-- display a button -->
- <SYSTEM_ACTION_BUTTON action_id="demo_OpenDirectory" width="150" />
OpenUrl brief detailed show all inherited
Name | Description | |
---|---|---|
url | The location of the resource to open. | |
url_string_id | Identifier of the string object containing the file url to open. | |
application | Name of the application to use to open the file. | |
application_string_id | Identifier of the string object containing the name of the application to use. | |
root_path | List of root directories for all paths, separated by ';'. Relative paths will be "absolutized" using these root paths until the file is found. |
Open the selected url (may be a local file path or a web url) using the system shell.
- <!-- open URL in browser -->
- <ACTION type="OpenUrl" id="demo_OpenURL"
- url="https://www.letimix.com/"
- name="Open url"
- />
- <!-- open current file in Finder -->
- <ACTION type="OpenUrl" id="demo_OpenFileInFinder"
- url="$_FILE_$"
- _url_string_id="can_use_string_id_instead"
- application="Finder"
- _application_string_id="can_use_string_id_instead"
- name="Open file in Finder"
- />
- <!-- run a batch file on Windows -->
- <ACTION type="OpenUrl" id="demo_RunBatchFileOnWin"
- application="C:/Scripts/file.bat"
- url='"param 1" param2 "param 3"'
- name="Run batch file on Windows"
- />
- <!-- run bash script in Mac terminal -->
- <ACTION type="OpenUrl" id="demo_RunScriptInMacTerminal"
- url='/path/to/bash_script.sh" --env MY_VAR1="value123" -n -F --args "'
- application="Terminal"
- name="Run script in Mac Terminal"
- />
- <!-- display buttons -->
- <SYSTEM_ACTION_BUTTON action_id="demo_OpenURL" width="150" />
- <SYSTEM_ACTION_BUTTON action_id="demo_OpenFileInFinder" width="150" />
- <SYSTEM_ACTION_BUTTON action_id="demo_RunBatchFileOnWin" width="250" />
- <SYSTEM_ACTION_BUTTON action_id="demo_RunScriptInMacTerminal" width="250" />
As you can see this OpenURL action type is quite powerful. You can open documents and run various apps with it. On Windows you can execute a .bat file by simply passing it as an "application" name, and parameters in "url".
On Mac we have to use a trick to run a script in the Terminal. Here OpenURL seems to be executed like: open -a "application" "url". Using extra double quotes we can inject attributes to the command and add environmental variable to pass data to the bash script.
User interface
DisplayFileOpenDialog brief detailed show all inherited
Name | Description | Default | |
---|---|---|---|
title | Title of the dialog box. | empty | |
file_path_string_id | The identifier of the string object where the chosen file path should be stored. | empty | |
file_name_string_id | String_id to get base file name without the extension and path | empty | |
file_types | wildcards list (semi-column separated) for file types accepted by the open dialog. | *.* | |
open_bundles | on Mac, when set to true, the end user can browse inside bundles. | false | |
default_path | default path (directory or file) to open if no file is already selected in the string pointed by file_path_string_id. | empty | |
root_path | List of root directories for all paths, separated by ';'. Paths relative to one of these directories will be truncated and stored as relative sub-paths. | empty | |
root_path_index_param_id | Param_id to receive index of the root_path that was used. | empty | |
applicative_type | Optional string to qualify the applicative use of the object. | empty | |
result_param_id | Param_id to keep the result of operation: 0 - not opened, 1 - opened | empty |
Opens a standard system "file open" dialog box.
Simple example
- <!-- action to execute file open dialog -->
- <ACTION type="DisplayFileOpenDialog"
- id="demo_DisplayFileOpenDialog"
- title="Select *.txt file"
- file_path_string_id="path_to_selected_file"
- file_types="*.txt"
- open_bundles="false"
- default_path=""
- name="Open file (dialog)"
- />
- <!-- string to receive file path -->
- <STRING id="path_to_selected_file" />
- <!-- display a button -->
- <SYSTEM_ACTION_BUTTON action_id="demo_DisplayFileOpenDialog" width="150" />
- <!-- display result -->
- <TEXT_FIELD string_id="path_to_selected_file" width="200" />
Complex example
- <!-- action to execute file open dialog -->
- <ACTION type="DisplayFileOpenDialog"
- id="demo_DisplayFileOpenDialog"
- title="Select *.txt or *.pdf file"
- file_path_string_id="file_path"
- file_name_string_id="file_basename"
- file_types="*.txt;*.pdf"
- open_bundles="true"
- default_path=""
- root_path="/Volumes/A2/1;/Volumes/A2/2"
- root_path_index_param_id="selected_root_index"
- result_param_id="result"
- name="Open file (dialog)"
- />
- <!-- strings to receive file path and base name -->
- <STRING id="file_path" />
- <STRING id="file_basename" />
- <!-- params to receive selected root path index and result -->
- <PARAM id="selected_root_index" max="100" min="-1" default="-1" />
- <PARAM id="result" max="1" min="-1" default="-1" />
- <!-- display a button -->
- <SYSTEM_ACTION_BUTTON action_id="demo_DisplayFileOpenDialog" width="150" />
- <!-- display result strings and params -->
- <TEXT_FIELD string_id="file_path" width="200" />
- <TEXT_FIELD string_id="file_basename" width="200" />
- <PARAM_TEXT param_id="result" content="result: {value}"/>
- <PARAM_TEXT param_id="selected_root_index" content="root_index: {value}"/>
DisplayFileSaveDialog
Opens a standard system "file save" dialog box. Same as DisplayFileOpenDialog, except that the selected file path is not required to exist.
- <!-- action to execute file save dialog -->
- <ACTION type="DisplayFileSaveDialog"
- id="demo_DisplayFileSaveDialog"
- title="Choose file to save"
- file_path_string_id="file_path"
- file_name_string_id="file_basename"
- file_types="*.txt"
- open_bundles="true"
- default_path="$PLUGIN_DATA_PATH$/Skins"
- result_param_id="result"
- name="Save file (dialog)"
- />
- <!-- strings to receive file path and base name -->
- <STRING id="file_path" />
- <STRING id="file_basename" />
- <!-- param to receive result (1 - ok, 0 - not) -->
- <PARAM id="result" max="1" min="-1" default="-1" />
- <!-- display a button -->
- <SYSTEM_ACTION_BUTTON action_id="demo_DisplayFileSaveDialog" width="150" />
- <!-- display result strings and params -->
- <TEXT_FIELD string_id="file_path" width="200" />
- <TEXT_FIELD string_id="file_basename" width="200" />
- <PARAM_TEXT param_id="result" content="result: {value}"/>
DisplayFolderSelectDialog brief detailed show all inherited
Name | Description | |
---|---|---|
file_path_string_id | The identifier of the string object where the chosen file path should be stored. | |
root_path | List of root directories for all paths, separated by ';'. Paths relative to one of these directories will be truncated and stored as relative sub-paths. |
Opens a standard system dialog to select a folder.
- <!-- action to execute folder select dialog -->
- <ACTION type="DisplayFolderSelectDialog"
- id="demo_DisplayFolderSelectDialog"
- file_path_string_id="file_path"
- root_path="/Volumes/A2/"
- name="Select folder (dialog)"
- />
- <!-- strings to receive file path and base name -->
- <STRING id="file_path" />
- <!-- display a button -->
- <SYSTEM_ACTION_BUTTON action_id="demo_DisplayFolderSelectDialog" width="180" />
- <!-- display result strings and params -->
- <TEXT_FIELD string_id="file_path" width="200" />
DisplayMessageBox brief detailed show all inherited
Name | Description | Default | |
---|---|---|---|
title | Title of the dialog box. | empty | |
message | message to be displayed in the message box. | empty | |
style | type of the system message box (info, warning, error, none) | none | |
timeout | The timeout specifies the number of milliseconds before the message box disappears. | -1 | |
button0 | Name of the first button. | Ok | |
button1 | Name of the second button. | empty | |
button2 | Name of the third button. | empty | |
button3 | Name of the fourth button. | empty | |
buttonX_action_id | Action to be executed when the user clicks on button X | empty | |
close_button | action of the window close button (Windows only) | empty | |
result_param_id | identifier of a parameter where the result (Clicked button number) should be stored | empty |
Opens a standard system message box.
Examples of message box
- <!-- a simple message box -->
- <ACTION type="DisplayMessageBox"
- id="demo_DisplayMessageBox"
- title="Hello there"
- message="This goes away in 2 seconds"
- name="Simple message"
- timeout="2"
- />
- <!-- a message box with options -->
- <ACTION type="DisplayMessageBox"
- id="demo_DisplayMessageBoxExtended"
- title="Hello there"
- message="There was an error. What to do?"
- style="error"
- timeout="-1"
- button0="Nothing"
- button1="Fix it"
- button2="Display simple one"
- button3="Ignore"
- close_button="button3"
- result_param_id="msg_box_result"
- button2_action_id="demo_DisplayMessageBox"
- name="With buttons"
- />
- <!-- display built-in system buttons -->
- <ROW>
- <SYSTEM_ACTION_BUTTON action_id="demo_DisplayMessageBox" width="150" />
- <SYSTEM_ACTION_BUTTON action_id="demo_DisplayMessageBoxExtended" width="150" />
- </ROW>
- <!-- add a parameter to keep chosen button -->
- <PARAM id="msg_box_result" min="-1" max="100" default="-1" />
- <ROW margin="20">
- <PARAM_TEXT param_id="msg_box_result" content="result: {value}" />
- </ROW>
As you see, there are some options can customize for the message box. Yet there's no option for string_id (to change the text on the fly), but it may be added in the future.
Plug'n Script related
These action types can be used for creating your own skin for Plug'n Script.
DisplayPlugNScriptMenu brief detailed show all inherited
Name | Description | |
---|---|---|
script_file_name_string_id | The identifier of the string object where the filename of the selected script is stored. |
Displays script selection menu.
- <!-- open script selection menu -->
- <ACTION type="DisplayPlugNScriptMenu"
- id="demo_DisplayPlugNScriptMenu"
- script_file_name_string_id="filename"
- name="Script selection menu"
- />
- <!-- display a button -->
- <SYSTEM_ACTION_BUTTON action_id="demo_DisplayPlugNScriptMenu" width="180" />
- <!-- string to keep the filename -->
- <STRING id="filename" />
- <!-- display selected file -->
- <TEXT_FIELD string_id="filename" width="350" />
- <!-- where the full path is stored -->
- <TEXT string_id="$script_file_path$" width="350" text_h_align="right" />
- <TEXT value="$script_file_path$" width="350" />
ExportPlugNScriptPlugin brief detailed show all inherited
Name | Description | |
---|---|---|
plugin_id_string_id | String holding unique 4-chars plugin id (eg. 'ab41'), used for AU and VST2. | |
plugin_guid_string_id | String holding unique 32-chars plugin guid, used for VST3. | |
plugin_name_string_id | String holding the name of the plugin. | |
plugin_manufacturer_string_id | String holding the name of the manufacturer | |
plugin_manufacturer_id_string_id | String holding the unique 4-chars manufacturer id (eg. 'sup1'), used for AU. | |
dsp_file_string_id | String holding the script file path (AngelScript or C++). | |
dest_folder_string_id | String holding the folder name where to export the plugin(s). | |
use_generic_params_param_id | Param holding '1' to export with generic param names and ranges. | |
use_generic_skin_param_id | Param holding '1' if you don't want to export the skin. | |
plugin_type_param_id | Param holding the type of a plugin (0 - AudioEffect, 1 - Instrument, 2 - MidiEffect) | |
enable_meters_param_id | Param holding '1' to enable meters in the exported plugin (0 to lower CPU). | |
enable_encryption_param_id | Param holding '1' if you want to encrypt AngelScript upon export. | |
result_param_id | Param receiving the result of the export operation. | |
io_config_path_string_id | String holding the selected I/O config for the plugin. | |
io_config_root_path | Path to the folder with I/O configs. | |
log_path_string_id | String holding the export log. | |
temp_path_string_id | String holding the temporary folder. |
Executes export of the script as a separate plugin. To get the better understanding of the plugin export process you can examine BCA Skin or LM Skin.
- <ACTION type="ExportPlugNScriptPlugin"
- id="do_ExportPlugin"
- name="Build the plugin!"
- plugin_id_string_id="plugin_id"
- plugin_guid_string_id="plugin_guid"
- plugin_name_string_id="plugin_name"
- plugin_manufacturer_string_id="plugin_manufacturer"
- plugin_manufacturer_id_string_id="plugin_manufacturer_id"
- dsp_file_string_id="$script_file_path$"
- dest_folder_string_id="dest_path"
- use_generic_params_param_id="use_generic_params"
- use_generic_skin_param_id="use_default_gui"
- plugin_type_param_id="plugin_type"
- enable_meters_param_id="enable_meters"
- enable_encryption_param_id="encrypt_dsp_script"
- result_param_id="export_result"
- io_config_path_string_id="selected_io_config"
- io_config_root_path="$PLUGIN_DATA_PATH$/Resources/Settings/ioconfig"
- log_path_string_id="export_log_path"
- temp_path_string_id="export_temp_path"
- />
GeneratePlugNScriptGUID brief detailed show all inherited
Name | Description | |
---|---|---|
string_id | The identifier of the string object where the generated string would be stored. |
Generates unique GUID string. Used for generating a unique ID for plugin when exporting, you can use it for other purposes as well.
- <!-- action to generate unique ID -->
- <ACTION type="GeneratePlugNScriptGUID"
- id="demo_GeneratePlugNScriptGUID"
- string_id="new_id"
- name="Generate GUID"
- />
- <!-- string to keep the generated id -->
- <STRING id="new_id" />
- <!-- display result -->
- <PARAM_TEXT param_id="new_id.length" content="length: {value} chars" value_format="0.0" />
- <TEXT_FIELD string_id="new_id" width="350" />
- <!-- display a button -->
- <SYSTEM_ACTION_BUTTON action_id="demo_GeneratePlugNScriptGUID" width="180" />