Touch OSC Lua Cheet Sheet

PUBLISHED: 2024-2-8
UPDATED: 2024-2-27

Why make this?¶

In my quest to master Touch OSC MKII, I've ventured deep into the labyrinth of its manual and formatted the information in a different way. Not only does creating this guide serve as a deep dive into learning the intricacies of Touch OSC, but it also became an essential tool in my arsenal, especially since my forays into editing Touch OSC templates aren't a daily ritual.

The journey into the world of Touch OSC is ongoing, and I’m excited to share the insights and tricks I've gathered along the way. Lua everywhere!

Version¶

This cheat sheet is a work inp progress. ~~up to date with Touch OSC version 1.2.7.190~~

Snippets¶

My personal library of useful Lua Snippets.

Midi¶

onReceiveMIDI()

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

sendMIDI()

Sending Midi

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

Color¶

Color()

color.r
color.g
color.b
color.a 

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

Color.toHexString(color)
Color.fromHexString(string)

-- multiplication
color * color
color * number

-- division
color / color
color / number

-- addition
color + color
color + number

-- subtraction
color - color
color - number

Lua Functions¶

base

Lua Base Manual Reference

error
ipairs
next
pairs
print
select
tonumber
tostring
unpack
type

table

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

Table Pack

table.pack(...)

Returns a new sequential table created from the elements provided.

Table UnPack

table.unpack(...)

Same as the Lua base library function unpack.

math

All standard standard Lua Math Library functions are available plus the following additions:

Clamp

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.

bit32

Support for bitwise operations has been backported from Lua 5.2. All functions are available inside the table bit32.

Controls¶

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

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.

Properties And Values¶

Common

Properties

Name	Description	Since
`name`	A user-editable string.
`tag`	A user-editable string.	1.0.2.98
`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.
`cornerRadius`	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	Since
`font`	One of the possible values of the `Font` enumeration.	1.0.4.106
`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	Since
`font`	One of the possible values of the `Font` enumeration.	1.0.4.106
`textSize`	An integer value.
`textAlignH`	One of the possible values of the `AlignH` enumeration.	1.0.4.106
`textAlignV`	One of the possible values of the `AlignV` enumeration.	1.2.1.171
`textColor`	A `Color` object.
`textClip`	A boolean value.	1.2.1.171
`textWrap`	A boolean value.	1.2.1.171

Values

Name	Description
`text`	A string value.

Fader

Properties

Name	Type	Since
`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.
`gridColor`	A `Color` object.	1.2.0.166

Values

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

XY

Properties

Name	Type	Since
`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.
`gridColor`	A `Color` object.	1.2.0.166

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	Since
`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.
`gridColor`	A `Color` object.	1.2.0.166

Values

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

Encoder

Properties

Name	Type	Since
`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.
`gridColor`	A `Color` object.	1.2.0.166

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	Since
`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.
`gridColor`	A `Color` object.	1.2.0.166

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 `300`.
`tabbarDoubleTap`	A boolean value.
`tabLabels`	A boolean value.
`textSizeOff`	An integer value.
`textSizeOn`	An integer value.

Page Properties

Name	Type
`tabLabel`	A string value.
`tabColorOff`	A `Color` object.
`tabColorOn`	A `Color` object.
`textColorOff`	A `Color` object.
`textColorOn`	A `Color` object.

Values

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

Messages¶

https://hexler.net/touchosc/manual/script-objects-messages

Vectors¶

https://hexler.net/touchosc/manual/script-objects-vectors

Rectangle¶

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

Fields¶

rectangle.x

rectangle.x

The x position of the rectangle.

rectangle.y

rectangle.y

The y position of the rectangle.

rectangle.w

rectangle.w

The width of the rectangle.

rectangle.h

rectangle.h

The height of the rectangle.

Constructor functions¶

Constructor Functions

Rectangle()

function Rectangle()

returns a new rectangle with position and size set to (0,0).

Rectangle(rectangle)

function Rectangle(rectangle)

returns a new rectangle with position and size copied from another Rectangle object.

Rectangle(number, number)

function Rectangle(number, number)

returns a new rectangle with position set to (0,0) and size set to the two numbers.

Rectangle(number, number, number, number)

function Rectangle(number, number, number, number)

Returns a new rectangle object with position set to the first pair of numbers and size set to the second two numbers

Functions¶

contains(number, number)

function contains(number, number)


-- example
local r = Rectangle(10,10,50,50)
local b = r:contains(20,20)
print(b)
> true

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

Enumerations¶

AlignH

Possible values for a Control object's textAlignH property.

AlignH.LEFT
AlignH.CENTER
AlignH.RIGHT

AlignV

AlignV.TOP
AlignV.MIDDLE
AlignV.BOTTOM

ButtonType

Possible values for a Control object's buttonType property.

ButtonType.MOMENTARY
ButtonType.TOGGLE_RELEASE
ButtonType.TOGGLE_PRESS

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

CursorDisplay

CursorDisplay.ALWAYS
CursorDisplay.ACTIVE
CursorDisplay.INACTIVE

Font

since 1.0.4.106 Possible values for a Control object's font property.

Font.DEFAULT
Font.MONOSPACED

GamepadInput

since 1.1.0.132

GamepadInput.STICK_LEFT_X
GamepadInput.STICK_LEFT_Y
GamepadInput.STICK_RIGHT_X
GamepadInput.STICK_RIGHT_Y
GamepadInput.TRIGGER_LEFT
GamepadInput.TRIGGER_RIGHT
GamepadInput.BUTTON_UP
GamepadInput.BUTTON_DOWN
GamepadInput.BUTTON_LEFT
GamepadInput.BUTTON_RIGHT
GamepadInput.BUTTON_A
GamepadInput.BUTTON_B
GamepadInput.BUTTON_X
GamepadInput.BUTTON_Y
GamepadInput.BUTTON_STICK_LEFT
GamepadInput.BUTTON_STICK_RIGHT
GamepadInput.BUMPER_LEFT
GamepadInput.BUMPER_RIGHT
GamepadInput.BUTTON_START
GamepadInput.BUTTON_SELECT
GamepadInput.BUTTON_HOME

MIDIMessageType

MIDIMessageType.code_OFF
MIDIMessageType.code_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

Orientation

Possible values for a Control object's orientation property.

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

OutlineStyle

Possible values for a Control object's outlineStyle property.

OutlineStyle.FULL
OutlineStyle.CORNERS
OutlineStyle.EDGES

PointerPriority

PointerPriority.OLDEST
PointerPriority.NEWEST

PointerState

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

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

Shape

Possible values for a Control object's shape property.

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

ValueField

ValueField.CURRENT
ValueField.LAST
ValueField.DEFAULT

ValueProperty

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

ValueType

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