Naming conventions in element descriptions

Extension

A single element description is a dictionary of type Event. It (or the shared properties of its group) should contain these keys:

generic keys

elementType

User-readable name for the physical type of thing. Usually one of the many types inMKtlElement.types; // [\button, \slider, \joyAxis, ...]

Example:( elementType: \slider )

ioType

whether and how it is an input and/or output element. Usually one ofMKtl.ioTypes; // [\in, \out, \inout, \collectiveIn, ...]; // or soon to be: // [\in, \out, \inout, \sharedIn, \sharedOut, \sharedInOut];

Example:( ioType: \inout )

spec

a spec for the internal number range of the device; e.g. for midi controls, \midiCC is [0, 127, \lin, 1, 0].asSpec;

This gives an overview of some predefined specs:Spec.specs; MKtl.globalSpecs.keys;

Example:spec: \midiCC, // e.g. hid buttons send values of 0 or 1: spec: \hidBut, // or just spec: \but,

valueType

Either \absolute or \relative.

\absolute

this is what most elements send, e.g. fader position, so it is the default valueType.

\relative

means the element sends a delta value, i.e. by how much to change whatever it is currently setting. HID mouse devices send deltaX and deltY values, MIDI encoder knobs send how many clicks one has turned, or custom increment/decrement buttons. In this case, the element's value is simply the last delta value, and there is no current absolute value in the element - the object that is being set knows its absolute value. The RelSet class can be used in the element.action to change the current value of the destination object by a delta. See RelSet

Example:( valueType: \absolute, // this is default and need not be given. valueType: \relative )

buttonMode

Determines how buttons behave:

\toggle

triggers action on release only for toggle buttons

\momentary

triggers action on push and release, so value is active only while holding down on MKtlGUIs. The mode can be changed by clicking on the button view and typing 't' or 'm'.

Example:( buttonMode: \toggle ); // or ( buttonMode: \momentary )

releaseMode and snapbackValue

Many physical elements, e.g. faders and joystick axes have one of several behaviors when they are released. \releaseMode describes which behavior the element has.

\hold

means the value is held where it is (e.g. most faders)

\snapback

means it physically returns to a known value, which is then given via \snapbackValue.

Example:( releaseMode: \hold ); // simple fader // joystick axes with springs that return them to center: ( releaseMode: \snapback, snapbackValue: 0.5 )

Protocol-specific keys

MIDI device elements

MIDI device elements require these keys:( // one of MIDIMKtlDevice.allMsgTypes; midiMsgType: \control, // which channel to listen to and/or send on midiChan: 0, // for note/cc specific controls like noteOn, noteOff, cc, polyTouch: // which noteNum, ccNum to use midiNum: 60, )

HID device elements

HID device elements require these keys:( // which 'usage' and 'usagePage' to listen to 'hidUsage': 5, 'hidUsagePage': 9, // if the HID's firmware is flaky, // one also can define by an elementID 'hidElementID': 0, )

OSC device elements

OSC device elements require these keys:( // the osc message the element listens to: oscPath: "/minibee/imu", // if multiple elements use the same message name, // address this one via argTemplate: argTemplate: [ 1, 2 ] );

\argTemplate is further described in How_to_create_a_description_file_for_OSC.