MKtlDesc | SuperCollider 3.13.0 Help

Description

MKtlDesc can read description files for hardware interface devices into MKtlDesc instances. Usually, this happens automatically when an MKtl is instantiated.

NOTE: The file syntax can be found at MKtl_description_files, element description keys can be found at Naming_conventions_in_element_descriptions.

Some examples:

Which devices are supported by Modality? Look at the webpage:MKtlDesc.web; // SC-internal webView MKtlDesc.docURI.openOS; // open in browser

Folders:MKtlDesc.defaultFolder; // where modality puts descriptions MKtlDesc.userFolder; // where user can put personalized descriptions MKtlDesc.addFolder("~/Desktop/"); // Add custom folders if desired MKtlDesc.descFolders; // which show up here MKtlDesc.openFolder(0); // open by index, 0 is defaultFolder, 1 is userFolder MKtlDesc.openFolder(1);

Loading:MKtlDesc.loadDescs; // load all description files MKtlDesc.loadDescs("*nano*"); // or matching ones MKtlDesc.loadDescs("nano*", folderIndex: 0); // in specific places

Global inspection:MKtlDesc.allDescs; // all currently loaded descs MKtlDesc('korg-nanokey2').dump; // look at one MKtlDesc('korg-nanokey2').web; // open its web documentation

Make an MKtlDesc from a desc filenamex = MKtl/Desc.fromFileName("korg-nanokontrol2"); x.openFile; // open its file x.fullDesc // the dict that contains all the info x.fullDesc.keys; // the description items: x.protocol; // one of [\midi, \hid, \osc]; x.idInfo.postcs; // the device name under which it registers in the OS x.fullDesc[\testCode].cs; // optional testCode, wrapped into a function x.elementsDesc; // the hierarchical description of the elements x.elAt(\sl); // access single elements or groups by name or index x.elAt(\sl, 0); // access elements by name or index x.elementsDict.keys; x.postInfo; // post overview info x.postInfo(postElements: true); // and the elements too x.postElements; // generate default test code for a desc name: MKtlDesc.defaultTestCode("korg-nanokontrol"); MKtlDesc("*nanokontrol").testCode; // in its own document for quick testing MKtlDesc("*nanokontrol").openTestCode; // nanokontrol2 has specific testCode in the desc itself d = MKtlDesc("*nanokontrol2"); d.fullDesc[\testCode]; d.testCode;

Class Methods

.defaultFolder

the path where the folder for MKtlDesc files lives.

.userFolder

the path where users can put personalized MKtlDesc files.

.folderName

the name of the defaultFolder and userFolder.

.descFolders

all descFolders within which to look for MKtlDesc files.

.addFolder

add a folder to descFolders

.openFolder

open folder(s) in descFolders by index.

.loadDescs

load matching descriptions in descFolders.

.allDescs

dict of all currently loaded descs

.postStatus

post status and name of all loaded descsMKtlDesc.postStatus;

.postLoadable

post the filenames of descs that can be loadedMKtlDesc.postLoadable;

.postLoaded

post currently loaded descsMKtlDesc.postLoaded;

.descKeysUsed

collect all element keys used in loaded descsMKtlDesc.descKeysUsed;

.deviceTypesUsed

collect all device types used in loaded descsMKtlDesc.deviceTypesUsed;

.elementTypesUsed

collect all element types used in loaded descsMKtlDesc.elementTypesUsed;

.notePair

make a pair of noteOn, noteOff elementsMKtlDesc.notePair(\padL, 13);

.notePairs

make pairs for a list of key, note pairsMKtlDesc.notePairs([[\padL, 13], [\padL, 21]]).printAll;

.isValidDescDict

check whether dict is a valid description dict.

.new

create an MKtlDesc with a name, from a well-formed description file.

.at

access an MKtlDesc by name in the global repository

.fromFileName

create an MKtlDesc from a file.

Arguments:

filename	filename without path or extension, will be looked for in descfolders.
folderIndex	in which folder of descFolders to search the file
multi	flag whether to load multiple matching files

.fromDict

create an MKtlDesc from a well-formed description dict.

.findFile

find the filepath for a given desc name.

.fromPath

create an MKtlDesc from a full file path.

.web

get info for an MKtlDesc on the webMKtlDesc.web; MKtlDesc("*manta").web; MKtlDesc.webview;

internal methods

.compExt

.descExt

legal extensions for filenames

.fileToIDDict

a dictionary that contains the idInfos for every desc file

.idInfoForFilename

find device idInfo for given filename

.filenamesForIDInfo

find filenames for a given device idInfo

.writeCache

.cacheName

.loadCache

