oop
Index
Classes are objects of metaclasses, so therefore
classes are created with OOP_NewObject().
As of now there are three different metaclasses available:
mimetaclass (CLID_MIMeta)
- Creates classes that supports multiple interfaces.
simetaclass (CLID_SIMeta)
- Creates classes that can only support single interfaces. Advantage is faster
method invocation (doesn't require hashing).
How to create a class is best shown through an example.
Here is a Timer class with two simple methods,
Start and Stop.
Note, this example doesn't show the New and Dispose
methods and OOP_DoSuperMethod() usage, but it is exactly the same as in BOOPSI,
so those familiar with BOOPSI, should find creating classes with this system simple.
// In the classes' include file you have to define class ID, interface ID
// method offsets and attribute offset
#define CLID_Timer "timerclass"
#define IID_Timer "I_timer"
// Method offset for methods in the IID_Timer interface.
enum
{
moTimer_Start = 0,
moTimer_Stop,
Num_Timer_Methods // number of methods in the Timer interface
};
// Attribute offsets for attrs in the IID_Timer interface.
enum
{
aoTimer_Elapsed = 0,
Num_Timer_Attrs // number of attrs in the timer interface
};
// private instance data
struct timer_data
{
struct timeval start_time;
struct timeval elapsed_time;
};
// The methods
static VOID timer_start(Class *cl, Object *o, Msg msg)
{
struct timer_data *data;
data = INST_DATA(tcl, o);
gettimeofday(&(data->start_time), NULL);
return;
}
static VOID timer_stop(Class *cl, Object *o, Msg msg)
{
struct timer_data *data = INST_DATA(tcl, o);
gettimeofday(&(data->elapsed_time), NULL);
SubTime(&(data->elapsed_time), &(data->start_time));
return;
}
#define NUM_TIMER_METHODS 2
Class *make_timerclass()
{
struct MethodDescr methods[NUM_TIMER_METHODS + 1] =
{
{(IPTR (*)())timer_start, moTimer_Start},
{(IPTR (*)())timer_stop, moTimer_Stop},
{NULL, 0UL} // must be null-terminated
};
struct InterfaceDescr ifdescr[] =
{
{ methods, "Timer", NUM_TIMER_METHODS },
{ NULL, 0UL, 0UL} // must be null-terminated
};
struct TagItem tags[] =
{
{aMeta_SuperID, (IPTR)CLID_Root},
{aMeta_InterfaceDescr, (IPTR)ifdescr},
{aMeta_ID, (IPTR)CLID_Timer},
{aMeta_InstSize, (IPTR)sizeof (struct timer_data)},
{TAG_DONE, 0UL}
};
Class *tcl;
// Make it a class of the SIMeta
tcl = (Class *)OOP_NewObject(NULL, CLID_SIMeta, tags);
if (tcl)
{
// Make the class public
OOP_AddClass(tcl);
}
return tcl;
}
VOID free_timerclass(Class *cl)
{
OOP_DisposeObject((Object *)cl);
return;
}
Root class is the base class of all classes.
One can create new baseclasses, but all classes must implement the root interface.
This section describes the recommented convention for naming attributes and methods.
Method and attribute offsets are constructed like this:
method offset:
mo<interface>_<method name> (eg. moTimer_Start)
attribute offset:
ao<interface>_<attrname> (eg. aoTimer_Elapsed)
or moHidd_GC_SetPixel and aoHidd_GC_FgPen
Macro specifying class ID is defined like this:
CLID_<system>_<class name> (eg. CLID_Hidd_Gfx )
And interface IDs like this.
IID_<system>_<interface name> (eg. IID_Hidd_Gfx )
ID themselves are strings.
Specifies the class ID for the class.
Size of the instance data for this class.
Note, this is not necessarily the same as the size of the whole
object of this class.
[I..], struct InterfaceDescr *
Pointer to an array of interface descriptors (struct InterfaceDescr).
This array has to be null-terminated.
Each
struct InterfaceDescr
{
struct MethodDescr *MethodTable;
CONST_STRPTR InterfaceID;
ULONG NumMethods;
};
describes an interface of the class.
The MethodTable is an array of
struct MethodDescr
{
IPTR (*MethodFunc)();
ULONG MethodIdx;
};
which describes each method's implementation.
struct MethodDescr root_mdescr[NUM_ROOT_METHODS + 1] =
{
{ (IPTR (*)())unixio_new, moRoot_New },
{ (IPTR (*)())unixio_dispose, moRoot_Dispose },
{ NULL, 0UL }
};
struct MethodDescr unixio_mdescr[NUM_UNIXIO_METHODS + 1] =
{
{ (IPTR (*)())unixio_wait, moHidd_UnixIO_Wait },
{ NULL, 0UL }
};
struct InterfaceDescr ifdescr[] =
{
{root_mdescr, IID_Root, NUM_ROOT_METHODS},
{unixio_mdescr, IID_UnixIO, NUM_UNIXIO_METHODS},
{NULL, NULL, 0UL}
};
struct TagItem tags[] =
{
{aMeta_SuperID, (IPTR)CLID_Hidd},
{aMeta_InterfaceDescr, (IPTR)ifdescr},
{aMeta_ID, (IPTR)CLID_UnixIO_Hidd},
{aMeta_InstSize, (IPTR)sizeof (struct UnixIOData) },
{TAG_DONE, 0UL}
};
...
cl = NewObjectA(NULL, CLID_HIDDMeta, tags);
InterfaceDescr->NumMethods field was originally intended to specify
size of internal method table. When creating a new interface (i. e.
if this is your own interface), you need to be sure that the value
you set there is equal to highest possible method number + 1.
Since v42.1 oop.library always ensures that methods table has enough
entries to accomodate all defined methods. NumMethods field in interface
descriptor is effectively ignored and is present only for backwards
compatibility.
ID of public class that will be superclass of class to be created.
Pointer to private class that will be superclass to
class created.
See OOP_DisposeObject() doc.
Used internally to dispose of an object previously
created using the moRoot_New method.
OOP_GetAttr(OOP_Object *object, ULONG attrID, IPTR *storage);
Get the value for an object attribute.
The attribute value will be stored in *storage.
..
ULONG num_members;
OOP_GetAttr(list, aList_NumMembers, &num_members);
Creates a new object of some class. Class users should use OOP_NewObject() to
create an object.
OOP_SetAttrs() (OOP_Object *object, struct TagItem *attrs);
Set an attribute of an object.
VOID OOP_AddClass(
OOP_Class * classPtr );
Adds a class to the public list of classes.
This means that any process can create objects of this
class.
classPtr - Pointer to the class to make public.
Would be faster to use a hashtable to look up class IDs
VOID OOP_DisposeObject(
OOP_Object * obj );
Delete an object that was previously allocated with OOP_NewObject().
obj - pointer to object to dispose.
APTR OOP_FindClass(
CONST_STRPTR classID );
Finds a class with given ID in the list of public classes.
classID - Public ID of the class to find.
Pointer to a public class or NULL if there's no such class
IPTR OOP_GetAttr(
OOP_Object * object,
OOP_AttrID attrID,
IPTR * storage );
Gets the specifed attribute from the object,
and puts it into storage.
object - pointer to object from which we want to
get an attribute.
attrID - Attribute ID for property to get.
storage - Pointer to IPTR the fetched data should be put into.
OOP_AttrBase OOP_GetAttrBase(
CONST_STRPTR interfaceID );
Maps a globally unique string interface ID into
a numeric AttrBase ID that is unique on
pr. machine basis. IMPORTANT: You MUST
be sure that at least one class implementing
specified interface is initialized at the time calling
this function. This function is especially useful
for a class to get AttrBases of the interfaces
it implements.
interfaceID - globally unique interface identifier.
Numeric AttrBase that is unique for this machine.
There are NO error conditions.
OOP_MethodFunc OOP_GetMethod(
OOP_Object * obj,
OOP_MethodID mid,
OOP_Class ** classPtr );
Get a specific method function for a specific object and
a specific interface. This a direct pointer to the method
implementation. The pointer should ONLY be used on the object you
acquired.
obj - pointer to object to get method for.
mid - method id for method to get. This may be obtained with GetMethodID()
classPtr - A pointer to a location where implementation class pointer will be stored.
The obtained method must be called with this class pointer. This pointer
is mandatory!
The method asked for, or NULL if the method does not exist in
the object's class.
!!! Use with EXTREME CAUTION. Very few programs need the extra speed gained
by calling a method directly
!!!
OOP_MethodID OOP_GetMethodID(
CONST_STRPTR interfaceID,
ULONG methodOffset );
Maps a globally unique full method ID
(Interface ID + method offset) into
a numeric method ID.
interfaceID - globally unique interface identifier.
methodOffset - offset to the method in this interface.
Numeric method identifier that is unique for this machine.
APTR OOP_NewObject(
struct OOP_IClass * classPtr,
CONST_STRPTR classID,
struct TagItem * tagList );
APTR OOP_NewObjectTags(
struct OOP_IClass * classPtr,
CONST_STRPTR classID,
TAG tag, ... );
Creates a new object of given class based on the TagItem
parameters passed.
classPtr - pointer to a class. Use this if the class to
create an instance of is private.
classID - Public ID of the class to create an instance of.
Use this if the class is public.
tagList - List of TagItems (creation time attributes),
that specifies what initial properties the new
object should have.
Pointer to the new object, or NULL if object creation failed.
You should supply one of classPtr and classID, never
both. Use NULL for the unspecified one.
OOP_AttrBase OOP_ObtainAttrBase(
CONST_STRPTR interfaceID );
Maps a globally unique string interface ID into
a numeric AttrBase ID that is unique on a
per machine basis. The AttrBase can be combined
with attribute offsets to generate attribute IDs.
interfaceID - globally unique interface identifier.
for which to obtain an attrbase.
Numeric AttrBase that is unique for this machine.
A return value of 0 means that the call failed.
#define aTimer_CurrentTime (__AB_Timer + aoTime_CurrentTime)
..
__AB_Timer = OOP_ObtainAttrBase(IID_Timer);
SetAttrs(timer, aTimer_CurrentTime, "10:37:00");
Obtained attrbases should be released with ReleaseAttrBase().
BOOL OOP_ObtainAttrBases(
const struct OOP_ABDescr * abd );
ULONG OOP_ObtainAttrBasesArray(
OOP_AttrBase * bases,
CONST_STRPTR const * ids );
Obtain several attribute base IDs, storing them in linear array.
bases - a pointer to array to fill in
ids - a NULL-terminated array of interface IDs
Zero on success or number of failed bases on failure. Failed
entries will be set to 0.
ULONG OOP_ObtainMethodBasesArray(
OOP_MethodID * bases,
CONST_STRPTR const * ids );
Obtain several method ID bases, storing them in linear array.
bases - a pointer to array to fill in
ids - a NULL-terminated array of interface IDs
Zero on success or number of failed bases on failure. Failed array
entries will be set to -1.
Method IDs are owned by particular class, and are released when
the class is destroyed. Thus, there is no ReleaseMethodBasesArray()
function.
LONG OOP_ParseAttrs(
struct TagItem * tags,
IPTR * storage,
ULONG numattrs,
OOP_AttrCheck * attrcheck,
OOP_AttrBase attrbase );
Parse a taglist of attributes and put the result in an array.
It will only parse the attr from a single interface
which is indicated by the 'attrbase' parameter.
tags - tags to be parsed.
storage - array where the tag values will be stored.
To get the value for a certain tag just use
ao#? attribute offset as an index into the array.
The array must be of size 'numattrs', ie. the number
of attributes in the interface.
numattrs - number of attributes in the interface.
attrcheck - will is a flag that where flags will be set according
to the attributes' offset. Since this is only 32
bytes you can only parse interfaces
with <= 32 attributes with this function.
If you try with more, you will get a
ooperr_ParseAttrs_TooManyAttrs error.
The flags will be set like this if an attr is found:
attrcheck |= 1L << attribute_offset
attrbase - attrbase for the interface whise attrs we should look for.
0 for success, and an error otherwise.
Possible values are:
ooperr_ParseAttrs_TooManyAttrs.
VOID OOP_ReleaseAttrBase(
CONST_STRPTR interfaceID );
Release an OOP_AttrBase previosly obtained with
OOP_ObtainAttrBase()
interfaceID - globally unique interface identifier.
for which to release an attrbase.
The call must be paired with OOP_ObtainAttrBase().
VOID OOP_ReleaseAttrBases(
const struct OOP_ABDescr * abd );
void OOP_ReleaseAttrBasesArray(
OOP_AttrBase * bases,
CONST_STRPTR const * ids );
Release several attribute ID bases, stored in linear array.
bases - a pointer to array of bases
ids - a NULL-terminated array of corresponding interface IDs
It is legal to have some entries in the array not filled in
(equal to 0). They will be skipped.
void OOP_RemoveClass(
OOP_Class * classPtr );
Remove a class from the list of public classes.
The class must have previously added with AddClass().
classPtr - Pointer to class that should be removed.
IPTR OOP_SetAttrs(
OOP_Object * object,
struct TagItem * attrList );
IPTR OOP_SetAttrsTags(
OOP_Object * object,
TAG tag, ... );
Sets the object's attributes as specified in the
supplied taglist.
object - pointer to a object in whih we
want to set attributes.
tagList - List of attributes and their new values.
|
|
