GUI Notifiers

Notifiers are helper objects very useful in graphics interfaces.

If you want to implement your GUI interacting with the library classes you will probably want it to be responsive: if, while playing a MIDI song, a parameter (tempo, time signature, a track program) changes the GUI should immediately show it. So the library implements notifiers, i.e. objects which communicates between the sequencer classes and the GUI,sending real time messages when something happens in the sequencer.

The MIDISequencerGUIEvent class

The MIDISequencerGUIEvent packs into a single unsigned long data that represents a GUI event, i.e. "something that is happened in the sequencer". Events have three attributes: group, subgroup and item, according to the following table:

Group	Subgroup	Item	Meaning
GROUP_ALL	Not used	GROUP_ALL_ALL	General refresh of the GUI (for example when a file is loaded or when you jump from a time to another)
GROUP_CONDUCTOR	Not used
		GROUP_CONDUCTOR_TEMPO	A tempo change
		GROUP_CONDUCTOR_TIMESIG	A time signature change
		GROUP_CONDUCTOR_KEYSIG	A key signature change
		GROUP_CONDUCTOR_MARKER	A text marker
		GROUP_CONDUCTOR_USER	User defined conductor event
GROUP_TRANSPORT	Not used
		GROUP_TRANSPORT_START	Start of the sequencer
		GROUP_TRANSPORT_STOP	Stop of the sequencer
		GROUP_TRANSPORT_MEASURE	New measure
		GROUP_TRANSPORT_BEAT	New metronome beat
		GROUP_TRANSPORT_USER	User defined transport event
GROUP_TRACK	The track number
		GROUP_TRACK_NAME	Track name text event
		GROUP_TRACK_PROGRAM	Program change
		GROUP_TRACK_NOTE	Note
		GROUP_TRACK_VOLUME	Volume control change
		GROUP_TRACK_PAN	Pan control change
		GROUP_TRACK_CHR	Chorus control change
		GROUP_TRACK_REV	Reverb control change
		GROUP_TRACK_USER	User defined track event
GROUP_RECORDER	Not used
		GROUP_RECORDER_RESET	Recorder reset
		GROUP_RECORDER_START	Recording start
		GROUP_RECORDER_STOP	Recording stop
		GROUP_RECORDER_USER	User defined recorder event
GROUP_USER	Not used	GROUP_USER_USER	User defined user event

The GROUP_TRACK has a subgroup which represents the track number in which the event is happened (while other groups don't use the subgroup). The various item attributes have USER values that you can use for your own purposes (and can be extended with, for example, GROUP_CONDUCTOR_USER + 1, GROUP_CONDUCTOR_USER + 2, etc.).

When the GUI receives a message, it can examine it and know what is happened; messages do not contain the values of the changed parameters, but these can be asked to the sequencer by its get methods, allowing therefore to refresh the GUI.

The MIDISequencerGuINotifier class

The MIDISequencerGUINotifier is an abstract class which has a pure virtual method MIDISequencerGUINotifier::Notify(): this takes as parameter a MIDISequencerGUIEvent and sends it to the GUI. The class is abstract because the effective sending depends by the OS (in a GUI it is typically a communication between separate processes or windows). The library implements two working subclasses of the base class: the MIDISequencerGUINotifierText which prints readable messages to a std::ostream and the MIDISequencerGUINotifierWin32 for MS Windows: this communicates with a window by mean of the Windows API PostMessage() function.

When you want to use a notifier together with a sequencer you must first create the notifier and then pass its pointer as a parameter in the sequencer constructor (see MIDISequencer::MIDISequencer and AdvancedSequencer::AdvancedSequencer). For example:

#include "notifier.h"
#include "advancedsequencer.h"
#include "timer.h"
 
int main() {
   MIDISequencerGUINotifierText notifier;
   AdvancedSequencer sequencer(&notifier);
   seq.Load("twinlkle.mid");
   seq.Play();
   while (seq.IsPlaying())
      MIDITimer::Wait(10);
}

This simple example outputs to stdout a description of every event which happens in the sequencer. In the following files you can see more elaborated examples of the typical usage of the notifier classes:

• test_stepsequencer.cpp (text notifier)
• test_win32_player.cpp (Windows notifier)