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.This is not the path to the script file but the actual script to be executed. For example: "DoStuff();"
	requires	List of objects expected by the script.Forces the KUIML engine to expose the listed objects to the scripting engine.

	Name	Value type	Default	Description	Comment
	script	script	empty	The script to be executed.	This is not the path to the script file but the actual script to be executed. For example: "DoStuff();"
	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.

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.

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.All object types are supported: parameters, strings, groups, curves, surfaces, properties...
	applicative_type	Optional string to qualify the applicative use of the object.Use the applicative type to make sure that objects can be pasted only where they can be accepted. If no applicative type is defined, the content can be pasted into any compatible object. Experimental since 2.7: use the system::text applicative type to copy the content of a parameter or string as system text into the clipboard.
	copy_context	Optional string to define the serialization context used for the copy operation.

	Name	Value type	Default	Description	Comment
	object_id	object identifier	empty	Identifier of the object to be stored into the clipboard.	All object types are supported: parameters, strings, groups, curves, surfaces, properties...
	applicative_type	string	empty	Optional string to qualify the applicative use of the object.	Use the applicative type to make sure that objects can be pasted only where they can be accepted. If no applicative type is defined, the content can be pasted into any compatible object. Experimental since 2.7: use the system::text applicative type to copy the content of a parameter or string as system text into the clipboard.
	copy_context	string	empty	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.All object types are supported: parameters, strings, groups, curves, surfaces, properties...
	applicative_type	Optional string to qualify the applicative use of the object.Use the applicative type to make sure that objects can be pasted only where they can be accepted. If no applicative type is defined, any compatible content can be pasted into the object. Experimental since 2.7: use the system::text applicative type to paste text from the clipboard into a parameter or string.
	paste_context	Optional string to define the serialization context used for the paste operation.

	Name	Value type	Default	Description	Comment
	object_id	object identifier	empty	Identifier of the object to be pasted from the clipboard.	All object types are supported: parameters, strings, groups, curves, surfaces, properties...
	applicative_type	string	empty	Optional string to qualify the applicative use of the object.	Use the applicative type to make sure that objects can be pasted only where they can be accepted. If no applicative type is defined, any compatible content can be pasted into the object. Experimental since 2.7: use the system::text applicative type to paste text from the clipboard into a parameter or string.
	paste_context	string	empty	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

LoadObject brief detailed show all inherited

	Name	Description
	object_id	Identifier of the object to be loaded.All object types are supported: parameters, strings, groups, curves, surfaces, properties...
	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.Use the applicative type to make sure that objects can be loaded only where they can be accepted. If no applicative type is defined, any compatible content can be loaded into the object.
	load_context	Optional string to define the serialization context used for the load operation.

	Name	Value type	Default	Description	Comment
	object_id	object identifier	empty	Identifier of the object to be loaded.	All object types are supported: parameters, strings, groups, curves, surfaces, properties...
	file_path_string_id	string id	empty	The identifier of the string object where the path to the file is stored.
	root_path	string	empty	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		empty	undocumented
	applicative_type	string	empty	Optional string to qualify the applicative use of the object.	Use the applicative type to make sure that objects can be loaded only where they can be accepted. If no applicative type is defined, any compatible content can be loaded into the object.
	load_context	string	empty	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.All object types are supported: parameters, strings, groups, curves, surfaces, properties...
	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.Use the applicative type to make sure that objects can be loaded only where they can be accepted. If no applicative type is defined, the file can be loaded into any compatible object.
	save_context	Optional string to define the serialization context used for the save operation.

	Name	Value type	Default	Description	Comment
	object_id	object identifier	empty	Identifier of the object to be saved.	All object types are supported: parameters, strings, groups, curves, surfaces, properties...
	file_path_string_id	string id	empty	The identifier of the string object where the path to the file is stored.
	root_path	string	empty	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	string	empty	Optional string to qualify the applicative use of the object.	Use the applicative type to make sure that objects can be loaded only where they can be accepted. If no applicative type is defined, the file can be loaded into any compatible object.
	save_context	string	empty	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.

If you open the file where the object was saved to, you'll see something like this:

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.When this attribute is set, the 'url' attribute is ignored.

	Name	Value type	Default	Description	Comment
	url	file path or url	empty	The location of the file to open.
	url_string_id	string id	empty	Identifier of the string object containing the file to open.	When this attribute is set, the 'url' attribute is ignored.

Open the directory containing the selected file in the file explorer of the system (Explorer on Windows and the Finder Mac).

