Module Duplex.ControlMap
Load and parse XML based control-map files, add extra methods, handy accessors.
XML syntax:
- Supported elements are:
Row
,Column
,Group
,Param
andSubParam
- Use
Row
andColumn
nodes for controlling the layout - Only
Param
nodes are supported inside aGroup
node - Only
SubParam
nodes are supported inside aParam
node
The State
node
Define a state that the control-map can make use of (see also: Duplex.StateController) Accepts the following attributes
name
- (string) a unique name for identifying the state, and for prefixing nodes- type - (enum) "toggle", "momentary" or "trigger", determine how to respond to events
value
- (string) the incoming message that we want to match against, e.g. "C#4|Ch2".match
- (number) the exact value to match (e.g. CC number with value "5")exclusive
- (string) specify a(ny) name for states that should be mutually exclusiveinvert
- (bool) when true, trigger will light up when state is inactivereceivewheninactive
- (bool) when/if to receive/send parameter messageshidewheninactive
- (bool) when/if to show/hide parametersdisablewheninactive
- (bool) when/if to enable/disable parametersactive
- (bool) set the initial state
The Row
and Column
node
State prefixing: supported A pure layout node that accepts no attributes
The Group
node
State prefixing: supported Accepts the following attributes
name
- (string) the group name, this value is passed on to all members (Param nodes)visible
- (bool) optional, define if group should be visible or hidden (default is true)columns
- (int) optional, define how many parameters to create before creating a new rowcolorspace
- (table) if not defined, inherited from parent or deviceorientation
(enum) "horizontal" or "vertical" - determines the flow of elements
The Param
node
State prefixing: supported Accepts the following attributes
- type - (enum) lowercase version of Duplex.Globals.INPUT_TYPE, e.g.
dial
value
- (string) the pattern that we match messages against, e.g. "C#4|Ch2".action
- (string) specify this attribute to use a different output than input patternname
- (string) give the parameter a descriptive name (optional)size
- (int) the relative size of the UIComponent (2 = 200% size)aspect
- (number) the relative aspect of the UIComponent (0.5 = half height)minimum
- (number) the minimum value (e.g. to set a button to unlit state)maximum
- (number) the maxmum value (e.g. to set a button to lit state)match
- (number) the exact value to match (e.g. CC number with value "5")match_from
- (number) a value range to match (require that you also specify match_to)match_to
- (number) a value range to match (require that you also specify match_from)skip_echo
- (bool) never send message back to devicesoft_echo
- (bool) only send virtually generated messages back to deviceinvert
- (bool) swap the minimum and maximum valuesinvert_x
- (bool) for XYPad, swap the top and bottom valuesinvert_y
- (bool) for XYPad, swap the left and right valuesswap_axes
- (bool) for XYPad, swap the horizontal and vertical axesorientation
- (enum) specifies the orientation of a control - relevant for params of type=fader
text
- (string) specify the text value, relevant for params of type=label
font
- (string) specify the font type, relevant for params of type=label
range
- (int) specify the range of an on-screen keyboard (number of keys)mode
- (enum) how to interpret incoming values (see Duplex.Globals.PARAM_MODE)throttle
- (bool) whether we should throttle this parameter or not (overrides the device default)class
- (string) interpret control-map in the context of which (device) class? (default is to use the current device context, but you can enter any literal class name, e.g. "OscDevice" or "LaunchPad")
Some extra properties are added in runtime:
id
- (string) a unique, auto-generated nameindex
- (int) the index (position) within the parentGroup
nodegroup_name
- (string) this value is passed on from the parentGroup
noderow
- (int) the row within the parentGroup
column
- the column within the parentGroup
has_subparams
- (bool) true when the parameter contains additional subparametersregex_patt
- (string) preprocessed regular expression, created whenvalue
contains wildcards and/or captures
The SubParam
node
State prefixing: not supported The accepted attributes depend on the type of widget
value
- (string) the pattern that we match messages against, e.g. "C#4|Ch2" (if not specified, will use parent node)field
- (string) what aspect of the parent parameters' value that is being stored (e.g. "x" for xypad x axis)
Changes
0.99.5
- <Param @throttle> (new), enable/disable (MIDI) message throttling
0.99.3
- <Param @match> (new), match a specific (CC) value
- <Param @match_from, @match_to> (new), match a (CC) value-range
- <Param @mode> (new), specify resolution (7/14 bit) and operation (absolute/relative)
- <Param @class> (new), interpret parameter in the context of a specific device class
0.99.2
- Faster, more flexible parameter matching
- all messages are processed on startup, cached/memoized where possible
- OSC patterns now support "captures", see get_osc_params() for more info
- get_osc_params(): when using wildcards, returns table of regexp-matches
- <Param @invert> (new), allows inverting the value (flip min/max)
- <Param @soft_echo> (new) update device only when changed via virtual UI
- <Param @font> (new), specify the font type - relevant for @type=labels only
- <Param @velocity_enabled> attribute has been retired
- <Param @is_virtual> attribute has been retired, just enter a blank @value
- <Param @type="key"> widget type has been retired (use @type="button")
- <SubParam> new node type for combining several parameters into one
(finally, we can have a "proper" xypad control for MIDI devices)
- <Group @visible> (new), set to false to hide the entire group
0.99.1
- TWEAK No more need to explicitly state "is_virtual" for parameters that only
exist in the virtual UI - just leave the value attribute blank
0.98.14
- cache parameters
o Faster retrieval of MIDI parameters (put in cache once requested)
- New input method “xypad”, for creating XYPad controls in the
virtual control surface (paired-value support, however only OSC devices can
define this input method)
- new input method: “key” - for accepting note-input from
individual buttons/pads (Note: OBSOLETE)
- Control-map/virtual control surface: “keyboard” - a new input method for
representing a keyboard (the control surface will draw a series of keys)
o In the control-map, you can specify it’s range (number of keys)
- Control-map/XML parsing:
o Attribute names can now contain underscore
- Control-map/note value syntax: octave wildcard - you can now put an asterisk
in place of the octave to make mapping respond to the note only (e.g. “C-*”).
Used in the Midi-keyboard Grid Pie configuration to make navigation buttons
appear across all the black keys
0.95
- New button type: pushbutton (like togglebutton, has internal state control)
- UISlider, UIToggleButton made compatible with pushbutton (special case)
- We can now emulate sliders on the TouchOSC template (page 2)
- Nocturn and Remote will now be able to support hold/release events
- "name" attribute now optional (excluded from validation)
- "size" attribute now also applied to dials (see MPD24/32)
- Streamlined methods for detecting group size, grid mode
0.9
- First release
Functions
__init () | Initializate the ControlMap class |
load_definition (file_path, device_context) | Load_definition: load and parse xml |
_parse_definition (control_map_name, xml_string, device_context) | Parse the supplied xml string (reset the counter first) |
get_param_by_index (index, group_name) | Retrieve Param node by position within group |
get_param_by_pos (x, y, group_name) | Retrieve Param node by x/y coordinates within group |
get_params (group_name, index) | Retrieve Param nodes from group(s), supporting wildcard syntax. |
memoize () | Invoked after having loaded a new controlmap, this function will attempt to memoize as much information as possible (update osc/midi buffers etc.) |
get_midi_params (str) | Retrieve parameters with a MIDI style pattern
|
create_typemap (str_message) | generate a map containing information about each OSC message pattern-part |
get_osc_params (osc_str) | Retrieve parameters with a OSC style pattern. |
import_colorspace (str) | Parse a string into a colorspace table |
count_columns (group_name) | Count number of columns for the provided group |
count_rows (group_name) | Count number of rows for the provided group |
get_group_size (group_name) | Count number of parameters in group |
get_group_dimensions (group_name) | Get width/height of provided group |
is_grid_group (group_name) | Test if the group describe a grid group (meaning: it contains columns, and each member is a button) |
is_button (group_name, index) | Test if the parameter describes a button |
_read_file (file_path) | Internal method for reading a file into a string |
determine_type (str) | Determine the type of message (OSC/Note/CC) |
_parse_xml (str, device_context) | Parse the control-map into a table (add meta-info - such as unique ids - while parsing) |
Fields
self.groups | (table) associative array - groups by name |
self.file_path | (string) location of the control-map file |
self.patterns | (table) table of parameter patterns (key = pattern, value = list of parameters matching pattern) |
self.osc_headers | (table) table of OSC headers (like patterns, but OSC-only, and with no wildcards allowed) |
self.osc_buffer | (table) remember matched OSC patterns (key = osc_str, value = output from get_osc_params) |
self.midi_buffer | (table) remember matched MIDI patterns (key = midi_str, value = output from get_osc_params) |
self.definition | (table) parsed control-map |
self.typemaps | (table) associative array containing various parameter-patterns see create_typemap |
Functions
- __init ()
- Initializate the ControlMap class
- load_definition (file_path, device_context)
-
Load_definition: load and parse xml
Parameters:
- file_path (string), the name of the file, e.g. "my_map.xml"
- device_context (Duplex.Device) used when parsing the xml
- _parse_definition (control_map_name, xml_string, device_context)
-
Parse the supplied xml string (reset the counter first)
Parameters:
- control_map_name (string) path to XML file
- xml_string (string) the XML string
- device_context (Duplex.Device)
- get_param_by_index (index, group_name)
-
Retrieve
Param
node by position within groupParameters:
- index (int) the index/position
- group_name (string) the control-map group name
Returns:
-
(table or nil) table of attributes
- get_param_by_pos (x, y, group_name)
-
Retrieve
Param
node by x/y coordinates within groupParameters:
- x (int) the horizontal position
- y (int) the vertical position
- group_name (string) the control-map group name
Returns:
-
(table or nil) table of attributes
- get_params (group_name, index)
-
Retrieve
Param
nodes from group(s), supporting wildcard syntax.Collect the third parameter from Pad_1:
group_name="Pad_1", index=3
Collect all parameters from Pad_1
group_name="Pad_1", index=nil
Collect the third parameter from Pad1,Pad2, etc.
group_name="Pad_*", index=3
Collect every parameter from Pad1,Pad2, etc.
group_name="Pad_*", index=nil
Parameters:
- group_name (String) the control-map group name
- index (int) optional index/position
Returns:
-
(table or nil) the param attributes array
- memoize ()
- Invoked after having loaded a new controlmap, this function will attempt to memoize as much information as possible (update osc/midi buffers etc.)
- get_midi_params (str)
-
Retrieve parameters with a MIDI style pattern
CC#105|Ch1
will match bothCC#105|Ch1
andCC#105
(match values on the default channel)C#*|Ch1
will match bothC#1|Ch1
andC#5
(support for wildcard syntax)Parameters:
- str (string, control-map value attribute)
Returns:
-
table containing matched parameters
- create_typemap (str_message)
-
generate a map containing information about each OSC message pattern-part
Parameters:
- str_message split the message into non-whitespace chunks
Returns:
(table)
each part can define the following possible entries:
[int] = { text, -- (string) the raw value is_header, -- (bool) when value is the header part wildcard_pos,-- (int) position of first "*" (if any, in header text) is_capture, -- (bool) when token is surrounded by "{}" is_token, -- (bool) when "%f", "%i" or "%s" token is_string, -- (bool) when "%s" token is_float, -- (bool) when "%f" token is_integer -- (bool) when "%i" token } has_captures -- (bool) when any part contains a capture
in addition, the map will contain an entry specifying the order of each possible item that can be matched with regular expressions:
order = { [int] = { -- position of character method = [string] -- "wildcard" or "capture" type = [string] -- "%f", "%i" or "%s" } }
- get_osc_params (osc_str)
-
Retrieve parameters with a OSC style pattern.
### Match floats, integers and strings using
%f
,%i
and%s
/press 1 %i
matches/press 1 1
but not/press 1 A
### Specify wildcards using an asterisk
//pre 1 %f
matches/12/press 1 1
and/a/prefs 1 1.42
### Specify captures using curved brackets
/tilt {%f} %f {%f}
will capture the first and third numberThe method will match the action property if it's available, otherwise the
value
property (theaction
property is needed when a device transmit a different outgoing than incoming value)Parameters:
- osc_str (string), incoming OSC message
Returns:
-
(table) result of match:
{
(table), -- Param/SubParam node (table), -- resulting values (table) -- regular expression match(es) { index = [int], -- position of match chars = [string], -- matches characters method = [string], -- "wildcard" or "capture" type = [string] -- "%f", "%s" or "%i" }
}
- import_colorspace (str)
-
Parse a string into a colorspace table
Parameters:
- str (String) a comma-separated string of RGB values, e.g. "4,4,0"
Returns:
-
table
- count_columns (group_name)
-
Count number of columns for the provided group
Parameters:
- group_name
(string) the control-map group name, e.g.
Encoders
Returns:
-
int, or nil if group does not exist
- group_name
(string) the control-map group name, e.g.
- count_rows (group_name)
-
Count number of rows for the provided group
Parameters:
- group_name
(string) the control-map group name, e.g.
Encoders
Returns:
-
int, or nil if group does not exist
- group_name
(string) the control-map group name, e.g.
- get_group_size (group_name)
-
Count number of parameters in group
Parameters:
- group_name
(string) the control-map group name, e.g.
Encoders
Returns:
-
int, or nil if group does not exist
- group_name
(string) the control-map group name, e.g.
- get_group_dimensions (group_name)
-
Get width/height of provided group
Parameters:
- group_name
(String) the control-map group name, e.g.
Encoders
Returns:
- width, or nil if not matched
- height, or nil if not matched
- group_name
(String) the control-map group name, e.g.
- is_grid_group (group_name)
-
Test if the group describe a grid group
(meaning: it contains columns, and each member is a button)
Parameters:
- group_name
(String) the control-map group name, e.g.
Encoders
Returns:
-
bool
- group_name
(String) the control-map group name, e.g.
- is_button (group_name, index)
-
Test if the parameter describes a button
Parameters:
- group_name
(string) the control-map group name, e.g.
Encoders
- index (int) index within group
Returns:
-
bool, true if matched, false if not
- group_name
(string) the control-map group name, e.g.
- _read_file (file_path)
-
Internal method for reading a file into a string
Parameters:
- file_path
- determine_type (str)
-
Determine the type of message (OSC/Note/CC)
Parameters:
- str
(string), supply a control-map
value
such asC#4
Returns:
- str
(string), supply a control-map
- _parse_xml (str, device_context)
-
Parse the control-map into a table
(add meta-info - such as unique ids - while parsing)
Parameters:
- str (String) the xml string
- device_context (Duplex.Device)
Returns:
-
Table
Fields
- self.groups
- (table) associative array - groups by name
- self.file_path
- (string) location of the control-map file
- self.patterns
- (table) table of parameter patterns (key = pattern, value = list of parameters matching pattern)
- self.osc_headers
- (table) table of OSC headers (like patterns, but OSC-only, and with no wildcards allowed)
- self.osc_buffer
- (table) remember matched OSC patterns (key = osc_str, value = output from get_osc_params)
- self.midi_buffer
- (table) remember matched MIDI patterns (key = midi_str, value = output from get_osc_params)
- self.definition
- (table) parsed control-map
- self.typemaps
- (table) associative array containing various parameter-patterns see create_typemap