rom/oop/docs/class_creation.doc

   1 Classes are objects of metaclasses, so therefore
   2 classes are created with NewObjectA().
   3
   4 As of now there are three different metaclasses available:
   5
   6 CLID_MIMeta
   7 - Creates classes that supports multiple interfaces.
   8
   9 CLID_SIMeta
  10 - Creates classes that can only support single interfaces.
  11 Advantage is faster method invocation.
  12 (Method invocation doesn't require hashing).
  13
  14 CLID_HiddMeta
  15 - Base metaclass for Hidds. Subclass of CLID_SIMeta.
  16 (HIDDs should be fast).
  17
  18 How to create a class is best shown through an example.
  19 Here is a Timer class with two simple methods,
  20 Start and Stop.
  21 Note, this example doesn't show the New and Dispose
  22 methods and DoSuperMethod() usage, but it is exactly the same as in BOOPSI,
  23 so those familiar with BOOPSI,should find creating classes with this
  24 system simple.
  25
  26
  27 /* In the classes' include file you have to define class ID, interface ID
  28    method offsets and attribute offset
  29 */
  30
  31 /* The IDs below should really be genrated by some tool,
  32    as a combination of current time and some machine
  33    unique ID, IP address or othe unique entity, to
  34    assure unique IDs.
  35
  36 */
  37
  38 #define CLID_Timer      "timerclass"
  39 #define IID_Timer       "I_timer"
  40
  41
  42 /* Method offset for methods in the IID_Timer interface. */
  43
  44 enum
  45 {
  46     moTimer_Start       = 0,
  47     moTimer_Stop,
  48
  49     Num_Timer_Methods   /* number of methods in the Timer interface */
  50
  51 };
  52
  53
  54 /* Attribute offsets for attrs in the IID_Timer interface. */
  55
  56 enum
  57 {
  58     aoTimer_Elapsed = 0,
  59
  60     Num_Timer_Attrs     /* number of attrs in the timer interface */
  61 };
  62
  63
  64 /* private instance data */
  65 struct timer_data
  66 {
  67     struct timeval start_time;
  68     struct timeval elapsed_time;
  69 };
  70
  71 /* The methods */
  72
  73
  74 static VOID timer_start(Class *cl, Object *o, Msg msg)
  75 {
  76     struct timer_data *data;
  77
  78     data = INST_DATA(tcl, o);
  79
  80     gettimeofday(&(data->start_time), NULL);
  81
  82     return;
  83 }
  84
  85 static VOID timer_stop(Class *cl, Object *o, Msg msg)
  86 {
  87     struct timer_data *data = INST_DATA(tcl, o);
  88     gettimeofday(&(data->elapsed_time), NULL);
  89
  90     SubTime(&(data->elapsed_time), &(data->start_time));
  91
  92     return;
  93 }
  94
  95
  96 #define NUM_TIMER_METHODS 2
  97 Class *make_timerclass()
  98 {
  99
 100     struct MethodDescr methods[NUM_TIMER_METHODS + 1] =
 101     {
 102         {(IPTR (*)())timer_start,               moTimer_Start},
 103         {(IPTR (*)())timer_stop,                moTimer_Stop},
 104         {NULL, 0UL} /* must be null-terminated */
 105
 106     };
 107
 108     struct InterfaceDescr ifdescr[] =
 109     {
 110         { methods, "Timer", NUM_TIMER_METHODS },
 111         { NULL, 0UL, 0UL} /* must be null-terminated */
 112     };
 113
 114     struct TagItem tags[] =
 115     {
 116         {A_Meta_SuperID,                (IPTR)CLID_Root},
 117         {A_Meta_InterfaceDescr,         (IPTR)ifdescr},
 118         {A_Meta_ID,                     (IPTR)CLID_Timer},
 119         {A_Meta_InstSize,               (IPTR)sizeof (struct timer_data)},
 120         {TAG_DONE, 0UL}
 121     };
 122
 123     Class *tcl;
 124
 125
 126     /* Make it a class of the SIMeta */
 127     tcl = (Class *)NewObjectA(NULL, CLID_SIMeta, tags);
 128
 129
 130     if (tcl)
 131     {
 132         /* Make the class public */
 133         AddClass(tcl);
 134     }
 135
 136     return (tcl);
 137 }
 138
 139 VOID free_timerclass(Class *cl)
 140 {
 141     DisposeObject((Object *)cl);
 142
 143     return;
 144 }
 145
 146
 147 /* Stubs would look like this */
 148
 149 VOID Timer_Start(Object *timer)
 150 {
 151     static ULONG mid = NULL;
 152
 153     if (!mid)
 154     {
 155         /* First time executed the stub converts the full method ID
 156            (String Interface ID, numeric method offset) into a
 157            numeric method ID.
 158         */
 159
 160         mid = GetMethodID(IID_Timer, moTimer_Start);
 161     }
 162
 163     DoMethod(timer, (Msg)&mid);
 164
 165     return;
 166 }
 167
 168
 169 This API is bound to change, as its not flexible enough
 170 (not future-proof), better use tags for specifying all info.
 171
 172 Anyway, have a look at the unixio.hidd and hiddclass implementation
 173 for a bit more complex usage of this system.
 174