Class Documentation

Name:Class
Version:1.0
ID:ID_CLASS
Status:Stable
Category:System
Date:May 2001
Author:Rocklyte Systems
Copyright:  Rocklyte Systems (c) 1996-2001. All rights reserved.
Short:  The Master Class manages all classes in the Pandora Engine.



Description

The "Class" lies at the root of the system design and is responsible for managing the construction of new classes. All classes that are dynamically created within the system are represented by Class objects. If necessary, you can inspect these objects to discover detailed information about each class that has been loaded. Most of the interesting structural data can be gleaned from the Fields field.

A number of functions are available in the object kernel for the purpose of class management. The kernel maintains its own list of Class objects, which you can search by calling the FindClass() function. The CheckAction() function provides a way of checking if a particular pre-defined action is supported by a class.

Classes are almost always encapsulated by shared modules, although it is possible to create private classes inside executable programs. For information on the creation of classes, refer to the Class Development Guide for a complete run-down on class development.

Keep in mind that if you want to create an official (publicly available) class, you will need to register it with Rocklyte Systems so that its use can be promoted to other developers. To register, write to devsupport@rocklyte.com with details on the class that you want to create.

Structure

The Class object consists of the following public fields:

ActionTable  This field can be read to retrieve a Class object's internal action table.
Actions  Set this field to define the actions supported by the class.
BaseClassID  Specifies the base class ID of a Class object.
Category  Defines the category that a Class object belongs to.
Fields  Points to a field array that describes the Class' object structure.
FileDescription  Describes the file type represented by the Class.
FileExtension  Describes the file extension represented by the Class.
Flags  Optional flag settings.
Methods  Set this field to define the methods supported by the Class.
Name  The name of the Class.
OpenCount  Indicates the total amount of active objects that are linked back to the Class.
Size  The total size of the object structure represented by the Class.
SubClassID  Specifies the sub-class ID of a Class object.
TotalFields  Read this field to get the total number of fields defined by a Class.
TotalMethods  Read this field to get the total number of methods supported by a Class.
Version  The version number of the Class.
Field:ActionTable
Short:This field can be read to retrieve a Class object's internal action table.
Type:ERROR (*Routine)(OBJECTPTR Object, APTR Args)
Status:Read

This field can be read to retrieve the internal action table of a Class. The action table is arranged into a jump table of action routines, with each routine pointing directly to the object support functions. The size of the jump table is determined by the global variable, AC_END. The table is sorted by action ID, as outlined in the system/actioncodes.h include file.

You can check whether or not a particular action is supported by a Class by looking up its index within the ActionTable, for example Routine[AC_Read]. Calling an action routine directly is considered to be illegal, unless A) The call is made from an action support function in a class module and B) Special circumstances allow for such a call, as documented in the Action Support Guide.


Field:Actions
Short:Set this field to define the actions supported by the class.
Type:struct ActionArray *
Status:Init

It is common practice when developing classes to support a number of actions that help to flesh-out the Class functionality. To define the actions that your class will support, you need to create a pre-defined action list in your code, and set this field with the action specifications before the Class object is initialised.

An action list is basically a straight array of action ID's and the routines associated with each ID. When you set the Actions field, the list will be processed into a jump table that is used internally. After this process, your action list will serve no further purpose.

The following example shows an action list array taken from the Picture class:

   struct ActionArray PictureActions[] = {
      { AC_AccessObject,  PIC_AccessObject },
      { AC_Free,          PIC_Free },
      { AC_ReleaseObject, PIC_ReleaseObject },
      { AC_NewObject,     PIC_NewObject },
      { AC_Init,          PIC_Init },
      { AC_Query,         PIC_Query },
      { AC_Read,          PIC_Read },
      { AC_SaveToObject,  PIC_SaveToObject },
      { AC_Seek,          PIC_Seek },
      { AC_Write,         PIC_Write },
      { NULL, NULL }
   };

The action ID's used in this particular list can be found in the "system/actioncodes.h" include file, along with many others. Never define method ID's in an action list - please use the Methods field to define your methods.


Field:BaseClassID
Short:Specifies the base class ID of a Class object.
Type:LONG
Status:Read/Init

Before the initialisation of a Class object, this field should be set to the base class ID that the Class object represents. If there is no official ID for the class that is to be represented, this field can be left as a NULL value and the initialisation process will allocate a unique ID for you.


Field:Category
Short:Defines the category that a Class object belongs to.
Type:LONG
Prefix:CCF_
Status:Read/Init

When creating a new Class it is recommended that a suitable category is chosen and declared in this field. This will aid in the programming of abstract routines that need to understand what types of objects they are dealing with. The available categories are listed in the following table:

CategoryDescription
COMMANDCommand classes perform specific procedures, like copying or moving a file, managing assignments or executing a program.
DRAWABLEDrawable classes provide graphical areas that are designed to be drawn to.
EFFECTEffect classes draw graphics and/or play audio for non-productive demonstration purposes.
FILESYSTEM  FileSystem classes are based on file management and interaction with file based data.
GRAPHICSGraphics classes provide graphical manipulation and drawing services to developers.
GUIGUI classes are used in the development of graphical user interfaces.
IOIO classes manage hardware and software based input and output.
MISCMiscellaneous classes do not fit into any of the other available categories.
SYSTEMSystem classes are designed to provide low-level services related to system management.
TOOLTool classes are focussed on providing interactive services to the user.

