HelpSource/Classes/MIDIFunc.schelp

   1 CLASS:: MIDIFunc
   2 summary:: Fast Responder for incoming MIDI Messages
   3 categories:: MIDI
   4 related:: Guides/MIDI, Classes/MIDIdef
   5
   6 DESCRIPTION::
   7 MIDIFunc (and its subclass link::Classes/MIDIdef::) registers one or more functions to respond to an incoming MIDI message. Many of its methods are inherited from its superclass link::Classes/AbstractResponderFunc::.
   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. MIDIFunc and link::Classes/MIDIdef:: 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, cmdPeriod
  14
  15 METHOD:: defaultDispatchers
  16 Get or set an link::Classes/IndentityDictionary:: containing the default dispatcher objects for MIDIFuncs of different types (these are what you get if you pass nil as the dispatcher argument to link::#*new::). These objects will decide if any of their registered MIDIFuncs should respond to an incoming MIDI message. The dictionary should have the keys code::[\noteOn, \noteOff, \control, \polytouch, \touch, \program, \bend]:: and values of an appropriate subclass of link::Classes/AbstractDispatcher:: for each message type. By default these will be instances of link::Classes/MIDIMessageDispatcher:: for the the first four message types, and instances of link::Classes/MIDIMessageDispatcherNV:: for the last three.
  17
  18 returns:: The getter returns an link::Classes/IndentityDictionary::.
  19
  20 METHOD:: new
  21 Create a new, enabled MIDIFunc. Normally one would use one of the message type specific convenience methods below, rather than use this method directly.
  22
  23 argument:: func
  24 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.
  25
  26 argument:: msgNum
  27 An link::Classes/Integer:: indicating the MIDI message number (note number, control number, or programme number) for this MIDIFunc. This can be an array. If nil, the MIDIFunc will respond to messages of all possible message numbers.
  28
  29 argument:: chan
  30 An link::Classes/Integer:: indicating the MIDI channel number for this MIDIFunc. This can be an array. If nil, the MIDIFunc will respond to messages received on all channels.
  31
  32 argument:: msgType
  33 A link::Classes/Symbol:: indicating which kind of MIDI message this MIDIFunc should respond to. One of code::\noteOn::, code::\noteOff::, code::\control::, code::\touch::, code::\polytouch::, code::\bend::, or code::program::.
  34
  35 argument:: srcID
  36 An link::Classes/Integer:: corresponding to the uid of the MIDI input. (See link::Classes/MIDIClient::.)
  37
  38 argument:: dispatcher
  39 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.
  40
  41 returns:: A new instance of MIDIFunc.
  42
  43 METHOD:: cc
  44 A convience method to create a new MIDIFunc which responds to MIDI control messages. See link::#*new:: for argument descriptions.
  45
  46 returns:: A new instance of MIDIFunc which responds to MIDI control messages.
  47
  48 METHOD:: noteOn
  49 A convience method to create a new MIDIFunc which responds to MIDI note on messages. See link::#*new:: for argument descriptions.
  50
  51 returns:: A new instance of MIDIFunc which responds to MIDI note on messages.
  52
  53 METHOD:: noteOff
  54 A convience method to create a new MIDIFunc which responds to MIDI note off messages. See link::#*new:: for argument descriptions.
  55
  56 returns:: A new instance of MIDIFunc which responds to MIDI note off messages.
  57
  58 METHOD:: polytouch
  59 A convience method to create a new MIDIFunc which responds to MIDI polytouch messages. See link::#*new:: for argument descriptions.
  60
  61 returns:: A new instance of MIDIFunc which responds to MIDI polytouch messages.
  62
  63 METHOD:: touch
  64 A convience method to create a new MIDIFunc which responds to MIDI touch messages. See link::#*new:: for argument descriptions.
  65
  66 returns:: A new instance of MIDIFunc which responds to MIDI touch messages.
  67
  68 METHOD:: bend
  69 A convience method to create a new MIDIFunc which responds to MIDI bend messages. See link::#*new:: for argument descriptions.
  70
  71 returns:: A new instance of MIDIFunc which responds to MIDI bend messages.
  72
  73 METHOD:: program
  74 A convience method to create a new MIDIFunc which responds to MIDI program change messages. See link::#*new:: for argument descriptions.
  75
  76 returns:: A new instance of MIDIFunc which responds to MIDI program change messages.
  77
  78
  79 INSTANCEMETHODS::
  80 private:: init, printOn
  81
  82 METHOD:: chan
  83 Get this MIDIFunc's MIDI channel number.
  84
  85 returns:: An link::Classes/Integer::.
  86
  87 METHOD:: msgNum
  88 Get this MIDIFunc's MIDI message number.
  89
  90 returns:: An link::Classes/Integer::.
  91
  92 METHOD:: msgType
  93 Get this MIDIFunc's message type.
  94
  95 returns:: A link::Classes/Symbol::; one of code::\noteOn::, code::\noteOff::, code::\control::, code::\touch::, code::\polytouch::, code::\bend::, or code::program::.
  96
  97
  98 EXAMPLES::
  99
 100 code::
 101 MIDIIn.connectAll
 102 MIDIFunc.cc({arg ...args; args.postln}, 1); // match cc 1
 103 MIDIFunc.cc({arg ...args; args.postln}, 1, 1); // match cc1, chan 1
 104 MIDIFunc.cc({arg ...args; args.postln}, (1..10)); // match cc 1-10
 105 MIDIFunc.noteOn({arg ...args; args.postln}); // match any noteOn
 106
 107 MIDIIn.doNoteOnAction(1, 1, 64, 64); // spoof a note on
 108 MIDIIn.doControlAction(1, 1, 1, 64); // spoof a cc
 109 MIDIIn.doControlAction(1, 1, 9, 64);
 110 MIDIIn.doControlAction(1, 10, 1, 64);
 111 ::