Making a Scriptable UI

Making a plug-in UI is quite a lot of work, often more than the DSP part.
Since Dplug v12.3.0, you can use Wren as an "imperative CSS" to have live-coding in the UI creation process.
This article explains how to add Wren scripting to your plug-in.

---

Pros and cons of Wren scripting in Dplug

Should you use Wren scripting in your Dplug product? The most probable answer is yes.

• Pros:

  • Live-code UI widgets graphical properties, and see the result immediately without rebuild.
  • Your UI code contains large amounts of setting graphical properties. Creating this code is slow, and limited by the "change-build-run-load" feedback loop.

• Cons:

  • About 200kb of additional binary code in final product.
  • About 1 to 10 mb of additional memory in final product.
  • Slower UI opening and resize, because of scripting overhead.

The benefits of seeing directly your change on screen is interesting, as it should positively influence the result. It's really meant as a tool to lessen the cost to try a graphical change.

---

What can you do exactly from Wren?

Here is what you can do as of Dplug v12.3 from Wren:

• Set positions of a UIElement at UI creation or reflow.

  static reflow() { 
      var S = UI.width / UI.defaultWidth
      ($"_inputSlider").position = Rectangle.new(190, 132, 30, 130).scaleByFactor(S)
  }

• Set/get values of fields in UIElement-derived classes that are marked with @ScriptProperty, at UI creation or reflow.

  static reflow() { 
      var S = UI.width / UI.defaultWidth
      ($"_inputSlider").litTrailDiffuse = RGBA.new(151, 119, 255, 100)
  }

• Plus everything you can normally do in Wren.

Example

See plugin.wren int he Distort example.

• The available exposed API is ui.wren. This is a Dplug-specific Wren API implemented in the dplug:wren-support sub-package.

• The other imported Wren module is widgets, whose code is auto-generated based on what widgets were exposed to Wren.

Limitations (as of Dplug v12.3)

• You can not create a UIElement (or any kind of D object) from script. You will still need to create widgets in D code, and call addChild manually.
• @ScriptExport classes must derive from UIElement.
• Calling a @ScriptProperty setter just changes the memory. It does not trigger a redraw by itself. You can't expose methods, just assign fields in some D objects. So: you can't add arbitrary Wren APIs for now, just use @ScriptExport/@ScriptProperty.
• Enums are lowered to integers in Wren, they don't have pretty names.
• You can't have two @ScriptExport classes that are named the same in different D modules.
• Each UIElement you want to modify by script should have a unique ID. Can't traverse UI tree for now.

How to enable Wren scripting in your UI

Limitations