Control » Widgets

Widgets

The widgets currently included with Control are:

Button
MultiButton
Slider
MultiSlider
MultiXY
Knob
Label
Gyro
Accelerometer
Compass

The first six are all graphical widgets, the last three are hardware features of devices that may or may not be present depending on the device you are using. All widgets, whether they are graphical or not, have a number of attributes in common to specify via JSON.

name – this is the name for the JavaScript variable that will hold the widget. It must start with a letter and not contain any spaces.
type – the type of widget (button, slider, etc.)
isLocal – if true, the widget will not send out default OSC / MIDI messages. You can still send custom messages via event handlers. Useful for widgets that only manipulate other widgets in Control. Default value is false.
min – the minimum value the widget should transmit when using OSC. The default is 0.
max – the maximum value the widget should transmit when using OSC. The default is 1.
midiMin – the minimum value the widget should transmit when using MIDI. The default is 0.
midiMax – the maximum value the widget should transmit when using MIDI. The default is 1.
address: an optional attribute for OSC interfaces, this specifies what address the values the widget outputs should go to e.g. “/buttonMsg”. The default is / + whatever the name attribute of your widget is.
midiType: This specifies whether the widget outputs a noteon, noteoff, control change or program change message. The default value is “cc”.
channel: This specifies what channel the widget values are transmitted on. The default value is 1.
midiNumber: This specifies what number (note number, cc number) the widget transmits. The default is 0.
onvaluechange: Code to be executed whenever the value of the widget is changed but before the value is sent to any destinations. This lets you change the value that is outputted so that it can be rounded up, scaled in different ways, reference a lookup table etc. You can also use it to set the value of other widgets e.g. to change the value of a label whenever a new accelerometer value is received.
oninit: Code that is executed when the widget is first loaded. Unlike other event handlers in Control, you can’t use the this keyword in oninit due to the scope of where the event handler is called. Use window.nameOfTheWidget to refer to the widget.

If both the address and the midiType / channel / midiNumber are specified in JSON the widget will be able to output appropriate data regardless of whether an OSC or a MIDI destination has been chosen from the Destinations tab. It makes sense to specify both so that you (and other users who might download your interfaces) can take advantage of both protocols.

Graphical Widgets

All graphical widgets have a number of additional attributes in common:

x : the horizontal position of the upper left corner of the widget. This is a value from 0 to 1, with 0 being the far left and 1 being the far right of the screen.
y: the vertical position of the upper left corner of the widget. This is a value from 0 to 1, with 0 being the top and 1 being the bottom of the screen.
width: the width of the widget. This is a value from 0 (well, .05 would be more practical) to 1, with 0 being 0 pixels in width and 1 being the width of the screen in pixels. Note that this changes depending on the orientation of the interface.
height: the height of the widget. This is a value from 0 (well, .05 would be more practical) to 1, with 0 being 0 pixels in height and 1 being the height of the screen in pixels. Note that this changes depending on the orientation of the interface.
color: The fill color of the widget. This is given in CSS color notation. To specify a widget that is red, we could use either “#ff0000” or “#fff” or “rgb(255,0,0)”.
stroke: The stroke color of the widget. It uses the same rules as the fill color.
startingValue: ONLY VALID WHEN USING A OSC DESTINATIONS.The initial value that widget will used when drawn. The default is whatever the max of the widget is.
midiStartingValue: ONLY VALID WHEN USING A MIDI DESTINATIONS.The initial value that widget will used when drawn. The default is whatever the max of the widget is.
requiresTouchDown: This controls whether or not the widget will respond to touches that don’t start directly over the widget. The default is true, which means the widget will ignore all touches that don’t start on it.
ontouchstart: Code to be executed when a touch first hits the screen and hits a widget.
ontouchmove: Code to be executed when a touch moves inside of a widget
ontouchend: Code to be executed after a touch that started on the widget is released

Non-Graphical Widgets

Non-Graphical widgets (excluding the compass) have one additional attribute called updateRate. The updateRate determines the sampling rate of hardware. The default value depends on the individual widget. The compass is updated whenever changes in orientation occur.