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
  • messages
  • 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


-- example
local myID = self.ID
local parentID = self.parent.ID
print(myID == parentID)
> false

A unique ID string, generated when the control is created. It remains unchanged over a control's lifetime, during document load/save and during editor network transmission.

control.type


-- example
local myType = self.type
print(myType == ControlType.BUTTON)
> true

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

control.index


-- example
local myIndex = self.index
local parentIndex = self.parent.index

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

control.parent


-- example
local myParentControl = self.parent
local noParentControl = root.parent -- will be nil, root has no parent

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

control.children


-- example
self.children.button1.visible = false -- set 'visible' property on child 'button1'
self.children['button1'].visible = false -- same as the previous line
local firstChild = self.children[1] -- first child control
local secondChild = self.children[2] -- second child control
print(#self.children) -- print the number of child controls

A list of the control's child Control objects. The list can be indexed by control name (a string) or index (a number). Control names are user assignable and not unique.

control.properties


-- example
self.properties.name = 'new_name'
self.properties['name'] = 'new_name' -- same as the previous line
self.name = 'new_name' -- same as the previous line
self.frame.x = 10
self.color = Color(1,0,0)
self.color.r = 0
print(#self.properties) -- print the number of properties

A list of the control's properties. The list can be indexed by property name (a string) or index (a 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


-- example
self.values.x = 1
self.values['x'] = 1 -- same as the previous line
print(#self.values) -- print the number of values

A list of the control's values. The list can be indexed by value name (a string) or index (a number). Value names are unique.

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

control.messages


-- example
local midiMessages = self.messages.MIDI -- same as: self.messages[1]
local oscMessages = self.messages.OSC -- same as: self.messages[2]
local localMessages = self.messages.LOCAL -- same as: self.messages[3]
local gamepadMessages = self.messages.GAMEPAD -- same: as self.messages[4]
print(#self.messages)
> 4

A list of the control's messages, containing separate lists for each message type. The list can be indexed by

• message type name (a string): MIDI, OSC, LOCAL, GAMEPAD
• index (a number): 1 - 4

The messages in each of the lists will be in the same order as they are displayed in the editor UI.

See Script · Objects · Messages for a description of the four message object types.

control.pointers


-- example
local pointer = self.pointers[1]
print(pointer.ID,
      pointer.x, pointer.y,
      pointer.state,
      pointer.created, pointer.modified)
> 0 33.285 20.393 1 1836924.838 1836914.867

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.

See Control Callback Functions for more pointer example use.

Functions

function getValueField(string, field)


-- example
self:getValueField('x', ValueField.CURRENT) -- same as: self.values.x
self:getValueField('x', ValueField.DEFAULT)

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[string].

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

function setValueField(string, field, value)


-- example
self:setValueField('x', ValueField.CURRENT, 1.0) -- same as: self.values.x = 1.0
self:setValueField('x', ValueField.DEFAULT, 0.5)

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.

function getValueProperty(string, property)


-- example
local valueLocked = self:getValueProperty('x', ValueProperty.LOCKED)
local valueType = self:getValueProperty('x', ValueProperty.TYPE)
print(valueType == ValueType.FLOAT)
> true

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.

function setValueProperty(string, property, value)


-- example
self:setValueProperty('x', ValueProperty.LOCKED, false)
self:setValueProperty('x', ValueProperty.DEFAULT_PULL, 50)

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

function notify(string [, value])


-- example
self.parent:notify('hello parent')
self.children.button1:notify('hello child', self.name)
self.children.button2:notify('hello child', 1.5)

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.

function findByID(string [, boolean])


-- example
local buttonID = self.children.button1.ID
local childButton = self:findByID(buttonID)

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.

function findByType(controltype [, boolean])


-- example
local firstChildButton = self:findByType(ControlType.BUTTON)
local firstChildFader = self:findByType(ControlType.FADER)

Returns the first child Control object whose 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.

function findAllByType(controltype [, boolean])


-- example
local allChildButtons = self:findAllByType(ControlType.BUTTON)
local allChildFaders = self:findAllByType(ControlType.FADER)

Returns a list of child Control objects whose 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.

function findByProperty(string, value [, boolean])


-- example
local firstRedControl = self:findByProperty('color', Color(1,0,0))
local firstHiddenControl = self:findByProperty('visible', false)

Returns the first child Control object whose 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.

function findAllByProperty(string, value [, boolean])


-- example
local allRedControls = self:findAllByProperty('color', Color(1,0,0))
local allHiddenControls = self:findAllByProperty('visible', false)

Returns a list of child Control objects whose current values 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.

function findByName(string [, boolean])


-- example
local childButton1 = self:findByName('button1') -- same as: self.children.button1
local childFader1 = self:findByName('fader1') -- same as: self.children.fader1

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

function findAllByName(string [, boolean])


-- example
local allChildrenNamedA = self:findAllByName('A')

Equivalent to calling 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()


-- example
function init()
  print("init")
end

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()


-- example
function update()
  print("Elapsed ms:", getMillis())
end

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

function onValueChanged(string)


-- example
function onValueChanged(valueName)
  print("Value of ", valueName, "has changed to", self.values[valueName])
end

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


-- example
function onPointer(pointers)
  print('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

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


-- example
function onReceiveMIDI(message, connections)
  print('onReceiveMIDI')
  print('\t message     =', table.unpack(message))
  print('\t connections =', table.unpack(connections))
end

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 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 true is returned from that 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)


-- example
function onReceiveOSC(message, connections)
  print('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

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 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 true is returned from that 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)


-- example
function onReceiveGamepad(input, value, connections)
  print('onReceiveGamepad')
  print('\t input       =', input) -- one of the GamepadInput enumeration values
  print('\t value       =', value)
  print('\t connections =', table.unpack(connections))
end

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 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 true is returned from that 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])


-- example
function onReceiveNotify(key, value)
  print('onReceiveNotify')
  print('\t key   =', key)
  print('\t value =', value)
end

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.