HelpSource/Classes/MIDIdef.schelp

   1 CLASS:: MIDIdef
   2 summary:: MIDI response reference definition
   3 categories:: External Control>MIDI
   4 related:: Guides/MIDI, Classes/MIDIdef
   5
   6 DESCRIPTION::
   7 MIDIdef provides a global reference to the functionality of its superclass link::Classes/MIDIFunc::. Essentially it stores itself at a key within a global dictionary, allowing replacement at any time. Most methods are inherited from its superclass.
   8
   9 note:: Use of the older classes MIDIResponder, CCResponder, NoteOnResponder, NoteOffResponder, BendResponder, TouchResponder, and ProgramChangeResponder can be unsafe, since responders in user and class code can override each other unintentionally. MIDIdef and link::Classes/MIDIFunc:: are faster, safer, and have more logical argument order. Thus they are the recommended way of registering for incoming MIDI messages as of SC 3.5.::
  10
  11
  12 CLASSMETHODS::
  13 private:: initClass
  14
  15 METHOD:: all
  16 Get the global dictionary of all MIDIdefs.
  17
  18 returns:: An link::Classes/IdentityDictionary::.
  19
  20 METHOD:: new
  21 Create a new, enabled MIDIdef. If a MIDIdef already exists at this key, its parameters will be replaced with the ones provided (args for which nil is passed will use the old values). Normally one would use one of the message type specific convenience methods below, rather than use this method directly.
  22
  23 argument:: key
  24 The key at which to store this OSCdef in the global collection. Generally this will be a link::Classes/Symbol::.
  25
  26 argument:: func
  27 A link::Classes/Function:: or similar object which will respond to the incoming message. When evaluated for noteOn, noteOff, control, and polytouch messages it will be passed the arguments val, num, chan, and src, corresponding to the message value (e.g. velocity, control value, etc.), message number (e.g. note number), MIDI channel, and MIDI source uid. For touch, programme change and bend messages it will be passed only val, chan, and src.
  28
  29 argument:: msgNum
  30 An link::Classes/Integer:: indicating the MIDI message number (note number, control number, or programme number) for this MIDIdef. This can be an array. If nil, the MIDIdef will respond to messages of all possible message numbers.
  31
  32 argument:: chan
  33 An link::Classes/Integer:: indicating the MIDI channel number for this MIDIdef. This can be an array. If nil, the MIDIdef will respond to messages received on all channels.
  34
  35 argument:: msgType
  36 A link::Classes/Symbol:: indicating which kind of MIDI message this MIDIdef should respond to. One of code::\noteOn::, code::\noteOff::, code::\control::, code::\touch::, code::\polytouch::, code::\bend::, or code::program::.
  37
  38 argument:: srcID
  39 An link::Classes/Integer:: corresponding to the uid of the MIDI input. (See link::Classes/MIDIClient::.) If nil, the MIDIdef will respond to messages received from all sources.
  40
  41 argument:: argTemplate
  42 An optional link::Classes/Integer:: or link::Classes/Function:: (or object which responds to the method link::Overviews/Methods#matchItem::) used to match the value of an incoming MIDI message. (e.g. velocity, control value, program number, etc.). If a Function, it will be evaluated with the message value as an argument, and should return a link::Classes/Boolean:: indicating whether the message matches and this MIDIdef should respond.
  43
  44 argument:: dispatcher
  45 An optional instance of an appropriate subclass of link::Classes/AbstractDispatcher::. This can be used to allow for customised dispatching. Normally this should not be needed.
  46
  47 returns:: An instance of MIDIdef.
  48
  49 METHOD:: cc
  50 A convenience method to create a new MIDIdef which responds to MIDI control messages. See link::#*new:: for argument descriptions.
  51
  52 returns:: An instance of MIDIdef which responds to MIDI control messages.
  53
  54 METHOD:: noteOn
  55 A convenience method to create a new MIDIdef which responds to MIDI note on messages. See link::#*new:: for argument descriptions.
  56
  57 returns:: An instance of MIDIdef which responds to MIDI note on messages.
  58
  59 METHOD:: noteOff
  60 A convenience method to create a new MIDIdef which responds to MIDI note off messages. See link::#*new:: for argument descriptions.
  61
  62 returns:: An instance of MIDIdef which responds to MIDI note off messages.
  63
  64 METHOD:: polytouch
  65 A convenience method to create a new MIDIdef which responds to MIDI polytouch messages. See link::#*new:: for argument descriptions.
  66
  67 returns:: An instance of MIDIdef which responds to MIDI polytouch messages.
  68
  69 METHOD:: touch
  70 A convenience method to create a new MIDIdef which responds to MIDI touch messages. See link::#*new:: for argument descriptions.
  71
  72 returns:: An instance of MIDIdef which responds to MIDI touch messages.
  73
  74 METHOD:: bend
  75 A convenience method to create a new MIDIdef which responds to MIDI bend messages. See link::#*new:: for argument descriptions.
  76
  77 returns:: An instance of MIDIdef which responds to MIDI bend messages.
  78
  79 METHOD:: program
  80 A convenience method to create a new MIDIdef which responds to MIDI program change messages. See link::#*new:: for argument descriptions.
  81
  82 returns:: An instance of MIDIdef which responds to MIDI program change messages.
  83
  84 METHOD:: freeAll
  85 Clears and deactivates all MIDIdefs from the global collection.
  86
  87 INSTANCEMETHODS::
  88 private:: addToAll, printOn
  89
  90 METHOD:: key
  91 Get this MIDIdef's key.
  92
  93 returns:: Usually a link::Classes/Symbol::.
  94
  95 METHOD:: free
  96 Clears this MIDIdef from the global collection and deactivates it.
  97
  98
  99 EXAMPLES::
 100
 101 code::
 102 MIDIIn.connectAll
 103 MIDIdef.cc(\test1, {arg ...args; args.postln}, 1); // match cc 1
 104 MIDIdef.cc(\test2, {arg ...args; args.postln}, 1, 1); // match cc1, chan 1
 105 MIDIdef.cc(\test3, {arg ...args; args.postln}, (1..10)); // match cc 1-10
 106 MIDIdef.noteOn(\test4, {arg ...args; args.postln}); // match any noteOn
 107
 108 MIDIIn.doNoteOnAction(1, 1, 64, 64); // spoof a note on
 109 MIDIIn.doControlAction(1, 1, 1, 64); // spoof a cc
 110 MIDIIn.doControlAction(1, 1, 9, 64);
 111 MIDIIn.doControlAction(1, 10, 1, 64);
 112
 113 MIDIdef(\test1).free; // free one def
 114 MIDIdef.freeAll;      // free all registered MIDIdefs
 115 ::