jMusic Tools and Utilities

Like many software projects, jMusic has some core and some additional elements
. As you work more with jMusic the structure of these elements will become more clear and also (hopefully) the reasons why jMusic is structured in
this way will be clearer. A rough guide to the jMusic hierarchy of classes can be seen in the package structure

. If you have downloaded the source code simply open the jMusic directory and see how the classes are arranged into a directory tree.
(The jm directory may be consolidated as a jm.jar file, if so, download the source files to see the directory organisation within the jm directory. But this is not necessary to use the tools so don't get fazed if you don't have the source.)

To use the data or tool classes you need, at the top of your Java file, to import the appropriate directories:

import jm.music.data.*;
import jm.music.tools.*;
import jm.music.util.*;

Guess which package has all the tools, which one has all the utilities and which one has all the musical data (Note, Phrase, Part, Score etc.).

This tutorial will introduce you to the organisation of classes close to the heart of jMusic, the arrangement of data, tools and utilities,
and how you can use these most effectively.

Data

At the core of jMusic is the jmusic/src/jm/music directory. In particular the data classes, Score, Part, Phrase, CPhrase, and Note,
which hopefully you know intimately - or will. These data classes contain all the musical 'content' for jMusic and also many methods for creating
or reporting on that data.

The manipulation of the music content is performed by tools in the jm.music.tools directory, such as the Mod.transpose() and Mod.repeat() methods.
As you develop jMusic pieces you may write a generally useful class which can be included in the tools directory for others to utilise.
The AdaptiveMatrix class is one such tool that is a generalised Markov matrix generator.

Anyway, on with the show. At the data level the data objects 'set' themselves via their methods and we use tool classes, such as Mod to transform them. So in the case of part.setTitle("Fred"); the title (name) of the part is set to Fred. In the case of Mod.repeat(2); the phrase is changed by adding extra notes
to it so that it plays two more times through.

Utilities

In order to communicate with the outside world a set of utility classes have been created. Communicating, in this context, includes displaying a score on
screen, writing a score to a file, inputting a phrase as notation, reading a MIDI file, and so on.
Utilities communicate with the data structure, rather than transform it.
Of course in practice this is a blurry distinction, but a helpful one when you're getting started and want a clear explanation :)

At the utility level the data objects are 'translated' from (or to, in the case of Read) an i/o device (screen, hard disk).
The data objects are not necessarily changed.
For example, the View methods translate the data into visualisations and the Write methods translate the data into file formats.
Because the util methods use the jMusic data, a data object (usually a score) is passed as an argument, as in: Write.midi(score, "FileName.mid");

Your Classes

In the classes that you write you can use any of the data, tools or utility classes.
You can directly access the data and tool classes, and you can get particular interpretations of the data as viewed through the various utility classes.
The rule of thumb is, if you want to 'manipulate' the data then access the data classes and methods directly and if you want to 'render' the data so you
can see it, or hear it, or store it, then use the util classes.

Hopefully, this is more straight forward in practice than this long-winded explanation! Below is a summary of the functions performed by the util
classes, HelperGUI, Read, Write, View, and Play. As always, this tutorial scratches the surface, and you should check the documentation and
look at the source to get a more up-to-date and complete understanding of the util functionality.

HelperGUI

The Helper GUI provides a visual interface that accesses many of the other jMusic unitilies mentioned below.
It can be used by simply having your class extend the HelperGUI class and adding a compose() method.