TouchOSC

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, the root reference (since 1.0.5.109) can be used to refer to the document's root control.

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
  • ID
  • type
  • index
  • parent
  • children
  • properties
  • values
  • pointers
• Functions
  • getValueField
  • setValueField
  • getValueProperty
  • setValueProperty
  • notify
  • findByID
  • findByType
  • findAllByType
  • findByProperty
  • findAllByProperty
  • findByName
  • findAllByName
• Callback Functions
  • init
  • update
  • onValueChanged
  • onPointer
  • onReceiveMIDI
  • onReceiveOSC
  • onReceiveGamepad
  • onReceiveNotify

Fields

control.ID

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

control.type

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

control.index

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

control.parent

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

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.

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.

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.

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.

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

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:

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

control:getValueField(string, field)

Returns a value field 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.

control:setValueField(string, field, value)

Set a value field of the control value with name string.

The parameter field can be one of the following values of the ValueField enumeration, and determines which value field will be set:

• ValueField.CURRENT Set the current value.
• ValueField.DEFAULT Set the default value.

Invoking the function with field parameter ValueField.CURRENT is equivalent to calling control.values[string] = value.

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.

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.

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 type boolean, number, string, table or any of TouchOSC's object types.

Please note that because the parameter values have to be copied between Lua execution contexts and because this introduces overhead, it is advisable not to invoke the notify function from inside the update function every frame.

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.

control:findByType(controltype [, boolean])

Returns the child Control object which type matches controltype or nil if none is found. The controltype parameter can be any of the ControlType enumeration values. The optional boolean parameter determines if the search will be recursive and descend the child control hierarchy, defaults to false.

control:findAllByType(controltype [, boolean])

Returns a list of child Control objects which types match controltype or an empty list if none are found. The controltype parameter can be any of the ControlType enumeration values. The optional boolean parameter determines if the search will be recursive and descend the child control hierarchy, defaults to false.

control:findByProperty(string, value [, boolean])

Returns the child Control object where the current value of the property named string matches the provided value 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.

control:findAllByProperty(string, value [, boolean])

Returns a list of child Control objects where the current value of the property named string matches the provided value 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.

control:findByName(string [, boolean])

Equivalent to calling control:findByProperty('name', string [, boolean]).

control:findAllByName(string [, boolean])

Equivalent to calling control:findAllByProperty('name', string [, boolean]).

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.

function init()

Called once when the application transitions from editing mode to control surface mode.

Note that this function might be called again under certain conditions:

• When the application comes back to the foreground after being suspended on a mobile device
• When the application is running as editor network client and receives updates from the server that significantly change the structure of the local document

function update()

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

function onValueChanged(string)

Called after any of the control's values have 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).

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.

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.

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.

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 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.

function onReceiveGamepad(input, value, connections)

Called after receiving input from a connected game controller and determining that the control should be a receiver of the input 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 input (ie changing a control's values or properties).

NOTE If it is defined, the document root's onReceiveGamepad 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.

The first parameter input will be one of the possible values of the GamepadInput enumeration.

The second parameter value will be the raw, numeric value as received by the game controller.

See the Control Callback Functions sample script for an example of how to handle game controller messages.

function onReceiveNotify(string [, value])

Called as a result of the control's notify function being 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 overhead, it is advisable not to invoke the notify function from inside the update function every frame.