Control IDs:

When you touch the 'Create New / ID" label, the Insert and Append checkboxes will be replaced by a textfield where you can assign an ID string to individual controls. IDs are not normally needed and TouchDAW mostly does not use any, but they become more relevant with adaptive layouts. IDs can be used with dynamic labeling (See 'Text') and to tie together hidden and shown instances of controls that are to represent 'the same thing', but need to be presented in completely different ways in landscape and portrait mode for example.

Control specific properties:

Properties are stored in xml attributes. Most controls will use a 'mode' attribute for the basic properties exposed on the Control tab. The attribute holds a numeric value that is interpreted bitwise, i.e.: the number really holds up to 32 on/off switches. The meaning of single bits may vary by control and is given in more detail below. As of version 2.4.0 the app will write 'mode' (and other bitmask values) in hexadecimal format, which can make it more easily readable. Values can still be given in decimal format, though.

Most controls will also show a little + button on the control tab that brings up a popup menu with some less frequently needed options. Here you can set controls to be disabled initially, exclude them from snapshots, etc.

A little tool to help figuring out bitset values outside of the app can be found below.

Button:

• Buttonmode: determines how and when MIDI will be sent upon touches:
  
  
  • Momentary: High value sent when pressed, low value sent on release
    
  • Single: Only the high value is sent, low value and button release are ignored.
    
  • Toggle: First press sends high value, next sends low value. Release is ignored.
    
  
  
  The 3 variants available for 'Toggle' buttons are about managing the state of a toggle switch in relation to local touch events and incoming MIDI feedback. Which one you want will depend much on the behaviour of the remote side (and in many cases you probably will not want a toggle button at all):
  
  
  • Shared: Both sides can flip the toggle's state. In this mode the button will only react to incoming 'high' values (same as it is only affected by button presses, not releases). If a button is remotely toggled it will 'report' its changed state. This mode is primarily intended for standard momentary button / LED combinations on external hard- or software.
  • Local: the toggle state is maintained in the app. The remote side can only flip it with 'opposing' data: If a toggle is on, an off event will turn it off while a high value would be ignored and vice versa.
  • Remote: the toggle state is expected to be handled and reported by the remote side. Local button presses reverse the last received state, but do not flip it internally.
  
  
  
• Excl.Group: lets you combine several pads or buttons into virtual groups out of which only one will then be selectable at a time. On pad controllers this primarily affects the pad's visual representation. A pad's button-mode setting (Momentary,..,Single) remains in effect. Buttons in exclusive groups on custom layouts will internally be set to be toggles (and hide the 'Buttonmode' control). Members of an exclusive group that were the selected will by default send their "off" state when another member of the group is selected. This can be disabled by unchecking the box next to the group dropdowns. When unselected, the group's output will directly transition between the buttons' high values and only send an off state when the selected button is explicitly untoggled.
  
  - A button's exclusive group is stored as a simple numeric index in a grp attribute on the button's xml node.
  - Group behaviors are stored as a bitmask in an xgf attribute on the top-level controller node.
  
  
• Selected: Preselects a button in an exclusive group.

Fader & Small Fader:

