SCRIPTING API ^β

Updated for version 0.1.9

SCRIPTING API βLua Functionsbase ⇢table ⇢math ⇢string ⇢Global FunctionsUtililty FunctionsMessage FunctionsMIDI MessagesSimple OSC MessagesComplex OSC MessagesObjectsControlFieldsFunctionsCallback FunctionsRectangleFieldsConstructor functionsFunctionsColorFieldsConstructor functionsOperatorsStatic functionsVector typesFieldsConstructor functionsFunctionsOperatorsEnumerationsControlTypeShapeOutlineStyleButtonTypeRadioTypeResponseOrientationAlignHAlignVPointerStatePointerPriorityValueTypeValueFieldValuePropertyCursorDisplayMIDIMessageTypeConstantsColorsControl Properties and ValuesCommonPropertiesValuesBOXPropertiesBUTTONPropertiesValuesLABELPropertiesValuesTEXTPropertiesValuesFADERPropertiesValuesXYPropertiesValuesRADIALPropertiesValuesENCODERPropertiesValuesRADARPropertiesValuesRADIOPropertiesValuesPAGERPropertiesValuesExamplesControl Callback FunctionsSending MIDI MessagesSending OSC MessagesDetect Control 'Double-tap'Send Periodic MessageSend Accelerometer Data

TouchOSC's scripting layer is based on the Lua 5.1 language and virtual machine with custom additions and modifications.

Scripts can be added to all controls in a document and at the document root level. Each control's script will be executed in its own Lua context.

Lua Functions

The following Lua standard library functions are available.

base ⇢

Only the following Lua base library functions are available:


error
ipairs
next
pairs
print
select
tonumber
tostring
unpack
type

table ⇢

All standard Lua table library functions are available plus the following additions:


xxxxxxxxxx
table.pack(...)

Returns a new sequential table created from the elements provided.


xxxxxxxxxx
table.unpack(...)

Same as the Lua base library function unpack.

math ⇢

All standard Lua math library functions are available plus the following additions:


xxxxxxxxxx
math.clamp(number, number, number)

Returns min(max(x, minVal), maxVal) where x is the first parameter and minVal and maxVal the second and third parameters.

string ⇢

All standard Lua string library functions are available.

Global Functions

TouchOSC provides the following global functions.

Utililty Functions


xxxxxxxxxx
getVersion()

Returns a table with the application's version as major minor patch build number values stored in sequential order.


xxxxxxxxxx
getMillis()

Returns the number of milliseconds since application start.


xxxxxxxxxx
getDate()

Returns a table with the current local date's year month day tzd number values stored in sequential order. tzd refers to the timezone differential in seconds.


xxxxxxxxxx
getTime()

Returns a table with the current local time's hour minute second millisecond number values stored in sequential order.


xxxxxxxxxx
hasAccelerometer()

Returns true if the host device provides an accelerometer sensor, false otherwise.


xxxxxxxxxx
getAccelerometer()

Returns a list of three number values that are sampled from the host device's accelerometer sensor. If no accelerometer sensor is available, the values will be all zero.


xxxxxxxxxx
hasGyroscope()

Returns true if the host device provides a gyroscope sensor, false otherwise.


xxxxxxxxxx
getGyroscope()

Returns a list of three number values that are sampled from the host device's gyroscope sensor. If no gyroscope sensor is available, the values will be all zero.


xxxxxxxxxx
getBatteryLevel()

Returns the current battery charge level as a number ranging from 0.0 to 1.0 on mobile devices, 1.0 otherwise.


xxxxxxxxxx
bytesToInt(number, number, number, number)

Returns a number that is the 32-bit integer representation created from the four byte number values supplied.


xxxxxxxxxx
bytesToFloat(number, number, number, number)

Returns a number that is the 32-bit floating point representation created from the four byte number values supplied.

Message Functions

TouchOSC provides the following functions to send MIDI and OSC messages.

MIDI Messages


xxxxxxxxxx
sendMIDI(table [, table])

Send a MIDI message on one or multiple configured connections.

The first argument table is a list of byte values that make up the MIDI message.

The optional second argument table is a list of boolean values that specify which connections to send the message on. If the argument is omitted, the default is to broadcast the message on all configured connections. If the table has less than five elements, the omitted elements default to false.

