KUIML technical details

Brief overview

KUIML is an XML dialect with additional build-time capabilities. It is a strongly typed, model-driven language. The purpose of the language is to be able to quickly write applications which, once loaded, produce as little runtime errors as possible.

The data model (parameters, strings, curves, etc) can be accessed via scripts (AngelScript is used). Events can trigger several types of actions.

User Interface Elements connect to the data model (params, strings, etc) that can be either published by the DSP side or described directly in the GUI.

All elements (including widgets and layout elements) may also expose attributes that become part of the data model and can be connected/linked together.

About XML

In XML you can define your own tags and attributes. That's what has been done for KUIML. It respects the XML syntax and has its own tags and attributes definitions.

Here's a simple example of an XML/KUIML document:

<?xml version="1.0" encoding="utf-8" ?>
<SKIN background_color="#FFCC99">
<TEXT value="Hello, world!" />
</SKIN>

If you never heard about XML, you can learn more here: https://www.w3schools.com/xml/

Main Concepts

Build Time / Runtime

First when loading the KUIML file the "build phase" happens, where basic language elements and commands are processed (such as INCLUDE, REPEAT, VARIABLE, DEFINE, TEMPLATE, REQUIRED_OBJECTS etc). They form the resulting structure. These elements are not "working" anymore when the application is up and running. The exact build-time steps are:
- Preprocessing
  The file is parsed a first time to determine the data model to expose.
- Parsing
  The file is fully parsed and actual data model, user interface and exposed elements are created in memory. This is similar to the build phase of a compiler.
- Linking
  Once all objects are available in memory, the KUIML engine goes into the linking phase, connecting all objects together, checking types and missing objects.
- Script Exposure
  If no error occurred and the structure has been successfully created, the data model is exposed to the scripting engine, and scripts are verified and compiled.
When build-phase is done the application is up and running. During run-time model elements such as PARAM, STRING, FORMULA_PARAM, ACTION_TRIGGER etc and user interface elements are "working".

Basic Types

The runtime model of KUIML is simple and based on the following basic types. They actually exists in two forms: modifiable (mutable, read-write) and non-modifiable (immutable, read-only). These basic types of objects may be created for you by the application (DSP) or can be instantiated in the GUI using Model Elements (such as PARAM, STRING, etc).

They can also be exposed by some elements (see the "E" (exposed) column for the attributes that can be exposed).

Param - Parameter or literal. Basic type to represent numbers.
String - Basic type to represent text.
Curve - Type of object that can store a unary math function y=f(x).
Surface - Type of object that can store a binary math function y=f(x,y).
Group - Object that can reference other objects of any type to create a group to manage their properties together.
Action - An action represents a behavior, it is the "active" part of the data model.
Event - Events can be fired when something happens and can be used to trigger actions.
Custom Property (unavailable in Plug'n Script) Application defined, dynamically typed custom object.
Metadata (unavailable in Plug'n Script, apart from "param.meta.lock" ) Any object can also be assigned optional metadata, using the object types above. the metadata is optional, and unlike other attributes of an object, it may or may not be available.

Links

In order to assign values and connect things together, it is recommended to use Model Links (PARAM_LINK, STRING_LINK, etc). Links can be activated on demand (using the enabled attribute), and manage values assignation for you, without the need to write script for simple data model connections.