Skip to content

Widgets properties

All widgets share a set of generic properties described below.

Basics

type

  • type: string
  • default: fader

id

  • type: string
  • default: generated unique 'widget_n'
  • usage: widgets sharing the same id will act as clones and update each other's value(s) without sending extra osc messages.

linkId

  • type: string|array
  • default: empty
  • usage:
    • widgets sharing the same linkId update each other's value(s) AND send their respective osc messages.
    • when prefixed with >>, the linkId will make the widget act as a master (sending but not receiving)
    • when prefixed with <<, the linkId will make the widget act as a slave (receiving but not sending)

Style

label

  • type: string|false
  • default: auto, which displays id
  • usage:
    • set to false to hide completely
    • insert icons from FontAwesome using the prefix ^ followed by the icon's name : made with ^heart, etc

top / left

  • type: number|percentage
  • default: auto
  • usage:
    • when both top and left are set to auto, the widget is positioned according to the normal flow of the page (from left to right, by order of creation).
    • otherwise, the widget will be absolutely positioned

width / height

  • type: number|percentage
  • default: auto

color

  • type: string
  • default: auto, inherited accent color
  • usage: any valid css color code is valid, this will change the default accent color for the widget and all its children

css

  • type: string
  • default: empty
  • usage: applies CSS rules to widget. See css tips.

Value

default

  • type: *
  • default: empty
  • usage: if set, the widget will be initialized with this value when the session is loaded. Some widgets use this property under specific conditions (see fader's doubleTap for example).

value

  • type: *
  • default: empty
  • usage: set value to define a widget's value depending on other widget's values / properties using property inheritance and property maths. When updated by an osc-sending event (e.g. dragging a slider), the widget will send its own osc message as well.

default and value must match the widget's value type (ie a number for sliders, an array for pads, etc) and restrictions (equal to on or off for a push/toggle button)

OSC

precision

  • type: integer|string
  • default: 2
  • usage: the precision property defines the number of decimals to display and to send.
  • set to 0 to send integers only.
  • a specific data type can be specified by appending a valid osc type tag to the precision value, for example : 3d will make the widget send double precision numbers rounded to three decimals

target

  • type: array|string
  • default: []
  • usage:
    • this defines the targets of the widget's osc messages
    • each element of the array must be a string formatted as follows : "ip:port"
    • multiple targets can be specified : ["ip1:port1","ip2:port2"]
    • a single target can be set : ip:port
    • if midi is enabled, targets can be "midi:device_name"
    • special item "self" can be used to refer to the emitting client directly
    • if no target is set (empty array []), messages can still be sent if the server has defaults targets (-s / --send)
    • to disable the default global osc targets (set via the app's --send option), set one of the array's item as null (unquoted).

address

  • type: string
  • default: /widgets_id
  • usage: this is the address of the osc messages sent by the widget, it must start with a /

touchAddress

  • type: string
  • default: empty
  • usage: sliders and pads can send special osc messages to inform weither they are currently touched or not. The osc message will be of the following form :
        /touch/address [preArgs] 0/1
    

preArgs

  • type: array|*
  • default: []
  • usage:
    • each element of the array defines a constant value that will be prepended to the osc message
    • values can be defined as objects if the osc data type needs to be specified (ie different from the default implied by the precision option)
    • a single non-array value can be set
  • example:
    preArgs: [
        "1",        // this will always be sent as a string
        0.5,        // this will be sent as an integer if precision equals 0
        1,          // this will be sent as float if precision is different from 0
        {
            type:"f",
            value:0.5
        },
        {
            type:"i",
            value:1
        },
        {
            type:"T",
            value:true
        },
        {
            type:"F",
            value:false
        }
    ]
    

bypass

  • type: boolean
  • default: false
  • usage: set to true to prevent the widget from sending any osc message

Changing OSC properties dynamically using advanced property syntax is likely to break synchronisation between multiple clients.