See Sending MIDI Messages for example code.

Simple OSC Messages


xxxxxxxxxx
sendOSC(string [, ... [, table]])

Send an OSC message on one or multiple configured connections.

string is the path of the OSC message to be sent.

The optional argument values ... will be auto-converted to boolean, float or string OSC types and added to the OSC message as arguments.

Note that argument values are never auto-converted to integer OSC types as scripts do not treat floating point and integer numbers as separate types. Use the complex OSC message send function instead.

The optional last argument table is a list of boolean values that specify which connections to send the message on. If the argument is omitted, the default is to broadcast the message on all configured connections. If the table has less than five elements, the omitted elements default to false.

See Sending OSC Messages for example code.

Complex OSC Messages


xxxxxxxxxx
sendOSC(table [, table])

Sends an OSC message on one or multiple configured connections.

The first argument table is a list that represents the OSC message to be sent, where the first element is the path string of the message, and the second element is a list of argument tables with tag and value keys for each argument:


xxxxxxxxxx
{
    path,
    {
        { tag = 'argumentTypeTag', value = argumentValue },
        { tag = 'argumentTypeTag', value = argumentValue },
        { tag = 'argumentTypeTag', value = argumentValue },
        ...
    }
}

Each argument value will be converted to an OSC type according to the type tag string provided:

Tag	OSC Type
`T`	Boolean true
`F`	Boolean false
`N`	Nil
`I`	Infinitum
`i`	int32
`f`	float32
`s`	string
`b`	blob

If the tag key is omitted, the value will be auto-converted the same way as when sending simple OSC messages.

The T F N and I types do not need a value to be specified.

The b OSC blob type expects the value to be a list of byte values making up the blob data.

See Sending OSC Messages for example code.

Objects

TouchOSC defines the following objects to represent its internal and native types.

Control

A control object represents a reference to a single control contained within a TouchOSC document.

Using this reference most of a control's properties and values can be queried and set. From within a control's script, the self reference can be used to refer to the control's own fields and functions.

Each control is assigned a unique ID on creation that remains unchanged during and between application runs, document save/load and editor network transfer.

All controls live in a document tree hierarchy starting at the document root. All controls except for the root have a reference to a parent control, and some control types are containers for child controls.

During compilation each script will be checked for the definitions of any of the callback functions listed below, which serve as the main customization points during the various stages of TouchOSC's processing of an application frame.

Fields


xxxxxxxxxx
control.ID

A unique ID string, constant for a control's lifetime, between document load/save and during editor network transmission.


xxxxxxxxxx
control.type

Control type numeric constant, one of the ControlType enumeration values.


xxxxxxxxxx
control.index

The control's position in its parent list of child controls, 1-n for regular controls, 0 for the document root.


xxxxxxxxxx
control.parent

A reference to the control's parent Control object, or nil for the document root.


xxxxxxxxxx
control.children

A reference to TouchOSC's native container object for a list of the control's child Control objects. The container can be indexed by control name string or index number. Control names are user assignable and not unique.

Usage	Description
`control.children.name` `control.children[name]`	Returns the first child control with name `name` or `nil` if none is found. Indexing by name is equivalent to calling `control:findByName(name, false)`.
`control.children[1-n]`	Returns the child control at index `1-n` or `nil` if none is found.
`#control.children`	Returns the number of child controls.


xxxxxxxxxx
control.properties

A reference to TouchOSC's native container object for a list of the control's properties with no guaranteed ordering. The container can be indexed by property name string or index number. Property names are unique.

Usage	Description
`control.properties.name` `control.properties[name]`	Returns the current value of the property with name `name` or `nil` if none is found.
`control.properties[1-n]`	Returns the current value of the property at index `1-n` or `nil` if none is found.
`control.properties.keys`	Returns a table of all property names in the list.
`#control.properties`	Returns the number of properties in the list.

NOTE For convenience, indexing a control reference directly using control.name or control[name], where name is not one of the field or function names listed here, will implicitly index the control's property list with control.properties[name].

Therefore control.color and control.properties.color will refer to the same property value.

See Control Properties and Values for a list of possible properties for each control type.


xxxxxxxxxx
control.values

