The ProWesS access routines have the following prototypes :
typedef struct _PWDummyObject *PWObject; typedef unsigned long PWType; typedef struct _PWTypeDef PWTypeDef; Error PWCreate(PWObject owner, PWObject *ret, PWType type, ...); Error PWDoCreate(PWObject owner, PWObject *ret, PWType type, int *taglist); Error PWChange(PWObject object, ...); Error PWDoChange(PWObject object, int *taglist); Error PWQuery(PWObject object, int what, void *ret); Error PWActivate(PWObject object); Error PWAddType(PWTypeDef *newtype); Error PWRemove(PWObject object);
The variable arguments list is used to pass a taglist to the function. A tag is a number which indicates a function and which can have its own parameters. Such parameters can have any type, and there can be between zero and 15 of them. A tag can also have a list of parameters (the list is ended by the parameter NULL), or the parameter can be another taglist. A taglist itself is also terminated with a NULL tag. The use of a taglist will become clear in the examples.
In ProWesS there are three kinds of tags : creation tags, change tags and query tags. A particular tag can belong to more than one kind at the same time.
A query tag can only be used as the what part of the PWQuery function. A creation tag has a special meaning when passed to PWCreate, and is normally not valid when passed to PWChange. A change tag can be used to change some characterictic of an object. It can be applied at any time, and is part either of a PWCreate or a PWChange taglist.
The definitions of the prototypes and of the tags supported by ProWesS and by the standard types are defined in "ProWesS.h".
Error PWCreate(PWObject owner, PWObject *ret, PWType type, ...);
This command is used to create an object. An owner has to be passed to indicate the system to which the newly created object has to belong. If the owner is NULL then a new system will be created for the object.
On return, ret will be filled in with the object identifier of the newly created object. It will be NULL if an unrecoverable error occured. If the object identifier is not used in the program, NULL can be passed instead.
The type parameter indicates which type of object has to be created. Then follows a taglist with some parameters for the newly created object.
When a new region is created, it has to be positioned in the window. This can either be done by specifying one of the positioning tags explained below, or by means of a default rule (see also window structure).
The default rule positions the region as last object inside the owner. Thus it will be displayed at the bottom right in the owner. To achieve this, the children of (that is, the objects inside) the owner are scanned. While the last (rightmost or bottommost) child is not composite and has children, that region is used as owner. If the last region has no children, then the object is linked after that last region. If the owner did not have any children, the newly created region will just be linked as child.
The PW_POSITION_RIGHT_OF, PW_POSITION_LEFT_OF, PW_POSITION_BELOW and PW_POSITION_ABOVE tags (which require a "PWObject" parameter) specify a position relative to the object given as parameter. If the parameter is inside a region in the correct primary direction, then the new region is just linked in before or after the parameter object. If not, then a new container region (a row or column) is created which will contain both the parameter object and the new object. This container region can also be created explicitly (PW_TYPE_DIRECTION). The container automatically windowfits and has a scale factor of 1. If you want something else, you have to do it explicitly. Please note that the introduction of an extra level of nesting of regions can, if the parameter object has children, have the effect of changing the positioning of these children. Objects which where next to each other will suddenly be positioned below each other and vice versa.
The PW_POSITION_NEXT_ROW and PW_POSITION_NEXT_COLUMN tags will create a new container region (type PW_TYPE_DIRECTION) at the bottom/right inside the owner. The newly created object will be the first object in the newly created row/column. ProWesS will make sure that the primary direction of the container region is as requested.
Error PWCreate(PWObject owner, PWObject *ret, PWType type, ...);
This is a variant of the PWChange command. It is provided because it allows the programmer to pass the parameter list in an array instead of on the stack. This can sometimes prove useful (e.g. for storing window descriptions in a data structure instead of code).
Error PWRemove(PWObject object);
This command removes an object from the system. If the object which has to be removed is a region object, then all the children will also be removed. When all the regions in the system have been removed (with the exception of the PW_SLEEP_OBJECT and its children), then the system itself will be removed.
Error PWChange(PWObject object, ...);
Some of the parameters of an object or the system can be changed with this command. It requires the object for which the changes should be valid, and a taglist which specifies what has to be changed.
Error PWDoChange(PWObject object, int *taglist);
This is a variant of the PWChange command. It is provided because it allows the programmer to pass the parameter list in an array instead of on the stack. This can sometimes prove useful (e.g. for storing window descriptions in a data structure instead of code).
Error PWQuery(PWObject object, int what, void *ret);
ProWesS can also be queried about the current status of some of its internal settings, or about some of the objects. The what parameter has to be a query tag, and the result is returned in ret.
Although this is a very straightforward way to query ProWesS or an object, it may sometimes be too limited (e.g. for querying about a string which should be returned in a buffer of limited length). In such cases, the PWChange mechanism can still be used to formulate a query.
Error PWActivate(PWObject object);
This is the most important command of them all. After you have set up all the objects which make up your window, you can now get it up and running. This function will display your system and wait for events to occur. When they happen, they will be processed by the appropriate event handlers (as you have installed them). This function will only terminate after the system has been passed a PW_SYSTEM_BREAKDOWN tag. The window will then be removed.
Error PWAddType(PWTypeDef *newtype);
In some cases you may need a special type which is application specific. Such a type can be added using this function. When a new object is created, first a list of application specific types is searched for a type with the given identifier. If that fails, the normal list of types is searched for a match. It is thus possible to replace one of the loaded types with something else for this particular application.