If necessary, a Class can be assigned to multiple categories. You can do this by or'ing the available flags together. If you can't find a suitable category in the table, you may make a request for a new category by writing to devsupport@rocklyte.com.


Field:Fields
Short:Points to a field array that describes the Class' object structure.
Type:struct FieldArray *
Status:Read/Init

This field points to an array that describes the structural arrangement of objects generated from the given Class. If you are creating a base class then you will need to create this array yourself, while sub-classes will inherit this array from their base.

A large section of the Class Development Guide is devoted to describing how this array must be set up. Please read the guide for more information.


Field:FileDescription
Short:Describes the file type represented by the Class.
Type:STRING
Status:Read/Init

This field allows you to specify a description of the Class' file type, if the Class is designed to be file related. This setting can be important, as it helps to distinguish your Class from the other file based classes. Always make sure that your file description is short, descriptive and unique. A file description such as "JPEG" is not acceptable, but "JPEG Picture" would be appropriate.


Field:FileExtension
Short:Describes the file extension represented by the Class.
Type:STRING
Status:Read/Init

This field describes the file extension/s that your Class can recognise. Examples include:

     "iff;8svx;snd" [Sound]
     "jpg;jpeg"     [Picture]

By using the semi-colon character you can specify more than one file extension for your Class. The file extension that you prefer to save in should go at the start, e.g. in the first example any object saved will have a default filename of '<Name>.iff'. The following '8svx' and 'snd' extensions would be useful when recognising files to load.


Field:Flags
Short:Optional flag settings.
Type:LONG/FLAGS
Prefix:CLF
Status:Read/Init

Optional flag settings for a Class can be specified here. Currently available flags include:

FlagDescription
PRIVATEONLYIf this flag is set, programs will be prevented from allocating PUBLIC object types from your class. This is useful if your class has not been developed to handle public memory allocations.
PROMOTECHILDREN  If this flag is set then the fields of child objects (identified by an FD_CHILD flag in your field definitions) will be treated as if they are fields of the core object, effectively providing a level of seamless integration. This feature works with all of the object kernel's field based functions (for example, GetField() and SetFieldVariable()).
SHAREDOBJECTS  When this flag is set, all objects that are allocated from your class will automatically be converted into shared objects, even if the programmer has not requested this status.

Field:Methods
Short:Set this field to define the methods supported by the Class.
Type:struct MethodArray *
Status:Get/Set

If your Class design includes support for methods, you will need to define them by creating a method list and then setting this field with the specifications before the Class object is initialised. A method list provides information on each method's ID, name, arguments, and structure size. When you set the Methods field with your method list, the information will be processed into a jump table that is used for making method calls. After this process, your method list will serve no further purpose.

The Class Development Guide has a section devoted to describing how the method list must be set up. Please read the guide for more information.

Never use action ID's in a Methods array - please use the Actions field for this.


Field:Name
Short:The name of the Class.
Type:STRING
Status:Read/Init

This field specifies the name of a Class. Names for base classes will reflect the general purpose of a Class, e.g. the Picture Class has a name of "Picture". If you are writing a sub-class then you need to come up with an invented name, but keep it simple. For example, the JPEG sub-class would have a name of "Jpeg".

Bear in mind that sometimes the Name may be used by some programs in order to find a class when they do not know the ID.


Field:OpenCount
Short:Indicates the total amount of active objects that are linked back to the Class.
Type:LONG
Status:Read

Reading this field will reveal how many objects are currently using the Class. This figure will fluctuate over time as new objects are created and old ones are destroyed. When the OpenCount reaches zero, the system may flush the Module that the Class is related to, so long as no more programs are using it or any other classes created by the Module.


Field:Size
Short:The total size of the object structure represented by the Class.
Type:LONG
Status:Read/Init

When creating a Class, set this field to indicate the size of the objects that will be instantiated from the Class. For example, if you were responsible for maintaining the Picture class you would set this value to:

   sizeof(struct Picture)

If you do not specify the size of the object structure, the initialisation process will determine the structure size by evaluating the field definitions that were provided.


Field:SubClassID
Short:Specifies the sub-class ID of a Class object.
Type:LONG
Status:Read/Init

If you are creating a sub-class then you will need to set the SubClassID field to a unique class ID. If you have reserved an official class ID with Rocklyte Systems then you must specify it here, otherwise you can allocate a dynamic ID using the AllocateClassID() function.

If you are initialising a base class then you don't need to set this field.

If you want to determine whether or not a Class is a sub-class or a base class, grab the BaseClassID and SubClassID fields. If comparing them reveals them to be identical, then the Class is a base class. If they are different, then the Class is a sub-class.


Field:TotalFields
Short:Read this field to get the total number of fields defined by a Class.
Type:LONG
Status:Read

If you want to know how many fields are defined by a Class' object definition, read this field.


Field:TotalMethods
Short:Read this field to get the total number of methods supported by a Class.
Type:LONG
Status:Read

If you want to know how many methods are supported by a Class, read this field.


Field:Version
Short:The version number of the Class.
Type:FLOAT
Status:Read/Init

When creating a Class, this field must reflect the version of the Class structure. Legal version numbers start from 1.0 and ascend. Revision numbers can be used to indicate bug-fixes or very minor changes.

If you are writing a sub-class then you can leave this value at NULL, but base classes must set a value here.