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.
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.
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. |
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.
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.
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:
PointerState.BEGIN
for one frame.PointerState.ACTIVE
or PointerState.MOVE
depending on whether the pointer's position has changed since the last frame.
PointerState.END
for one frame and will then be
removed from the list of pointers.
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 valueValueProperty.LOCKED_DEFAULT_CURRENT
- Default and current value locked state, a boolean valueValueProperty.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])
.
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:
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.