Using or Adding a Project

 

All classes, methods and items of a projects are added by the method

   GRAPE(project, "use")(batch)

PROJECT * project
int batch

This is of course only done if the project isn't already in use. The batch flag determines if the items should be used, too. If the items should be supressed because the program is in global batch mode and the manger isn't available the value of g_batch_mode should be used for batch, for a description of the global batch mode and the g_batch_mode variable see 9.1.4. All projects the project depends upon are "use"d first, then the project's objects are added and finally a user defined init-method, which should be called "pname-init" for project pname, is called when the project goes into use.

How does a project know that it is in use? Everytime the method "use" is called the project's use count is increased. If the use count is zero the project isn't in use, then the classes, methods and items have to be added and the init-method is called. When "unuse" (see below) is called the use count is decreased and if it is zero all the objects added by "use" are removed after the exit-method has been called. The projects the project depends upon are "(un)use"d every time the methods are called to correct their use counter.

The init-method should do initializations for the project that cannot be done in the setup-method. For example if you have to call some method defined in the project before the project can be used, this is the place to do it, because when the init-method is called all classes and methods of the project are available. This method is called every time the project wasn't in use and is used again, therefore if some action has only to be taken once then a static flag has to be used.

An example is the init-method of our demo project in section 5.6.6.4 where the method "get-editor" is called to create the user-interface. Items that should be managed by the project cannot be added to the manager with "add-inter" or "add-inter-for-opt" directly, but they have to be added to the project with

     

PROJECT * project
ITEM * item
int menu_nr

instead. These methods have the same syntax and the same effect as "add-inter" and "ad-inter-for-opt", but they allow the project to add or remove the item.

The method

   GRAPE(project, "add")()

PROJECT * project

is for example called when a project is added from the managers project list. First the project is "use"d in non-batch mode, then the user defined add-method, which should be called "pname-add" for project pname, is called before the project message defined by P_Version, P_Date and P_Author is displayed.

The add-method is called everytime the project is "add"ed. It can be used to create an object (or hierachy of objects) that should be included in the data hierarchy by the project. The object is declared to the project with

   GRAPE(project, "set-object")(inst)

PROJECT * project
INSTANCE * inst

Only one object can be added to the data hierarchy (if the method is called a second time the previously given object is lost), of course you can create a whole hierarchy and give it to "set-object".

This method is used by the add-method of our demo project to add a Rot2d instance to the data hierarchy (see section 5.6.6.3).

When projects are created with g_project_include the project pointer is not available and therefore "use" and "add" cannot be called directly. Nevertheless the methods can be called with the functions

PROJECT * g_project_use(char * name, int batch);
PROJECT * g_project_add(char * name);

because project names are unique. The project pointer is returned by the functions to indicate that they were successful, if they return NULL something has failed, perhaps there was no project name.