• Invert - Inverts the MIDI output (sends 0 when fader is up, max value when down
• Centered - Initially shows with knob at 50%. Resets to 50% on double-click.
• Allow Jumps - Move knob without directly touching it. This disables double-click resets when also 'centered'.

Pitchwheel & Crossfader:

• Same options as faders. Centered by default.

Drawbar:

• Step: Moves in eight steps and only sends MIDI when high nibble changes.
• Black: Render with a dark knob (Colors can also be individually set).

Drumpad:

• Velocity - Sets how the velocity value for outgoing MIDI is determined.
• Velocity Code - Sets a colorcode to visualize incoming velocity information (Ableton Live grid controller stuff).
• Aftertouch - Sets how the second MIDI stream is generated (actual data type does not necessarily need to be aftertouch).
• Lockable - Temporary toggle mode. Holds the pad in pressed state when released outside and only sends the off-event when touched next time. Will unset 'permanent' toggle settings under 'Button Mode'.
• Blinkable - Makes the pad listen for its assigned MIDI message on 2 more MIDI channels to trigger blink & pulse styles.

Label:

• Touchable - Sets whether the control reacts to touch (and sends MIDI vs. only receiving and visualizing it).
• Blinkable - Makes the label listen for its assigned MIDI message on 2 more MIDI channels to trigger blink & pulse styles.

Encoder:

• Invert - Inverts the MIDI output (inverting the 'direction' in endless mode)
  
• Centered - Initially shows at 50%. Resets to 50% on double-click. No effect in endless mode.
  
• Operation - Touch interaction options. 'Relative (Circular)' has no effect in endless mode.
  
• Touchable - Execute 'V-Pot Press' on every touch instead of double-tabs.
  
• Dynamic Velocity - Transmit rotation speed in endless / relative mode.
  

Jogwheel and Scrubwheel:

• Invert - Inverts the MIDI output (inverting the 'direction' in endless mode).
• Dynamic Velocity - Transmit rotation speed in endless / relative mode.
  
  
  
  Rotary controls switch between endless and linear mode depending on their MIDI settings: With a 'Control Change' (CC, 0xBn) status byte, values of 0 - 3 for the second databyte select between endless modes (see MIDI Mode). Higher values make the control 'linear' (and define the range for potentiometers).
  This only applies to MIDI 1.0 CCs! MIDI 2.0 has dedicated relative controllers and at the time being it is totally unclear how they will be used.

---

Groups

Groups are layout containers that define how individual controls inside them appear on screen. See the Style tab for details on group layout behavior. Besides plain layout groups there are some more specialized group types.

Group types are mostly changeable without loosing content. You can turn a plain group into a scrollgroup etc. and the app will transfer the groups children and attempt to set some basic attributes needed in the new context (which may fail or at least not immediately meet your requirements at points).

You can also 'turn' single controls into a group in case you realize you need more controls bundled with the first one. The result should then be a new group with the original control as its first and only child. To directly change a control into a group with different child types use the 'Change content' option.

'Change content' and 'Nr.Children' also determine how newly created groups will be prefilled and can be used to swap out all of an existing group's children. Leave the child count dropdown at its '-' entry to stick with the current number of child controls (when changing contents) or to prefill with some default value based on orientation and nesting level when creating new groups.

Tabbedgroup:

Tabbed groups create a tab for every direct child placed inside them and then show one of those tabs or pages at a time. Direct children to a tabbed group will usually be groups again, which then hold individual controls, but it is also possible to add controls directly. Default presets on the keyboard and XY-Pads screens, the 'Synth-Controls' and 'Alt-Keys' and other presets demonstrate use of tabbed groups.

Newly created tabbed groups will be prefilled with two groups each holding a placeholder label.

Tab titles can be given as a comma separated list using the 'Title' field on the 'Text' tab.
Tabbedgroups can send MIDI in relation to tab selection and will switch tabs if they receive the MIDI they are set to send.

• Tab Position - Sets how and where tab controls are rendered.

Scrollgroup:

Scrollgroups allow for horizontally or vertically scrolling parts inside a layout. They will normally hold child controls directly and have the same prefill options as plain groups. Note that scrollgroups do not limit the size of what is placed into their scrollable viewport. Faders etc. will render at their 'preferred' aspect ratios and you may need to give absolute pixel 'width' or 'height' values (instead of a relative 'weight') if you want a certain number of them to be visible at a time.

The 'MIDI Volume', 'NRPN' and 'Drawbars' and 'Sound / FX' presets show use of scrollgroups. A grid-controller sample with a vertical scrollgroup is available on the Presets page.

• Vertical - Sets scroll direction (not the layout orientation!).

Grid:

Special group that arranges its children in an evenly spaced grid. Used by the drumpad parts of the XY-Pads screen for example and featuring some conceptually related suboptions.

• Rows, Columns - Determine the grid size.
• Childtype - Prefills the grid cells on initial setup. Ignored on subsequent edits by default unless explicitly set to something other than "-".
  (Individual controls can be selected and changed at any time like in any other group.)
• Note Layout - Auto-assigns MIDI messages to the grid's children. Will show additional options like base-note, MIDI channel etc. when changed.
  Ignored on subsequent edits by default (Current layout will be kept and eventually be extended / shrunk if grid size changes)

Grids also provide an easy way to set some common parameters for all of their children: The group's color settings are not applied to the group itself but to all of its children long as they do not have individual settings (If you need to set the group's background, change the color of its parent container). You can also set a global velocity code for a grid's children on the 'Style' tab.


Sysex Group:

Custom group type dedicated to manipulating fields in sysex messages. A Sysexgroup behaves like a plain group layoutwise, but isolates its children MIDI-wise. Instead of sending directly to the output port, contained controls will change single fields of a MIDI message assigned to the group and then send out that message.

Some global properties are set on the group's 'Control' tab:

