Skip to content

Controls

  • PUBLISHED: 2024-2-10
  • UPDATED: 2024-2-10

This document sourced and reformatted from Hexlers Touch OSC MKII Manual.

Fields

control.ID
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
local myType = self.type
print(myType == ControlType.BUTTON)
> true

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

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

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).
control.children[1 to n] Returns the child control at index 1 to n or nil if none is found.
#control.children Returns the number of child controls.
control.properties
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.

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 to n] Returns the current value of the property at index 1 to n or nil if none is found.

Since version 1.2.6.185 the list is always ordered alphabetically by property name. Earlier versions do not guarantee any particular order.
control.properties.keys Returns a list of all property names for the control in alphabetical order.
#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.

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

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 to n] Returns the current value of the value at index 1 to n or nil if none is found.

Since version 1.2.6.185 the list is always ordered alphabetically by value name, with the value named touch always at the end of the list. Earlier versions do not guarantee any particular order.
control.values.keys Returns a list of all value names for the control in alphabetical order with the value name touch always at the end of the list.
#control.values Returns the number of values in the list.

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

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

since 1.2.6.185

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

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.

See Snippets for more pointer example use.

Functions

getValueField(string, field)
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.

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

since 1.0.5.109

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.

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

setValueProperty(string, property, value)
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.

notify(string [, value])
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 booleannumberstringtable 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.

findByID(string [, boolean])
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.

findByType(controltype [, boolean])
function findByType(controltype [, boolean])


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

since 1.0.2.98

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.

findAllByType(controltype [, boolean])
function findAllByType(controltype [, boolean])


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

since 1.0.2.98

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.

findByProperty(string, value [, boolean])
local firstRedControl = self:findByProperty('color', Color(1,0,0))
local firstHiddenControl = self:findByProperty('visible', false)

since 1.0.2.98

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.

findAllByProperty(string, value [, boolean])
local allRedControls = self:findAllByProperty('color', Color(1,0,0))
local allHiddenControls = self:findAllByProperty('visible', false)

since 1.0.2.98

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.

findByName(string [, boolean])
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]).

findAllByName(string [, boolean])
local allChildrenNamedA = self:findAllByName('A')

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


Callback Functions

init()
function init()
  print("init")
end

since 1.0.8.122

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
update()
function update()
  print("Elapsed ms:", getMillis())
end

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

onValueChanged(string)
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).

onPointer(table)
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.

onReceiveMIDI(message, connections)
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)
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.

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

since 1.1.0.132

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.

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.