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 and SubParam
  • Use Row and Column nodes for controlling the layout
  • Only Param nodes are supported inside a Group node
  • Only SubParam nodes are supported inside a Param 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 exclusive
  • invert - (bool) when true, trigger will light up when state is inactive
  • receivewheninactive - (bool) when/if to receive/send parameter messages
  • hidewheninactive - (bool) when/if to show/hide parameters
  • disablewheninactive - (bool) when/if to enable/disable parameters
  • active - (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 row
  • colorspace - (table) if not defined, inherited from parent or device
  • orientation (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 pattern
  • name - (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 device
  • soft_echo - (bool) only send virtually generated messages back to device
  • invert - (bool) swap the minimum and maximum values
  • invert_x - (bool) for XYPad, swap the top and bottom values
  • invert_y - (bool) for XYPad, swap the left and right values
  • swap_axes - (bool) for XYPad, swap the horizontal and vertical axes
  • orientation - (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 name
  • index - (int) the index (position) within the parent Group node
  • group_name - (string) this value is passed on from the parent Group node
  • row - (int) the row within the parent Group
  • column - the column within the parent Group
  • has_subparams - (bool) true when the parameter contains additional subparameters
  • regex_patt - (string) preprocessed regular expression, created when value 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

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