Class header files define the following information:

Class header files are written in 'C' language and they must include all other class header files the user might needed to use the class in question.

Below is an example class header file.

    #ifndef MY_CLASS_H
    #define MY_CLASS_H

    #include <oops/r3root.h>    /* super's class header file */
    #include <oops/r3vector.h>    /* include r3vector.h because one of our attributes needs it */
    /*
     * Class ID
     */
    #define R3CLID_MYCLASS 12345678

    /*
     * Method IDs
     */
    enum {
        MYM_DOSOMETHING = R3CL_MTHBASE(R3CLID_MYCLASS), 
	   /* Description: Do something
	    * Returns: R3INT, the number of something
	    * p1: -
	    * p2: - 
	    * p3: -
	    */
        MYM_DOSOMETHINGELSE
	   /* Description: Do something else
	    * Returns: R3INT, the number of something else
	    * p1: -
	    * p2: - 
	    * p3: -
	    */
    };

    /*
     * Attribute IDs
     */
    enum {
        MYA_Invisible = R3CL_ATTRBASE(R3CLID_MYCLASS), /* R3BOOL, invisible */
        MYA_Position  /* R3VECTOR, position in 3d space */
    };

    /*
     * Registration function
     */
    int RegisterMyClass(R3APP *app);

    #endif

Super Class

Each class header files should include all the header files one needs to use the object and the super class header file is no exception. This way the user can use any features implemented by the class without worrying about the internal structure of the class. Once the user includes your class header file, he/she should be able to use all the methods and attributes of your class, including those derived from the super classes.

Class ID

Each class is identified by a unique class id which is defined in the class header file as follows:

    #define R3CLID_MYCLASS 12345

so that the user can instance the class using the R3New() or R3ObjectCreate() functions:

    obj = R3New(R3CLID_MYCLASS,
                MYA_Invisible, FALSE,
                R3TAG_END);

100 class ids are reserved for testing purposes (R3CLID_TESTBASE ... R3CLID_TESTBASE+99). You can use these test ids as follows:

    #define R3CLID_ROTATE (R3CLID_TESTBASE + 40)

Methods

For example, 'myclass' might define new method 'MYM_PLAYSOUND' as follows:

    enum {
        MYM_PLAYSOUND = R3CL_MTHBASE(R3CLID_MYCLASS)
            /* Description: play a sound
	     * Returns: - 
	     * p1 - R3INT, volume 0 ... 100
             * p2 - R3INT, tone 0 ... 100
             * p3 - char *, file name
             */
    };

The user can then ask 'myclass' objects to perform the method by calling:

    R3DoA3(obj, R3MYM_PLAYSOUND, (void *)22, (void *)35, "mysoundfile");

Attributes

The root class (inc/oops/r3root.h) defines methods R3RM_CREATE, R3RM_SET and R3RM_GET. These methods take a tag list in 'p3' and allow the user to define and fetch attributes of objects.

For example, 'myclass' can define an attribute id:

    enum {
        MYA_Invisible = R3CL_ATTRBASE(R3CLID_MYCLASS) /* R3BOOL */
    };

in which case the user can create an invisible object by calling:

    /* create new object */
    obj = R3New(R3CLID_MYCLASS,
                MYA_Invisible, TRUE,
                R3TAG_END);

Or make any 'myclass' object invisible by calling:

    R3SetAttrs(obj,
               R3MYA_Invisible, TRUE,
               R3TAG_END);    

To find out if the object is invisible:

    /* see if the object is really invisible */
    R3GetAttrs(obj,
               MYA_Invisible, &invisible,
               R3TAG_END);
    if(invisible) {
        ....
    }

Registration Function

One must be able to link a class in a plugin to an application. This is accomplished through a class registration function.

This should be the only global (external) function your plug-in defines and its prototype should be included with the class header files as follows:

    int RegisterMyClass(R3APP *app);

And finally the entire header file should be enclosed within #ifdef and #endif directives:

    #ifndef MY_CLASS_H
    #define MY_CLASS_H

    ....

    #endif