HelpSource/Classes/AbstractDispatcher.schelp

   1 CLASS:: AbstractDispatcher
   2 summary:: Dispatches incoming messages to Functions
   3 categories:: OpenSoundControl, MIDI
   4 related:: Classes/AbstractWrappingDispatcher, Classes/OSCMessageDispatcher, Classes/OSCMessagePatternDispatcher, Classes/MIDIMessageDispatcher, Classes/OSCFunc, Classes/OSCdef, Classes/MIDIFunc, Classes/MIDIdef, Classes/AbstractResponderFunc
   5
   6 DESCRIPTION::
   7 Instances of AbstractDispatcher dispatch incoming messages (e.g. MIDI, OSC), to registered instances of link::Classes/AbstractResponderFunc::. There will be a default dispatcher for each message type, but one can have multiple dispatchers per type in order to implement custom dispatching for groups of ResponderFuncs. (The main example of this is OSC pattern matching with link::Classes/OSCMessagePatternDispatcher::.) Normally users do not need to access dispatcher instances directly.
   8
   9 Dispatchers must be registered at the appropriate central point (e.g. Main:recvOSCfunc for OSC messages). In this capacity their interfaces mimic link::Classes/Function:: and link::Classes/FunctionList::.
  10
  11
  12 CLASSMETHODS::
  13 private:: initClass
  14
  15 METHOD:: all
  16 Get a collection of all currently active dispatchers.
  17
  18 returns:: An link::Classes/IdentitySet::.
  19
  20 METHOD:: new
  21 Make a new dispatcher.
  22
  23 returns:: A new instance.
  24
  25
  26 INSTANCEMETHODS::
  27 private:: init
  28
  29 METHOD:: add
  30 Add a responder func to this dispatcher. Subclasses should override this to do any necessary bookkeeping. Generally this method should add this dispatcher as a dependant of the responder func, so that it can respond to any changes.
  31
  32 argument:: funcProxy
  33 An instance of a subclass of link::Classes/AbstractResponderFunc:: to add.
  34
  35 METHOD:: remove
  36 Remove a responder func from this dispatcher.
  37
  38 argument:: funcProxy
  39 An instance of a subclass of link::Classes/AbstractResponderFunc:: to remove.
  40
  41 METHOD:: value
  42 Evaluate an incoming message to see if it matches. Subclasses should override this message to take appropriate arguments. If a matching responder func is found, this method should call value on it, passing the message.
  43
  44 METHOD:: valueArray
  45 As link::#-value:: above, but with the arguments passed as a single link::Classes/Array::. This method is needed so that subclasses can work in FunctionLists in central message registration points such as Main:recvOSCMessage.
  46
  47 argument:: args
  48 An link::Classes/Array:: containing the message and appropriate arguments.
  49
  50 METHOD:: register
  51 Register this dispatcher at the appropriate central point (e.g. Main:recvOSCfunc) to receive its message type. Subclasses should take care to not override any other registered objects. (So for example use Main:addOSCFunc for OSC messages rather than Main:recvOSCfunc_.) Generally speaking, dispatchers should register themselves automatically if needed when a responder func is added.
  52
  53 METHOD:: unregister
  54 Remove this dispatcher from the appropriate central registration point, i.e. deactivate it. Generally speaking a dispatcher should unregister itself automatically when its last responder func is removed.
  55
  56 METHOD:: free
  57 link::#-unregister:: this dispatcher and remove it from link::#*all::. After this the dispatcher should be discarded.
  58
  59 METHOD:: typeKey
  60 Subclasses should override this method to return a key indicating the type of message this dispatcher responds to, e.g. code::'OSC matched':: or code::'MIDI control'::.
  61
  62 returns:: A link::Classes/Symbol::.
  63
  64 METHOD:: update
  65 Subclasses should override this to do any necessary updating when a dispatchers responder funcs indicate they have changed via the standard dependancy mechanism. The default implementation does nothing.
  66