• Checksum & Data Offset - If needed, set the checksum algorithm and the byte index from where on the CRC is calculated
• Keep Address - ignore off events from fader & encoder touches and plain buttons
• Feedback Offset - gives the byte position for evtl. MIDI feedback to be shown on controls (Feedback with complex sysex has a high potential of just not really being possible with generic approaches like the one here)
• Child Feedback - Sets whether incoming CC data sets the controls inside the group (this will often make no sense)
• Eval.Feedback - If child controls are externally set they may also trigger manipulation of the group's nessage.

The MIDI attributes of child controls are used to program what field is manipulated in what way:

The first 128 fields are addressed via MIDI Control Change (CC) messages. The controller number (1st data byte) sets the field number and the changing control's value will then be written to that position. You can limit (or window) the value range in the same way it works outside the sysex-group context. If you need to address fields higher than 128, use Aftertouch (128 -255), Note On (256 - 383) or Off (384-512) messages (Also see *). All other message types will not change the sysex, but are directly routed to MIDI out.

The MIDI channel of child controls sets the 'format' of the value being placed into the sysex field(s):

1. BYTE - 7 bit values (0 - 127) placed into a single field
2. MSB_LSB = 14 bits with the Most Significant Bits (MSB) placed into the addressed field and the LSB written to address + 1
3. LSB_MSB - as before but with the Least Significant Bits (LSB) written first
4. LOW_NIB - 4 bit range (0 - 15) written to the lower nibble of the addressed position
5. HIGH_NIB - 3 bits written to the upper nibble
6. NIB_2L - writes 8 bit values spread out over the lower nibbles of the bytes at address & address+1, LSB first
7. NIB_2M - as before, but MSB first
8. NIB_3L - writes up to 12 bit values spread out over the lower nibbles of the bytes at address, address+1 & address+2, LSB first
9. NIB_3M - as before, but MSB first
10. NIB_4L - writes up to 16 bit values spread out over the lower nibbles of the bytes at address, address+1, address+2 & address+3, LSB first
11. NIB_4M - as before, but MSB first
12. MSB_LSB_SPREAD - 14 bits with the MSB placed into the addressed field and the LSB written to address + 2
13. LSB_MSB_SPREAD - as before, but LSB first
14. UMP_16 - writes up to 16 bit big endian values at address & address+1. Not compatible with MIDI 1.0 messages and MIDI 2.0 Sysex7 UMPs!
15. UMP_32 - writes up to 32 bit big endian values at address...address+3. Also not compatible with MIDI 1.0 messages and MIDI 2.0 Sysex7 UMPs!
16. BIT - sets or clears a single bit in the addressed field. This is mainly for use with toggle buttons. Set 'Data 2' to something between 0 and 6 and the button will toggle that bit in the addressed field. Becomes more interesting when multiple buttons address the same field.

To write formats that are not plain 7bit, the value range of the writing control should be adjusted to match the expected range.

There are two generic samples dealing with Roland's GS and Yamaha's XG standard available on the Workshop screen. Another visually more appealing sample that controls a Roland VM-3100 digital mixer can be downloaded from the Presets page. Even if you don't have a matching device, loading the samples, examining the controls' MIDI assignments and watching the generated messages in the MIDI monitor may help in understanding how this is supposed to work.

Sysexgroups take up to three 'midi' attributes with the first one giving the message the group is working on, the second a device specific query message and the third one an eventually different feedback nessage from the external device. Only the first message is required.

* If the sysex is shorter than the mentioned numbers, aftertouch and note messages go directly to MIDI out. This evtl. allows to place buttons etc. into the sysexgroup for layout purposes only


CI Group:

Custom group type implementing MIDI CI functionality. No further options. Group contents are built at runtime in response to property exchange communication. See the MIDI CI page for details.

---

Controls taking multiple pointers:

The following more complex controls make additional properties available through an in-control menu. They still use the 'mode' attribute, but will store things like scales and notelayouts, color schemes and sensors in additional attributes.
The runtime menus will also contain mute controls for separate CC streams if any exist. You will need them for mapping. Mutes are not stored in xml.

XY-Pad:

