Permalink
Fetching contributors…
Cannot retrieve contributors at this time
91 lines (57 sloc) 3.8 KB

Advanced property syntax

Inheritance: @{}

Widgets can use each other's property values by using the following syntaxes:

  • @{this.propertyName}
  • @{parent.propertyName}
  • @{widgetId.propertyName} (where widgetId is the target widget's id)

!!! note Don't use widgetId when targetting this or parent, it won't work.

propertyName can be any of the target widget's properties.

It can be used to:

  • concatenate strings: /@{parent.id}/some_suffix
  • define object value: ["@{parent.id}"]

If the retreived property is an object ([] / {}), a subset can be defined by appending a dot and a key (array index or object key) : @{parent.variables.key}

!!! note "" The root panel's id is root.

Using the value

The special property name value refers to a widget's current value (which can be affected by its value property).

When omitted, the property name defaults to value : @{widgetId} => @{widgetId.value}

### Dynamic properties

Some properties, when changed, trigger a complete widget recreation that ends any ongoing user interaction. Also, updating these properties continuously (e.g. when linked to a slider's dynamic value) can be very cpu expensive.

Some properties have much cheaper update routines and can be considered as dynamic, as in performance safe. These properties are marked in the documentation with a .

Circular references cases

  • container widgets can inherit their children's properties only to define dynamic properties
  • widgets can inherit their own value property only to define dynamic properties

Nesting

The inheritance syntax supports 1-level nesting : @{fader_@{toggle_1}}

OSC listeners: OSC{}

The following syntax allows listening on an osc address to define a property, with an optionnal default value :

OSC{/address, 1}

Will return 1 at first and listen for osc messages on address /address. Each time a value is received, the property will be updated.


Formulas: #{}

The following syntax allow writing mathematical formulas in widgets' properties:

#{FORMULA}

Where FORMULA is a valid MathJS expression:

Additionnal functions:

  • indexOf(a, x): returns index of item x in array a
  • unpack(x): remove an array's brackets (unpack([1,2]) returns "1, 2")
  • pad(x, padding): add leading zeros if the length the integer part of x is smaller than padding (pad(1,2) returns "01")
  • length(x): returns the length of an array or string
  • keys(x): returns an array of a given object's property names (from MDN)
  • values(x): returns an array of a given object's own enumerable property values (from MDN)
  • extend(x, y): merges two objects into one

!!! tip "" A single widget property can contain multiple formulas. Variables and functions declared in a formula are available to subsequent formulas in the same property definition.