OpenUrl brief detailed show all inherited

	Name	Description
	url	The location of the resource to open.The result may depend on the system and the applications registered to open the file.
	url_string_id	Identifier of the string object containing the file url to open.When this attribute is set, the 'url' attribute is ignored.
	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.When this attribute is set, the 'application' attribute is ignored.
	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.

	Name	Value type	Default	Description	Comment
	url	file path or url	empty	The location of the resource to open.	The result may depend on the system and the applications registered to open the file.
	url_string_id	string id	empty	Identifier of the string object containing the file url to open.	When this attribute is set, the 'url' attribute is ignored.
	application	string	empty	Name of the application to use to open the file.
	application_string_id	string id	empty	Identifier of the string object containing the name of the application to use.	When this attribute is set, the 'application' attribute is ignored.
	root_path	string	empty	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.

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.Example: "*.txt;*.html"	*.*
	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

	Name	Value type	Default	Description	Comment
	title	string	empty	Title of the dialog box.
	file_path_string_id	string id	empty	The identifier of the string object where the chosen file path should be stored.
	file_name_string_id	string id	empty	String_id to get base file name without the extension and path
	file_types	string	*.*	wildcards list (semi-column separated) for file types accepted by the open dialog.	Example: "*.txt;*.html"
	open_bundles	boolean	false	on Mac, when set to true, the end user can browse inside bundles.
	default_path	string	empty	default path (directory or file) to open if no file is already selected in the string pointed by file_path_string_id.
	root_path	string	empty	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.
	root_path_index_param_id	integer	empty	Param_id to receive index of the root_path that was used.
	applicative_type	string	empty	Optional string to qualify the applicative use of the object.
	result_param_id	integer	empty	Param_id to keep the result of operation: 0 - not opened, 1 - opened

Opens a standard system "file open" dialog box.

Simple example

Complex example

DisplayFileSaveDialog

Opens a standard system "file save" dialog box. Same as DisplayFileOpenDialog, except that the selected file path is not required to exist.

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.

	Name	Value type	Default	Description	Comment
	file_path_string_id	string id	empty	The identifier of the string object where the chosen file path should be stored.
	root_path	string	empty	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.

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.Example: "*.txt;*.html"	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.If no timeout is specified, the messagebox will not disappear until clicked.	-1
	button0	Name of the first button.By default, message boxes have a single button named "Ok"	Ok
	button1	Name of the second button.(optional)	empty
	button2	Name of the third button.(optional)	empty
	button3	Name of the fourth button.(optional)	empty
	buttonX_action_id	Action to be executed when the user clicks on button XBy default, no action is executed, except closing the message box. X ranges from 0 to 3.	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 storedParameter range should be [-1;3] as the dialog may return -1 in case of timeout, or window close on windows.	empty

	Name	Value type	Default	Description	Comment
	title	string	empty	Title of the dialog box.
	message	string	empty	message to be displayed in the message box.	Example: "*.txt;*.html"
	style	info, warning, error, none	none	type of the system message box (info, warning, error, none)
	timeout	integer	-1	The timeout specifies the number of milliseconds before the message box disappears.	If no timeout is specified, the messagebox will not disappear until clicked.
	button0	string	Ok	Name of the first button.	By default, message boxes have a single button named "Ok"
	button1	string	empty	Name of the second button.	(optional)
	button2	string	empty	Name of the third button.	(optional)
	button3	string	empty	Name of the fourth button.	(optional)
	buttonX_action_id	action id	empty	Action to be executed when the user clicks on button X	By default, no action is executed, except closing the message box. X ranges from 0 to 3.
	close_button	button0, button1, button3, button4	empty	action of the window close button (Windows only)
	result_param_id	param id	empty	identifier of a parameter where the result (Clicked button number) should be stored	Parameter range should be [-1;3] as the dialog may return -1 in case of timeout, or window close on windows.

Opens a standard system message box.

Examples of message box

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.

	Name	Value type	Default	Description	Comment
	script_file_name_string_id	string id	empty	The identifier of the string object where the filename of the selected script is stored.

Displays script selection menu.

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.

	Name	Value type	Default	Description	Comment
	plugin_id_string_id	string id	empty	String holding unique 4-chars plugin id (eg. 'ab41'), used for AU and VST2.
	plugin_guid_string_id	string id	empty	String holding unique 32-chars plugin guid, used for VST3.
	plugin_name_string_id	string id	empty	String holding the name of the plugin.
	plugin_manufacturer_string_id	string id	empty	String holding the name of the manufacturer
	plugin_manufacturer_id_string_id	string id	empty	String holding the unique 4-chars manufacturer id (eg. 'sup1'), used for AU.
	dsp_file_string_id	string id	empty	String holding the script file path (AngelScript or C++).
	dest_folder_string_id	string id	empty	String holding the folder name where to export the plugin(s).
	use_generic_params_param_id	param id	empty	Param holding '1' to export with generic param names and ranges.
	use_generic_skin_param_id	param id	empty	Param holding '1' if you don't want to export the skin.
	plugin_type_param_id	param id	empty	Param holding the type of a plugin (0 - AudioEffect, 1 - Instrument, 2 - MidiEffect)
	enable_meters_param_id	param id	empty	Param holding '1' to enable meters in the exported plugin (0 to lower CPU).
	enable_encryption_param_id	param id	empty	Param holding '1' if you want to encrypt AngelScript upon export.
	result_param_id	param id	empty	Param receiving the result of the export operation.
	io_config_path_string_id	string id	empty	String holding the selected I/O config for the plugin.
	io_config_root_path	string	empty	Path to the folder with I/O configs.
	log_path_string_id	string id	empty	String holding the export log.
	temp_path_string_id	string id	empty	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.

GeneratePlugNScriptGUID brief detailed show all inherited

	Name	Description
	string_id	The identifier of the string object where the generated string would be stored.

	Name	Value type	Default	Description	Comment
	string_id	string id	empty	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.