• Centered - Move pointer and values back to center position on release.
• Allow Jumps - If off first touch event must be close to current position or will be ignored.
• BG Sensor - Keep an evtl. active sensor running when control is hidden.
• Z-Source - Sets what feeds a pointer's third datastream (if not linked to a sensor).
  
  XY-Pads support two pointers that can (also partially) be activated by setting or disabling MIDI messages for their 8 streams.
  The first pointer can be driven by device sensors (Accelerometer, Magnetic Field and Orientation. Whether all of those will be available depends on the device). The rate at which sensordata will be delivered can be adjusted within the limits that recent Android versions put up for privacy reasons.
  Streams can individually be inverted, which will be stored in an 'inv' attribute.
  Sensor settings, inversion and (runtime) mute controls are accessible via the in-control menu.

Keyboard:

• Hide Labels - Show or hide octave root note names.
• Hide High C - Hide the next octave's root key.
• Disable Glides - Ignore key changes resulting from move events.
• Show MIDI input - Visualize incoming note events.
• Show Menu - dto. Off by default here.
• Velocity - Sets how the velocity value for outgoing MIDI is determined.
• Aftertouch - Sets message type and touch interpretation for key aftertouch.
  
  Scales, their basenote and octave-counts are accessible via the in-control menu and stored in a "kbm" attribute.

Scalepad:

• Orientation - Sets whether notes are arranged horizontally, vertically or depending on component size.
• Hide Labels - Show or hide note names.
• Show MIDI input - Visualize incoming note events.
• Velocity - Sets how the velocity value for outgoing MIDI is determined.
• Aftertouch - Sets message type and touch interpretation for key aftertouch.
  
  Scale, basenote and note-count accessible via in-control menu.

Isokeys:

• Hide Labels - Show or hide note names.
• Show MIDI input - Visualize incoming note events.
• Velocity - Sets how the velocity value for outgoing MIDI is determined.
• Aftertouch - Sets message type and touch interpretation (Y-axis) for key aftertouch.
  
  Notelayout, evtl. color scheme, scale, basenote and octave-count accessible via in-control menu.

Turmoil:

• Show MIDI input - Visualize incoming note events.
• Aftertouch - Sets aftertouch message type (always uses size / pressure for touch interpretation).
  
  Scale, basenote and note-count accessible via in-control menu.

ADSR:

• No extra properties. Mutes are always accessible on screen.

---

Utilities and hardware access:

Stepper:

Steps through a value range given by the last byte(s) of its MIDI assignment, optionally showing a list dialog when the display is touched. Displayed values can be given a comma separated list in the control's 'title' attribute, with the first (and eventually only) entry serving as the dialog title. If not text is given plain numeric values will be shown.

• No Popup: Disables the dialog option.

Dropdown:

Sends values corresponding to the selected index into its value range (given by the last byte(s) of its MIDI assignment). Entries in the dropdown list are created using text formatters. See the Control_Actions sample for an example.

PC Keyboard:

Gamepad:

Mouse:

TouchDAW 2.6 removes the global Keyboard and Gamepad mappers and instead makes HID peripherals available as controls that can be integrated into custom controllers. See the Map message type for programming them MIDI-wise.

Gamepad and Mouse have a long-click option that brings up a dialog for stream muting and inversion. Inversion is stored in an xml 'inv' attribute. Mutes are for mapping external gear and are runtime only (For a permanent 'Mute' remove an axis's MIDI assignment).

• Button mode - same as on regular buttons. Can be used to reject release events (Single) or turn hardware buttons into toggles. The app tracks toggle states for individual keyboard, mouse or gamepad buttons, but the overall setting is global per control. Only the plain variants are supported here (the 'Remote' and 'Local' ones are not).

Snapshots:

This is a readymade integrated control to take, recall and delete controller snapshots. It will paint as many buttons as it thinks will fit into the space it is given. The control is mainly thought to provide quick and easy access to the snapshot functionality. Probably not what you want to use in the end and rather to be seen as a temporary tool. See the snapshot sample available on the Workshop screen for other ways to take and recall snapshots.

Snapshots generally store a control's current value(s) in a device-side database. Controls are referred to by either ID (if given) or by index (default). The index approach is easier in that it doesn't require any further preparations, but may produce unwanted results if a layout is changed after a snapshot has been taken. Controls can be excluded from snapshots with the 'No Snapshot' option available in the '+' overflow menu for most controls.
Snapshot data is held in the database only as long as no other preset is loaded into a screen. If you want to keep snapshots of a layout, make sure to export it and use one of the 'bundle' options that will be offered when writing out the file.
Snapshot in v.2.6 are static. Crossfading between them may come in future versions.

---

Small utility for bitset attribute values:

Whenever the textfield on the right says "--default--", the attribute does not need to be given in xml at all (and TouchDAW would remove it). 0 or 0x0 can be a valid non-default value.