ControlIntro to JSON and Control
Before getting started, the interfaces included with the app are available here. In particular, everyone should start their new projects using the template interface. This includes some basic infrastructure to get you going. Download the template and then copy and paste into it from the other examples or the Widget description pages.
Interfaces for Control are primarily written in JSON. JSON is a data description language that is a subset of JavaScript. In general, JSON is readable by people regardless of whether or not they’ve ever programmed before. As an example, below is a short JSON snippet that would place a button in the upper-left corner of the interface when read by Control.
{
"name":"buttontest",
"type":"Button",
"x":0,
"y":0,
"width":.5,
"height":.5,
"address":"/btn"
}
The name attribute should provide a unique name for each widget. The type attribute establishes what type of widget we’re defining… A slider, a button, a knob, a label etc.
X,y,width and height are all given as percentages of the screen. For example, the above has a width of .5 and a matching height; this means it fills half the screen. If the width was .25, it would fil, a quarter, if it was 1 it would fill the entire screen. The x and y coordinates are for the upper left corner of the widget; the widget is drawn down and to the right from that coordinate according to the width and height.
The address field gives the OSC address that Control will send information to from the widget. You can also define MIDI messages to be sent.
If you haven’t used JSON before please look through some online tutorials before reading the rest of these instructions.
Structure of Interface Files
The interface files mainly consist of a JavaScript array named “pages”; this array can hold multiple arrays of widgets. You can create buttons to take you to different pages of the interface by attaching some simple javascript to a widget:
"ontouchstart":"control.changePage(2)"
In addition to the array of pages, it is also important to define the loadedInterfaceName variable with a string naming your interface.
loadedInterfaceName = "myinterface";
This is usually placed above the pages array in the code. Finally, the other variable you might want to define is the interfaceOrientation variable; this variable can either hold the string “landscape” or “portrait” and will force the device orientation to change when the interface is loaded.
interfaceOrientation = "portrait";
Thus, a simple (the simplest?) interface file would be as follows:
loadedInterfaceName = "simple";
interfaceOrientation = "portrait";
pages = [ [
{
"name": "bigButton",
"type": "Button",
"width":1, "height":1,
"x":0, "y":0,
}
],
];
Notice the two [] brackets to open and close the pages multidimensional array. The first open bracket starts the array of pages, subsequent open brackets start a new page. The above widget doesn’t do very much; it just creates a button that fills the screen but doesn’t actually do anything when pressed. After we cover how to get custom interfaces into Control, we’ll look at building more advanced interfaces.