Module Duplex.ControlMap

Load and parse XML based control-map files

Changelog

0.99.5 - (new), enable/disable (MIDI) message throttling

0.99.3 - (new), match a specific (CC) value - from, @matchto> (new), match a (CC) value-range - (new), specify resolution (7/14 bit) and operation (absolute/relative) - (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 getoscparams() for more info - getoscparams(): when using wildcards, returns table of regexp-matches - (new), allows inverting the value (flip min/max) - (new) update device only when changed via virtual UI - (new), specify the font type - relevant for @type=labels only - attribute has been retired - attribute has been retired, just enter a blank @value - widget type has been retired (use @type="button") - new node type for combining several parameters into one (finally, we can have a "proper" xypad control for MIDI devices) - (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

CC#105|Ch1 will match both CC#105|Ch1 and CC#105 (match values on the default channel)

C#*|Ch1 will match both C#1|Ch1 and C#5 (support for wildcard syntax)
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 group

Parameters:

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

Parameters:

  • 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 both CC#105|Ch1 and CC#105 (match values on the default channel)

C#*|Ch1 will match both C#1|Ch1 and C#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 number

The method will match the action property if it's available, otherwise the value property (the action 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
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
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
get_group_dimensions (group_name)
Get width/height of provided group

Parameters:

  • group_name (String) the control-map group name, e.g. Encoders

Returns:

  1. width, or nil if not matched
  2. height, or nil if not matched
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
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
_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 as C#4

Returns:

    enum (Duplex.Globals.DEVICE_MESSAGE)
_parse_xml (str, device_context)
Parse the control-map into a table (add meta-info - such as unique ids - while parsing)

Parameters:

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
generated by LDoc 1.4.2