The "setup" Method

 

A setup-method has to be provided for every project (everything else is optional), it should be called "pname-setup" where pname is the name of the project. When a project is used for the first time this setup-method is called to initialize it. For declaring which other projects, classes, methods, items, etc. belong to the project the method

   GRAPE(project, "setup")(...)

PROJECT * project

has to be sent to it within the setup-method. "setup" has a variable parameter list (like the new_item function), each parameter starts with a tag (with prefix P_) followed by its arguments. The list has to be terminated with P_End otherwise the project initialization will probably fail.

The order of the tags is only significant if the same tag is used several times: if for example a class and a subclass of this class should be created first the class and then its subclass have to be given, because they are created in this order. The "use" method will always add methods after the classes have been added, therefore methods can be given before the class they belong to is declared.

The following list describes all possible tags and their parameters. Some of the tags will be used in our Rot2d example in section 5.6.6.2.

P_Project, char *name:

The name of a project this project depends upon. The "(un)use" method will send "(un)use" to project name to add (remove) it before this project is added (removed). Be careful: currently loops are not allowed, therefore none of the "use"d projects can "use" this one again.

P_ProjectList, PROJECT_DESCR *plist:

Same as P_Project, but now the whole NULL terminated list of list of project is added (removed). Again, loops are not allowed. PROJECT_DESCR is defined as

typedef struct {
  char *name;
} PROJECT_DESCR;

P_Class, CLASS **super, CLASS **class, char *name, int size:

Create a new class name and store the class pointer in class (therefore the pointer pointer). size has the same meaning as in the "new-class" method (section 5.3.4), it should be the size of the structure defining the instances of the class. The new class will be a subclass of super. Here a pointer to the superclass-pointer has to be provided because the superclass might be created within the project, in this case the superclass-pointer is not sufficient (it would be NULL).

P_ClassList, CLASS_DESCR *clist:

Same as P_Class for a list of classes. Each entry in clist has the same structure as the parameters to P_Class:

typedef struct {
  CLASS **superclass;
  CLASS **class;
  char *name;
  int size;
} CLASS_DESCR;

This list has to be NULL terminated, too.

P_ClassCN, char *classname, CLASS **class, char *name, int size:

This tag is used to create a new class even if the class pointer of the superclass is unknown. classname is the name of the superclass, the other parameters are the same as for P_Class. This tag makes only sense for dynamic shared object and shouldn't be used yet.

P_Method, CLASS **class, char *name, void *(*func)():

Add the method name implemented by the method function func to class class. Again a class pointer pointer is needed, because the class might be created by the project.

P_MethodList, METHOD_DESCR *mlist:

Same as P_Method for a list of method. Each entry in mlist has the same structure as the parameters to P_Method:

typedef struct {
  CLASS **class;
  char *name;
  void *(*func)();
} METHOD_DESCR;

Like all project lists this one has to be NULL terminated. This is the list that is most often used (for example in our Rot2d example in section 5.6.6.2). Since every method has its own class (pointer) pointer methods from different classes can be handled with one list.

P_MethodCN, char *classname, char *name, void *(*func)():

As P_ClassCN this tag only makes sense for dynamic shared objects and shouldn't be used yet. It is used to add a method without knowing the class pointer, the name of the class classname is used instead. The other parameters are identical to those of P_Method.

P_Item, ITEM *item:

The item will be handled by the project. The items of a project are only visible if the project is in use, they will be added to and removed from the manager automatically with the project. If the items are visible depends on the batch flag that is given as parameter to "use". When the project is added from the manager's project list the batch flag is always FALSE and the items are added. The item is added with "add-inter", therefore it is placed in the first option menu.

P_ItemOpt, ITEM *item, int menu_nr:

Same as P_Item, but the item will be placed in option menu menu_nr. There is no tag ``P_ItemList'' because items can be and should be grouped.

P_ButtonList, BUTTON_DESCR *blist:

This and the following tags are provided for compatibility with the old project management where it was only possible to handle lists of buttons, rulers and sliders. Each entry in blist has the format

typedef struct {
  char *methname;     /* method to be send by the button */
  INSTANCE **obj;     /* instance to send it to, NULL if current instance */
  char *txt;          /* label of the button */
  double l, h, x, y;  /* size and position */
  int optmenu;        /* option menu the button should be added to */
} BUTTON_DESCR;

Again a pointer pointer to the instance of the ruler has to be provided, because the instance of the ruler could be a class that is created by the project. The rulers will be created by the "setup" method, nevertheless the instances are initialized later when the items are added. The buttons of the list can be placed in a group by using the new_item function's tag I_ButtonList (see section 5.5.3), but in this case the button's instances must be initialized.

P_RulerList, RULER_DESCR *rlist:

Same as P_ButtonList for rulers, see there. RULER_DESCR has the format

typedef struct {
  void *var;          /* variable modified by the ruler */
  char *txt;          /* label of the ruler */
  double x, y;        /* position of the ruler */
  char *action;       /* method called when the ruler is modified */
  int type;           /* ruler's type (dfInt, dfFloat, dfDouble) */
  int optmenu;        /* option menu the ruler should be added to */
} RULER_DESCR;

P_SliderList, SLIDER_DESCR *slist:

Same as P_ButtonList for sliders, see there. SLIDER_DESCR is defined as

typedef struct {
  void *var;          /* variable modified by the slider */
  char *txt;          /* label of the slider */
  double x, y;        /* position of the slider */
  char *action;       /* method called when the slider is modified */
  int type;           /* slider's type (dfInt, dfFloat, dfDouble) */
  int optmenu;        /* option menu the slider should be added to */
} SLIDER_DESCR;

Because of the fixed structure of the lists the possibilities when creating buttons, rulers or sliders with P_ButtonList, P_RulerList or SliderList are very limited. These tags should really only be used if an old project is converted.

P_InitMethod, char *init:

Set the init-method of the project. This method has to be added by the project with P_Method or within a P_MethodList.

P_ExitMethod, char *exit:

Set the exit-method of the project. This method has to be added by the project, too.

P_AddMethod, char *add:

Set the add-method of the project. Has to be added, too.

P_Version, int version, int revision:

With P_Version, P_Date and P_Author a standard message can be set for the project. The first line contains the method name, the second the version and date and the third one the author information. The message will be displayed every time the project is "add"ed.

P_Date, char *date:

Used together with P_Version and P_Author, see P_Version.

P_Author, char *author:

Used together with P_Version and P_Date, see P_Version.