A reference to TouchOSC's native container object for a list of the control's values with no guaranteed ordering. The container can be indexed by value name string or index number. Value names are unique.

Usage	Description
`control.values.name` `control.values[name]`	Returns the current value of the control value with name `name` or `nil` if none is found.
`control.values[1-n]`	Returns the current value of the value at index `1-n` or `nil` if none is found.
`control.values.keys`	Returns a table of all value names in the list.
`#control.values`	Returns the number of values. in the list.

See Control Properties and Values for a list of possible values for each control type.


xxxxxxxxxx
control.pointers

A list containing one table for each pointer currently associated with the control during the current frame with the following table keys per pointer:

Key	Description
`ID`	The numeric ID of the pointer. Constant during the pointers lifetime.
`x`	The x position of the pointer.
`y`	The y position of the pointer.
`state`	The current state of the pointer, one of the possible values of the `PointerState` enumeration.
`created`	The time the pointer event began, in milliseconds as returned by the `getMillis` global function.
`modified`	The time of the last modification of this pointer, in milliseconds as returned by the `getMillis` global function.

Each pointer progresses through the states in the PointerState enumeration during its lifetime:

After being created the pointer will be in state PointerState.BEGIN for one frame.
During its lifetime the pointer will be either in state PointerState.ACTIVE or PointerState.MOVE depending on whether the pointer's position has changed since the last frame.
When the pointer event ends it will be in state PointerState.END for one frame and will then be removed from the list of pointers.

Functions


xxxxxxxxxx
control:getValueField(string, field)

Returns a value of the control value with name string or nil if none is found.

The parameter field can be one of the possible values of the ValueField enumeration and determines which value is returned:

ValueField.CURRENT Returns the current value.
ValueField.LAST Returns the value before the last change.
ValueField.DEFAULT Returns the default value.

Invoking the function with field parameter ValueField.CURRENT is equivalent to referencing control.values.name.

See Control Properties and Values for a list of possible values for each control type.


xxxxxxxxxx
control:getValueProperty(string, property)

Returns the value of the property property of the control value with name string or nil if none is found.

The parameter property can be one of the possible values of the ValueProperty enumeration and determines which property value is returned:

ValueProperty.TYPE - The type of the value, one of the possible values of the ValueType enumeration
ValueProperty.LOCKED - Locked state of the value, a boolean value
ValueProperty.LOCKED_DEFAULT_CURRENT - Default and current value locked state, a boolean value
ValueProperty.DEFAULT_PULL - Default pull of the value, an integer value ranging from 0 to 100

See Control Properties and Values for a list of possible values for each control type.


xxxxxxxxxx
control:setValueProperty(string, property, value)

Set the value of the property property of the control value with name string.

The parameter property can be one of the possible values of the ValueProperty enumeration with the exception of ValueProperty.TYPE and determines which property value is set.

See the control:getValueProperty function above for a description of the possible value properties.

See Control Properties and Values for a list of possible values for each control type.


xxxxxxxxxx
control:notify(string [, value])

Invokes the onReceiveNotify callback function on another control.

The parameter string and an optional parameter value will be copied to the receiving control's Lua context and passed to the onReceiveNotify callback function, only if that callback function is defined in the receiving control's script. Calling the function on self has no effect.

The optional parameter value can be of any Lua type except for function, userdata or thread.


xxxxxxxxxx
control:findByID(string [, boolean])

Returns the child Control object with ID string or nil if none is found. The optional boolean parameter determines if the search will be recursive and descend the child control hierarchy, defaults to false.


xxxxxxxxxx
control:findByName(string [, boolean])

Returns the first child Control object with name string or nil if none is found. The optional boolean parameter determines if the search will be recursive and descend the child control hierarchy, defaults to false.


xxxxxxxxxx
control:findAllByName(string [, boolean])

Returns a list of child Control objects with name string or an empty list if none are found. The optional boolean parameter determines if the search will be recursive and descend the child control hierarchy, defaults to false.

Callback Functions

If any of the following functions are defined in a control's script, these callback functions are invoked during the various stages of processing of an application frame.

When considering a script function for registration as a callback, the parameter declarations are optional and the function will be called regardless of the parameters being omitted or not.

