PWcreate: CREATE AN OBJECT

This Chapter explains the use of the PWcreate function. It also explains the concepts of owner, types and tags.

Purpose

The PWcreate function is used to create any and all objects. As we have said in the introduction, creating an object is one of the main steps in ProWesS programming. It is also generally the very first step - you can't really do anything with (or rather in) ProWesS until you have created some objects. So this step is paramount.

SYNTAX

For something so important, it is actually achieved quite easily, by using the PWcreate keyword. This is a new function with the following syntax:

my_object = PWcreate (owner, type [,tag parameter][,tag parameter]...)

This will create an object, and the SBasic variable my_object will be that object. From now on, whenever you need an object for doing something, you can use my_object. This is actually no different from using any other variable returned by a function in SBasic. Sometimes, you will come across the term "Object ID" which is just this variable, too!

The parameters passed to the function can look more daunting than they are. What this function does is create the object my_object according to the parameters you have given. The parameters are logically structured and correspond to some important concepts within ProWesS.

The Owner

The owner of my_object is the object that will own my_object. As was stated in the introduction , objects usually belong to other objects. With this parameter, you tell ProWesS who my_object will belong to.

Of course, the very first object doesn't belong to anybody, so the owner is 0. If you now create a second object that belongs to the first object, the owner of that second object is my_object as returned by the first call to PWcreate.

Type

This parameter of the PWcreate function tells the software what type of object you are creating. There are many different types of objects, which will do different things.

Normally, the first object would be the outline of the window, which is just a sort of container enclosing all the other objects in the window. So the type of this object would be that of an outline. Another object could be, for example, a menu item for this outline, or an infotext item.

Each type has one special type word associated to it which is predefined and explained in the part of the manual concerning the detailed description of the Types and Tags. Thus, if you want to indicate that the object is to be of the type outline, you will use the PW('TYPE_OUTLINE') type.

TAGS

The types are very different from each other. But there are only a few of them and it seems logical that you will have to define some more details for them. This is why the type parameter can itself be followed by other parameters - for some strange reason, these parameters are called TAGS and define exactly what characteristics the type should have. For example, if you create an object of the type loose_item, you should tell this object whether it contains a string or an icon, and if it is a string, what the string is. In other words, you would follow the type by a 'tag' saying that the item is of the type string, and the tag would then be followed by the string.

Tags are always dependent on a type. Each type has its own tags, even though they may achieve something similar, like setting a text. For more detail on what each tag does, you should look to the part of the manual that contains the detailed description of Types and Tags. The Tags are thus parameters for the types. If you remember, in the introduction it was mentioned that ProWesS is not complicated but complex, since there is a lot of information to absorb. Most of that information concerns the tags, and what they mean and do. To be quite frank, I personally can never remember what type can uses what tags, and what each tag does. I just keep a copy of the manual handy and look it up whenever I need to. If you want to learn them by heart, though, feel free to do so.

The part of the manual concerning the detailed description of the Types and Tags contains not only a 'detailed description' of each type and its tags, it also sets out whether the tags can be used during creation of the object, changes to the object or queries to the object. In most cases, all tags that can be used when you create an object, can also be used when you change an object (with PWchange), even though there are a few exceptions. On the other hand, all tags used for a change can always be used during the creating of an object.

An example

Here is an example of the PWcreate function. It creates an outline (this is the type) which has a quit item (one of the tags for this type). The owner of this outline will be 0.

my_outline=PWcreate (0,PW('TYPE_OUTLINE'),PW('OUTLINE_QUIT'))


PROGS, Professional & Graphical Software
last edited 1996 May 29 (wl)