# TSE3 library class structure

Since TSE3 is a powerful and full-featured library it contains a large number of classes. These can be split into several categories of class.

These categories of class reside in a number of namespaces. This is described below.

### Song classes

  These are the 'data' classes in the TSE3 library. They contain the representation of the Song information. The top level class is the `Song` class, it contains all the other objects. These include `Track`, `Part` and `Phrase`.

  These are described here. They reside in the `TSE3` namespace.

### Transport classes

  These are the classes that are used to playback and record songs. This includes the following objects:

  `Transport` | Deals with the playback/redord operations
  `MidiScheduler` | Provides access to the computer's MIDI ports
  `Metronome` | Provides a configurable metronome facility
  `MidiEcho` | A software MIDI thru port
  `MidiFilter` | Configurable filter for MIDI commands

  They reside in the `TSE3` namespace.

### Instrument classes

  These classes provide the ability to read Cakewalk .ins files. See here for more information. They reside in the `TSE3::Ins` namespace.

### Utility classes

  A number of 'utilities' are provided. These are operations that are performed on `Song`s which are more complex than the basic object member functions (such as merging two `Phrase`s).

  They reside in the `TSE3::Util` namespace.

### Application classes

  A selection of classes that provide support for application programemers. The idea is to take as much of the generic (non-UI) application functionality and place it in the TSE3 library.

  They reside in the `TSE3::App` namespace.

### Command classes

  Classes that implement a 'command' design pattern. This provides application programmers with a command history facility that allows you to provide undo/redo of commands. See the Commands documentation for more details. The command classes reside in the `TSE3::Cmd` namespace.

### Listener classes

  Many of the TSE3 objects can raise events which can be caught by client code. This is described in the Notifier documentation.

  Each listener interface class resides in the namespace that it's Notifier class resides in.

# Other API issues

### Using TSE3 objects

Note that some TSE3 classes are 'value' classes, for instance `MidiClock` and `MidiCommand`. It is fine to create these on the stack, copy them etc. They 'behave like the `int`s do'.

Others must be created on the heap (i.e. via `new`), like `Part` and `Phrase`. This is because you will pass them into another object which will assume responsibility and ownership of them. This 'owner' will take care of deleting the object when it is no longer needed. If you created this object on the stack then such a delete will cause Undefined Behaviour.

Value classes are documented as such to avoid confusion.

### Using the Transport class

The `Transport` class is used to perform playback of `Song` data. To use it you must repeatedly call it's `poll()` method to allow it to perform MIDI input and output.

Perhaps you might like to call `sleep()` or some such function inbetween calls to `poll()` so as not to load your system unnecessarily.

### MIDI note off commands

The TSE3 library has a convention for where MIDI note off commands are stored. The `MidiEvent` class that is used to store MIDI data has two entries, one for the MIDI event, and a second which is used to hold a MIDI note off command if the first is a note on.

The two MIDI commands must be paired together in the one `MidiEvent` for the TSE3 playback system to work properly.

This will only be an issue to you if you are creating MIDI data using the TSE3 library. See the `PhraseEdit` class for information on how to create MIDI data.