.updateCache

support methods for cache of filenames and idInfos

.platformSpecific

Set false to disable platform specific replacements.

NOTE: This will break standard MKtl functionality and is only needed for rendering documentation!

Instance Methods

.idInfo

get the string by which the hardware device registers to the OS.

.protocol

get and set the hardware protocol of the device.

.deviceFilename

get the filename of the desc file

.testCode

returns code to test a controller with this description.

.openTestCode

Opens a Document with code to test a controller with this description.

.fullDesc

get MKtlDesc's properties, or set them from a dict fullDesc.elementsDesc contains the description of all elements

.elementsDesc

the hierarchical dict that contains the description of all elements

.elAt

access element descriptions hierarchically

.elementsDict

the flat dict that contains descriptions of all elements by compound lookup name

.dictAt

access element descriptions by compound hierarchic lookup name

.web

open a webview on the device's info page at Modality website.

.openFile

open the desc file from which the MKtlDesc was generated

.postInfo

post info on the device, if postElements = true, also info on the elements

.postElements

post info on the elements

.path

the path where file was read (if so)

.writeFile

not done yet - should eventually write a well-formed description file at path based on its current data.

Examples

// matching with generic desc files is done automatically now.

// still, here an example for matching with a generic desc by hand:
d = MKtlDesc.loadDescs("generic-mouse").first;
m = MKtl.find(\hid);
// we found an optical mouse with an hid ID, so make an MKtl,
m = MKtl('m', 'hid_5_usb_optical_mouse');

// generic-mouse desc matches, no extra elements on either side
d.matchWithHID(m.device.source);

// -> this should happen automatically when no desc is found.
// to test matching:
// remove middle button in desc -> now elements remain onlyInDesc
d.elementsDict.removeAt(\bt_middle);
d.matchWithHID(m.device.source);
// remove hid elem 5 in HID -> now elements remain onlyInHID as well
m.device.source.elements.removeAt(5);
d.matchWithHID(m.device.source);

/********** TESTS ********/
// groupType expansion:

a = (midiNum: 12, style: (width: 0.5, height: 2));

// call funcs directly
MKtlDesc.groupFuncs['noteOnTrig'].value(a);
MKtlDesc.groupFuncs['noteOnVel'].value(a);

MKtlDesc.groupFuncs['noteOnOff'].value(a);
MKtlDesc.groupFuncs['noteOnOffBut'].value(());
MKtlDesc.groupFuncs['noteOnOffVel'].value(());

MKtlDesc.groupFuncs['noteOnOffCtl'].value(());
MKtlDesc.groupFuncs['noteOnOffTouch'].value(());
MKtlDesc.groupFuncs['noteOnOffVelTouch'].value(());

// lookup as it happens in deepExpand
MKtlDesc.expandElemToGroup(a, 'noteOnOff');

// tests for deepExpand:

~groupType = \noteOnTrig;
~groupType = \noteOnVel;

~elems = MKtlDesc.deepExpand(
    (key: \pad,
        elements: (48..51).collect { |num, i|
            ( midiNum: num, groupType: ~groupType,
                style: (row: i % 4, column: i div: 4) )
        }
    )
).printAll; "";
~elems.collect(_.elements).flat.size; // 4

// these expand to two each
~groupType = 'noteOnOff';
~groupType = 'noteOnOffBut';
~groupType = 'noteOnOffVel';

// these expand to three each
~groupType = 'noteOnOffCtl';
~groupType = 'noteOnOffTouch';
~groupType = 'noteOnOffVelTouch';

helpfile source: Modality/HelpSource/Classes/MKtlDesc.schelp
link::Modality-toolkit/Modality/HelpSource/Classes/MKtlDesc::

MKtlDescExtension

Description

Class Methods

.defaultFolder

.userFolder

.folderName

.descFolders

.addFolder

.openFolder

.loadDescs

.allDescs

.postStatus

.postLoadable

.postLoaded

.descKeysUsed

.deviceTypesUsed

.elementTypesUsed

.notePair

.notePairs

.isValidDescDict

.new

.at

.fromFileName

Arguments:

.fromDict

.findFile

.fromPath

.web

internal methods

.compExt

.descExt

.fileToIDDict

.idInfoForFilename

.filenamesForIDInfo

.writeCache

.cacheName

.loadCache

.updateCache

.platformSpecific

Instance Methods

.idInfo

.protocol

.deviceFilename

.testCode

.openTestCode

.fullDesc

.elementsDesc

.elAt

.elementsDict

.dictAt

.web

.openFile

.postInfo

.postElements

.path

.writeFile

Examples

MKtlDesc
Extension