/ Reference / Webview GUI API

We implement an experimental, simple, lightweight, portable interface for providing CLAP plugin GUIs based atop standard web browser technologies (html, css, JavaScript).

A Plugin GUI is a "website" loaded into an iframe within a Hz tab. We load the website from the webview directory within the plugin directory.

IPC is performed by standard window.postMessage / window.onmessage interfaces.

Plugin GUI can display current state and make modifications thereto via clap setParam.

The MusicAPI interface to display the webview GUI is controlled by anode.Show()/Hide(). Currently script-based set/modParam changes may not be reflected in the GUI.

Implementation

Delivering information from host to plugin gui

First plugin creates a per-iid (node instance) gui:

window.addEventListener("message", (evt) =>
{
    if(evt.data.iid != null)
    {
        let myInstance = this.myInstances[evt.data.iid];
        if(!this.myInstances[evt.data.iid])
        {
            // evt.data.iid is a unique id for each plugin.
            // evt.data.sid is a sibling id (small integer counter)
            let myInstance = XXX;// create your gui here.
            this.myInstances[evt.data.iid] = myInstance;
        }
        // dispatch events to instance
        myInstance.handleEvent(evt.data.iid); 
    }
});

Now handle events associated with your instance.

handleEvent(evt)
{
    switch(evt.data.msg)
    {
    case "show":
        this.panel.style.display = "block";
        break;
    case "hide":
        this.panel.style.display = "none";
        break;
    case "pluginSetState":
        this.updateState(evt.data.state);
        break;
    }
}

Controlling the plugin instance from your plugin gui.

pluginGetState

Asynchronously requests the current plugin state and is usually invoked when a new instance is created (as above). Currently requires that state be ascii transportable.

pluginGetState(iid, sid)
{
    let anyOrigin = "*";
    // console.log("-------------------requestState for " + iid);
    parent.postMessage(
      {
            msg: "pluginGetState", iid, sid,
      }, anyOrigin);
}

log

Request logging into the host logging interface.

log(msg)
{
    let anyOrigin = "*";
    parent.postMessage(
        {
            msg: "log", 
            val: msg
        }, anyOrigin);
}

pluginSetParam

Update the value of the parameter with the provided numeric id.

setParam(iid, pid, value)
{
    let anyOrigin = "*";
    parent.postMessage(
      {
        msg: "pluginSetParam", 
        iid, pid, val: value
      }, anyOrigin);
}