PWactivate: ACTIVATING OBJECTS

This Chapter explains how you can activate objects within ProWesS, and what that actually means!

Purpose

Activation normally only concerns an outline object. When you activate the outline with this keyword, control of your program is passed to ProWesS. ProWesS then (and only then) actually paints the window on the screen with all the objects you have PWcreated. Once the window is drawn, ProWesS watches over what happens with the pointer within the window and whether the user presses any special keys etc... At some predefined point, it will come back to your program and tell it why it came back, i.e. what has happened (such as the fact that the user clicked on a loose item).

Syntax

The syntax of the PWactivate keyword is as follows:

mempointer= PWactivate (object,mempointer,object_hit,add_info,hit_or_do%)

where:

So, once you have created all of the objects, your program will be actually a simple loop, something like this:


         (...definition of your objects here...)
         (... you are presumed to have defined an object called outline...)
         (...and another one called item1, which is a loose item...)

         mem=0:object_hit=0:hit_do%=0:add_info=0
         REPeat loop%
           mem=PWactivate(outline,mem,object_hit,add_info,hit_do%)
           SELect ON mem
              =0     : PWremove outline:STOP     : rem user pressed QUIT
              =item1 : take_care_of_this_item
                   (...)
           END SELect
         END REPeat loop%

This is actually a very simple program structure - a loop which terminates when 0 is returned in mempointer.

Defining objects to return

So, ProWesS draws the window and then handles everything else, checking where the mouse is, and so on. This would mean that the PWactivate call would never return, so there must be a way to tell ProWesS to relinquish control and return to SBasic. This happens automatically whenever the user quits the program - in that case, the PWactivate function returns 0, as we have seen.

All that needs to be explained now is how to tell ProWesS to make a return from the PWactivate call for other reasons. This is done whenever you create (and, sometimes, change) an object. If you look at the tags for a determined type, you can see that some of them permit "do routines", "hit routines" or other action routines to be passed to an object. An example would be the tag "OUTLINE_ACTION_DO" for the outline type of object. If you use this tag, it must be followed by a routine which is called from the ProWesS Event Handler. In other words, you must tell ProWesS what routine to call when the user actions the DO item in the window.

This means that ProWesS itself, once it has drawn the window, is just a loop that checks what the user does with the mouse or the keyboard (an "event"). This piece of ProWesS is the ProWesS Event Handler. If the user actions the DO item, the ProWesS Event Handler checks whether there is a routine it should go to (the one indicated by you) and, if so, it jumps to that (machine code!) routine. That routine then does what it has to do, and returns control back to the ProWesS Event Handler.

Of course, for the SBasic programmer, the best thing would be if there was a way to tell ProWesS to call a determined SBasic function or procedure directly upon such an event. Unfortunately,that isn't possible since you cannot call an SBasic procedure from within a machine code program. So there are several new keywords, which, when called from the ProWesS Event Handler, will return to SBasic: HIT_ROUTINE , DO_ROUTINE and many other routines, which are explained elsewhere in the manual. You just use these as parameter whenever a tag requires an action routine.

  • A fake return

    Thus, whenever you use these two keywords to indicate that, upon a hit or do on an item, ProWesS should come back to SBasic, this is indeed done: the PWactivate call returns with a certain value in mempointer (other than 0). You must be aware however, that this is a fake return! In fact, ProWesS doesn't know that it has returned control back to SBasic: It still thinks that it is in the routine that was called from within its Event Handler, since the two keywords return to SBasic without returning to the ProWesS Event Handler.

    It is thus very important that you always check on the mempointer returned by PWactivate. If this is 0, then a clean return was made from ProWesS - this can also be seen by the fact that the window drawn by ProWesS has disappeared: whenever a clean return is made to SBasic, the window is undrawn first.

    If the value returned by PWactivate is not 0, then a fake return was made, and you must loop back to this call and go back to ProWesS so that a return is made from the routine called by the ProWesS Event Handler. This also explains the loop structure of the above example: a simple loop, always calling upon PWactivate, until 0 is returned.

    If you do not do this, but rather call the PWactivate call completely anew (i.e. with mempointer = 0) then you will certainly loose some memory (at least 4 KB, this is a guaranteed minimum). Apart from that, it should be safe to do so, but there is a risk that you might also confuse (i.e. crash) your copy of SBasic and/or ProWesS and/or the entire system. So don't!

    For reasons which are more closely explained in the comment on the PWquit keyword, it is never a good idea that the outline and the mempointer variables be LOCal variables.


    PROGS, Professional & Graphical Software
    last edited 1996 Jun 06 (wl)