Managing Juggler Objects

A group of Music library functions allows a task to manage Juggler objects. The library functions allow a task to initialize the Juggler, define new classes, create objects from those classes, destroy existing objects, and check an object's validity.

Initializing the Juggler

Before a task can perform any object-oriented work in the Juggler environment, including object management and playing objects with the Juggler, the task must first initialize the Juggler with the following call:

int32 InitJuggler( void )

This call accepts no arguments and, when it executes, initializes the Juggler and its object-oriented programming environment. It also defines the Juggler default classes so the task can create objects or define new classes based on the default classes.

If successful, InitJugger() returns 0. If unsuccessful, it returns an error code (a negative value).

Note that a task must call InitJuggler() before it can use any Juggler calls or play Juggler objects (including MIDI scores created as described in Playing MIDI Scores).

Creating an Object

To create an object based on an existing class, a task uses this call:

COBObject *CreateObject( COBClass *Class )

The call accepts a single argument: *Class, a pointer to the COBClass data structure containing the class definition. There are currently two classes defined in the header file juggler.h. The classes are SequenceClass and CollectionClass, which you can supply to this call as the pointers &SequenceClass and &CollectionClass.

When it executes, CreateObject() allocates memory for the object, sets up object variables and method pointers in that memory, and initializes the object variables to default values.

CreateObject() returns a pointer to the COBObject data structure defining the object if successful or a negative value (an error code) if unsuccessful. The task uses the pointer to the COBObject structure when sending messages to the object or when using other object management calls on the object.

Destroying an Object

When a task is finished with an object, it deletes the object from memory using this call:

int32 DestroyObject( COBObject *Object )

The call accepts one argument: *Object, a pointer to the object to be destroyed. When executed, the call terminates any methods the object may be executing and frees the memory used to contain the object's COBObject data structure.

DestroyObject() returns 0 if successful, or a negative value (an error code) if unsuccessful.

Checking an Object's Validity

A task must pass a pointer to an object to an object-management call or a method. If the argument does not point to an object, the results of the call are unpredictable. A task can check a pointer's validity using this call:

int32 ValidateObject( COBObject *cob )

The call accepts one argument: *cob, a pointer to an object's COBObject data structure. When the call executes, it looks in the object's data structure for an element that confirms the object's validity.

If the object is valid, ValidateObject() returns 0. Otherwise, the call returns a negative value (an error code).