See Control Callback Functions for example implementations.


xxxxxxxxxx
function update()

Called once per application frame after all processing of user input and received messages has completed.


xxxxxxxxxx
function onValueChanged(string)

Called after any of the control's values has changed, once for each changed value, and before any further processing as a result of the change.

The parameter string is the name of the value that has changed. It is valid to set the changed value again from inside the callback, but note that the callback will not be invoked again as a result.

Returning a value that evaluates to true from this callback will end any further processing TouchOSC would normally do as a result of the change (ie sending of messages).


xxxxxxxxxx
function onPointer(table)

Called after processing of user input is complete and all active pointers (mouse cursor or touch input) have been mapped and assigned to any controls, and before any further processing of the pointer state and internal control behavior in response to the pointer input is evaluated.

Will only be invoked if there are any pointers associated with the control during the current frame.

The table passed as parameter to the callback contains a list of one or more pointers that have been selected as the significant event input according to the control's configuration and do not necessarily include all pointers currently associated with the control.

For example, a button type control will commonly only be interested in a single significant touch input, which will be selected by the application and passed to the control for processing based on the control's configuration.

To access all pointers currently associated with a control access the control.pointers field.

Returning a value that evaluates to true from this callback will end any further processing TouchOSC would normally do for the current control as a result of the input (ie changing a control's values).

For a description of the pointer table format and pointer states see the control.pointers field.


xxxxxxxxxx
function onReceiveMIDI(message, connections)

Called after receiving a MIDI message and determining that the control should be a receiver of the message according to the routing table, and before any further evaluation or processing of potential changes to a control's values or properties.

Returning a value that evaluates to true from this callback will end any further processing TouchOSC would normally do for the current control as a result of receiving the message (ie changing a control's values or properties).

NOTE If it is defined, the document root's onReceiveMIDI callback function will always be invoked first, and if a value that evaluates to true is returned from the callback, processing of the message will end, it will not be passed along to any other controls in the routing table and no further callbacks will be invoked.

For the format of the message and connections parameters see the sendMIDI function.


xxxxxxxxxx
function onReceiveOSC(message, connections)

Called after receiving an OSC message and determining that the control should be a receiver of the message according to the routing table, and before any further evaluation or processing of potential changes to a control's values or properties.

NOTE If it is defined, the document root's onReceiveOSC callback function will always be invoked first, and if a value that evaluates to true is returned from the callback, processing of the message will end, it will not be passed along to any other controls in the routing table and no further callbacks will be invoked.

For the format of the message and connections parameters see the sendOSC function for complex messages.


xxxxxxxxxx
function onReceiveNotify(string [, value])

Called as a result of the control's notify function begin called by another control.

The parameters string and an optional value will be copied from the calling control's Lua context to the receiving control's Lua context and passed as parameters to the callback function.

Please note that because the parameter values have to be copied between Lua execution contexts, and because this introduces some overhead, it is advisable not to invoke the notify function from inside the update function every frame but only in response to events such as received messages, changed pointer input or value changes.

Rectangle

A rectangle object native to TouchOSC. Will be returned and can be passed anywhere a rectangle is required.

Fields


xxxxxxxxxx
rectangle.x

The x position of the rectangle.


xxxxxxxxxx
rectangle.y

The y position of the rectangle.


xxxxxxxxxx
rectangle.w

The width of the rectangle.


xxxxxxxxxx
rectangle.h

The height of the rectangle.

Constructor functions


xxxxxxxxxx
Rectangle()                               -- [1]                  
Rectangle(rectangle)                      -- [2]
Rectangle(number, number)                 -- [3]
Rectangle(number, number, number, number) -- [4]

Returns a new rectangle with

position and size set to (0,0).
position and size copied from another Rectangle object.
position set to (0,0) and size set to the two numbers.
position set to the first pair of numbers and size set to the second two numbers.

Functions


xxxxxxxxxx
rectangle:contains(number, number)

Tests if the point at position (number, number) is contained within the rectangle and returns a boolean value.

Color

A color object native to TouchOSC. Will be returned and can be passed anywhere a color is required. Color components are stored as floating point values ranging from 0.0 to 1.0.

Fields


xxxxxxxxxx
color.r

The red component of the color.


xxxxxxxxxx
color.g

The green component of the color.


xxxxxxxxxx
color.b

The blue component of the color.


xxxxxxxxxx
color.a

The alpha component of the color.

Constructor functions


xxxxxxxxxx
Color()                               -- [1]
Color(color)                          -- [2]
Color(number)                         -- [3]
Color(number, number)                 -- [4]
Color(number, number, number)         -- [5]
Color(number, number, number, number) -- [6]

Returns a new color with

all components initialized with 0.0.
all components copied from another Color object.
all components initialized with number.
rgb components initialized with the first number, the a component initialized with the second number.
rgb components initialized with the three numbers, the a component initialized with 1.0
rgba components initialized with the four numbers provided.

Operators


xxxxxxxxxx
-- multiplication
color * color
color * number
-- division
color / color
color / number
-- addition
color + color
color + number
-- subtraction
color - color
color - number

All operators operate component-wise and return a new color object.

Static functions


xxxxxxxxxx
Color.toHexString(color)

Returns a hexadecimal string representation of the color in the format RRGGBBAA.


xxxxxxxxxx
Color.fromHexString(string)

Returns a color object created from the hexadecimal string representation. The string can be in one of the following formats: RRGGBBAA, RRGGBB, GGAA, GG, with the latter two forms creating a grayscale color from the GG value.

Vector types

TouchOSC provides 2,3 and 4 component vector types as Vec2 Vec3 Vec4 objects.

Fields


xxxxxxxxxx
vec2.x
vec3.x
vec4.x

The x component of the vector.


xxxxxxxxxx
vec2.y
vec3.y
vec4.y

The y component of the vector.


xxxxxxxxxx
vec3.z
vec4.z

The z component of the vector.


xxxxxxxxxx
vec4.w

The w component of the vector.

Constructor functions


x
Vec2()                                -- [1]
Vec2(vec2)                            -- [2]
Vec2(number)                          -- [3]
Vec2(number, number)                  -- [4]
Vec3()                                -- [1]
Vec3(vec3)                            -- [2]
Vec3(number)                          -- [3]
Vec3(number, number, number)          -- [4]
Vec4()                                -- [1]
Vec4(vec4)                            -- [2]
Vec4(number)                          -- [3]
Vec4(number, number, number, number)  -- [4]

Returns a new vector with

all components initialized with 0.0.
all components copied from another vector object.
all components initialized with number.
each component initialized with the numbers provided.

Functions


xxxxxxxxxx
vec:length()

Returns the length of the vector


xxxxxxxxxx
vec:normalize()

Returns a new vector that is the normalized vector

Operators


xxxxxxxxxx
-- multiplication
vector * vector
vector * number
-- division
vector / vector
vector / number
-- addition
vector + vector
vector + number
-- subtraction
vector - vector
vector - number

All operators operate component-wise and return a new vector object.

Enumerations

ControlType

Possible values for a Control object's type field.

ControlType.BOX
ControlType.BUTTON
ControlType.LABEL
ControlType.TEXT
ControlType.FADER
ControlType.XY
ControlType.RADIAL
ControlType.ENCODER
ControlType.RADAR
ControlType.RADIO
ControlType.GROUP
ControlType.PAGER
ControlType.GRID

Shape

Possible values for a Control object's shape property.

Shape.RECTANGLE
Shape.CIRCLE
Shape.TRIANGLE
Shape.DIAMOND
Shape.PENTAGON
Shape.HEXAGON

OutlineStyle

Possible values for a Control object's outlineStyle property.

OutlineStyle.FULL
OutlineStyle.CORNERS
OutlineStyle.EDGES

ButtonType

Possible values for a Control object's buttonType property.

ButtonType.MOMENTARY
ButtonType.TOGGLE_RELEASE
ButtonType.TOGGLE_PRESS

RadioType

Possible values for a Control object's radioType property.

RadioType.SELECT
RadioType.METER

Response

Possible values for a Control object's response property.

Response.ABSOLUTE
Response.RELATIVE

Orientation

Possible values for a Control object's orientation property.

Orientation.NORTH
Orientation.EAST
Orientation.SOUTH
Orientation.WEST

AlignH

Possible values for a Control object's textAlignH property.

AlignH.LEFT
AlignH.CENTER
AlignH.RIGHT

AlignV

Possible values for a Control object's textAlignV property.

AlignV.TOP
AlignV.MIDDLE
AlignV.BOTTOM

PointerState

PointerState.BEGIN
PointerState.ACTIVE
PointerState.MOVE
PointerState.END

PointerPriority

PointerPriority.OLDEST
PointerPriority.NEWEST

ValueType

ValueType.BOOLEAN
ValueType.INTEGER
ValueType.FLOAT
ValueType.STRING

ValueField

ValueField.CURRENT
ValueField.LAST
ValueField.DEFAULT

ValueProperty

ValueProperty.TYPE
ValueProperty.LOCKED
ValueProperty.LOCKED_DEFAULT_CURRENT
ValueProperty.DEFAULT_PULL

CursorDisplay

CursorDisplay.ALWAYS
CursorDisplay.ACTIVE
CursorDisplay.INACTIVE

MIDIMessageType

MIDIMessageType.NOTE_OFF
MIDIMessageType.NOTE_ON
MIDIMessageType.POLYPRESSURE
MIDIMessageType.CONTROLCHANGE
MIDIMessageType.PROGRAMCHANGE
MIDIMessageType.CHANNELPRESSURE
MIDIMessageType.PITCHBEND
MIDIMessageType.SYSTEMEXCLUSIVE
MIDIMessageType.QUARTERFRAME
MIDIMessageType.SONGPOSITION
MIDIMessageType.SONGSELECT
MIDIMessageType.CLOCK
MIDIMessageType.START
MIDIMessageType.CONTINUE
MIDIMessageType.STOP
MIDIMessageType.ACTIVESENSING
MIDIMessageType.SYSTEMRESET

Constants

Colors

Colors.clear
Colors.black
Colors.white
Colors.red
Colors.green
Colors.blue
Colors.orange
Colors.yellow
Colors.cyan
Colors.purple
Colors.violet
Colors.gray
Colors.darkGray
Colors.lightGray

Control Properties and Values

Common

Properties and values that are common to all controls, independent of their type. Not all control types will utilize the value of these properties.

Properties

Name	Description
`name`	A user-editable string.
`frame`	A `Rectangle` object.
`color`	A `Color` object.
`visible`	A boolean value.
`interactive`	A boolean value.
`background`	A boolean value.
`outline`	A boolean value.
`outlineStyle`	One of the possible values of the `OutlineStyle` enumeration.
`grabFocus`	A boolean value.
`pointerPriority`	One of the possible values of the `PointerPriority` enumeration.
`corner`	An integer number value ranging from `0` to `10`
`orientation`	One of the possible values of the `Orientation` enumeration.
`script`	A string value. The control's script source code.

Values

Name	Description
`touch`	A boolean value. `true` if any pointers are associated with the control in the current frame, `false` otherwise. For a control to be able to be associated with a pointer, its `visible` and `interactive` properties have to both be `true`

BOX

Properties

Name	Description
`shape`	One of the possible values of the `Shape` enumeration

BUTTON

Properties

Name	Type
`shape`	One of the possible values of the `Shape` enumeration.
`buttonType`	One of the possible values of the `ButtonType` enumeration.
`press`	A boolean value.
`release`	A boolean value.
`valuePosition`	A boolean value.

Values

Name	Description
`x`	A floating point value ranging from `0.0` to `1.0`.

LABEL

Properties

Name	Type
`textSize`	An integer value.
`textLength`	An integer value.
`textAlignH`	One of the possible values of the `AlignH` enumeration.
`textAlignV`	One of the possible values of the `AlignV` enumeration.
`textColor`	A `Color` object.
`textClip`	A boolean value.

Values

Name	Description
`text`	A string value.

TEXT

Properties

Name	Type
`textSize`	An integer value.
`textColor`	A `Color` object.

Values

Name	Description
`text`	A string value.

FADER

Properties

Name	Type
`cursor`	A boolean value.
`cursorDisplay`	One of the possible values of the `CursorDisplay` enumeration.
`bar`	A boolean value.
`barDisplay`	One of the possible values of the `CursorDisplay` enumeration.
`centered`	A boolean value.
`response`	One of the possible values of the `Response` enumeration.
`responseFactor`	An integer value ranging from `1` to `100`.
`grid`	A boolean value.
`gridSteps`	An integer value.

Values

Name	Description
`x`	A floating point value ranging from `0.0` to `1.0`.

XY

Properties

Name	Type
`cursor`	A boolean value.
`cursorDisplay`	One of the possible values of the `CursorDisplay` enumeration.
`lines`	A boolean value.
`linesDisplay`	One of the possible values of the `CursorDisplay` enumeration.
`lockX`	A boolean value.
`lockY`	A boolean value.
`response`	One of the possible values of the `Response` enumeration.
`responseFactor`	An integer value ranging from `1` to `100`.
`gridX`	A boolean value.
`gridY`	A boolean value.
`gridStepsX`	An integer value.
`gridStepsY`	An integer value.

Values

Name	Description
`x`	A floating point value ranging from `0.0` to `1.0`.
`y`	A floating point value ranging from `0.0` to `1.0`.

RADIAL

Properties

Name	Type
`inverted`	A boolean value.
`centered`	A boolean value.
`response`	One of the possible values of the `Response` enumeration.
`responseFactor`	An integer value ranging from `1` to `100`.
`grid`	A boolean value.
`gridSteps`	An integer value.

Values

Name	Description
`x`	A floating point value ranging from `0.0` to `1.0`.

ENCODER

Properties

Name	Type
`cursor`	A boolean value.
`cursorDisplay`	One of the possible values of the `CursorDisplay` enumeration.
`response`	One of the possible values of the `Response` enumeration.
`responseFactor`	An integer value ranging from `1` to `100`.
`grid`	A boolean value.
`gridSteps`	An integer value.

Values

Name	Description
`x`	A floating point value ranging from `0.0` to `1.0`.
`y`	A floating point value ranging from `0.0` to `1.0`.

RADAR

Properties

Name	Type
`cursor`	A boolean value.
`cursorDisplay`	One of the possible values of the `CursorDisplay` enumeration.
`lines`	A boolean value.
`linesDisplay`	One of the possible values of the `CursorDisplay` enumeration.
`lockX`	A boolean value.
`lockY`	A boolean value.
`gridX`	A boolean value.
`gridY`	A boolean value.
`gridStepsX`	An integer value.
`gridStepsY`	An integer value.

Values

Name	Description
`x`	A floating point value ranging from `0.0` to `1.0`.
`y`	A floating point value ranging from `0.0` to `1.0`.

RADIO

Properties

Name	Type
`steps`	An integer value.
`radioType`	One of the possible values of the `RadioType` enumeration.

Values

Name	Description
`x`	An integer value ranging from `0` to the value of the `steps` property minus one.

PAGER

Properties

Name	Type
`tabbar`	A boolean value.
`tabbarSize`	An integer value ranging from `10` to the value of the `300`.
`tabbarDoubleTap`	A boolean value.
`tabLabels`	A boolean value.
`textSizeOff`	An integer value.
`textSizeOn`	An integer value.

Values

Name	Description
`page`	An integer value ranging from `0` to the number of pages minus one.

Examples

Control Callback Functions


xxxxxxxxxx
function update()
    print(self.name, "update")
end
function onPointer(pointers)
    print(self.name, "onPointer")
    for i=1,#pointers do
        local pointer = pointers[i]
        print("\t", pointer.ID, pointer.x, pointer.y, pointer.state, pointer.created, pointer.modified)
    end
end
function onValueChanged(key)
    print(self.name, "onValueChanged")
    print("\t", key, "=", self.values[key])
end
function onReceiveMIDI(message, connections)
    print(self.name, "onReceiveMIDI")
    print("\t message     =", table.unpack(message))
    print("\t connections =", table.unpack(connections))
end
function onReceiveOSC(message, connections)
    print(self.name, "onReceiveOSC")
    local path = message[1]
    local arguments = message[2]
    print("\t path        =", path)
    for i=1,#arguments do
        print("\t argument    =", arguments[i].tag, arguments[i].value) 
    end
    print("\t connections =", table.unpack(connections))
end
function onReceiveNotify(key, value)
    print(self.name, "onReceiveNotify")
    print("\t key   =", key)
    print("\t value =", value)
end

Sending MIDI Messages


xxxxxxxxxx
-- control change, controller 0, channel 1
-- all configured connections (1-5)
sendMIDI({ 176, 0, 102 })                               
sendMIDI({ MIDIMessageType.CONTROLCHANGE, 0, 102 })
-- control change, controller 0, channel 2
-- all configured connections (1-5)
sendMIDI({ 177, 0, 103 })                               
sendMIDI({ MIDIMessageType.CONTROLCHANGE + 1, 0, 103 })
-- control change, controller 2, channel 6
-- all configured connections (1-5)
sendMIDI({ 181, 2, 104 })
sendMIDI({ MIDIMessageType.CONTROLCHANGE + 5, 2, 104 })
-- send only on connections 1 and 2
sendMIDI({ MIDIMessageType.NOTE_ON, 12, 88 }, { true, true })
sendMIDI({ MIDIMessageType.NOTE_OFF, 12, 0 }, { true, true })
-- send only on connections 1 and 3
sendMIDI({ MIDIMessageType.NOTE_ON, 13, 88 }, { true, false, true })
sendMIDI({ MIDIMessageType.NOTE_OFF, 13, 0 }, { true, false, true })
-- send only on connections 1 and 5
sendMIDI({ MIDIMessageType.NOTE_ON, 14, 88 }, { true, false, false, false, true })
sendMIDI({ MIDIMessageType.NOTE_OFF, 14, 0 }, { true, false, false, false, true })
-- send system exlusive
sendMIDI({ 0xF0, 0x00, 0x01, 0xF7 })
sendMIDI({ MIDIMessageType.SYSTEMEXCLUSIVE, 0x00, 0x0D, 0xF7 })

Sending OSC Messages


xxxxxxxxxx
-- -----------------------------------------
-- Send simple OSC messages
--
-- arguments are auto-converted to 
-- boolean, float or string (not integer!) 
-- -----------------------------------------
-- send on all configured connections (1-5)
sendOSC("/simple")
sendOSC("/ping", "pong")
sendOSC("/on", true)
sendOSC("/1/fader1", 0.5)
sendOSC("/3/xy1", 0.25, 0.75)
sendOSC("/mixedarguments", "Hello", 1, true, "World")
-- send only on connections 1 and 2
sendOSC("/1/fader1", 0.5, { true, true })
-- send only on connections 1 and 3
sendOSC("/3/xy1", 0.25, 0.75, { true, false, true })
-- send only on connections 1 and 5
sendOSC("/mixedarguments", "Hello", 1, true, "World", { true, false, false, false, true })
-- -----------------------------------------
-- Send complex OSC messages 
-- with argument type tags
-- -----------------------------------------
sendOSC(
    -- message
    {
        -- path
        "/complex",
        
        -- argument list
        {
            { tag = 'T' },                                    -- true
            { tag = 'F' },                                    -- false
            { tag = 'N' },                                    -- nil
            { tag = 'I' },                                    -- infinitum
            { tag = 'i', value = 42 },                        -- int32
            { tag = 'f', value = 3.14 },                      -- float32
            { tag = 's', value = 'Goodbye Cruel World' },     -- string
            { tag = 'b', value = { 0xC0, 0x00, 0x10, 0xFF } } -- blob
        }
    },
    -- connections
    {
        true, -- 1
        true, -- 2
        true, -- 3
        true, -- 4
        true  -- 5
    }
)

Detect Control 'Double-tap'


xxxxxxxxxx
local delay = 300
local last = 0
function onValueChanged()
    if(not self.values.touch) then
        local now = getMillis()
        if(now - last < delay) then
            print("double tap!")
            last = 0
        else
            last = now
        end
    end
end

Send Periodic Message


xxxxxxxxxx
local delay = 1000 -- every 1000ms = 1s
local last = 0
function update()
    local now = getMillis()
    if(now - last > delay) then
        last = now
        sendOSC("/ping")
    end
end

Send Accelerometer Data


xxxxxxxxxx
if(hasAccelerometer()) then
    update = function()
        local values = getAccelerometer()
        sendOSC("/accxyz", table.unpack(values))
    end
end