PWactivate: ACTIVATING OBJECTS
This Chapter explains how you can activate objects within ProWesS, and what
that actually means!
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:
- object
is the object to activate, as returned by the PWcreate function.
- mempointer
is the result returned, and is also used within the call to
PWactivate. It is a pointer to somewhere in memory. THIS MUST BE 0 THE
FIRST TIME YOU USE PWactivate for this object. After this, it is maintained
by the system itself and you do not have to worry about it. This pointer
will be 0 when the user clicked on the QUIT item of your window, indicating
that he/she doesn't want that window anymore. You should then remove the
outline object and (possibly) stop the program.
- object_hit
tells you what object was hit (or done or otherwise indicated
by the user) and which thus caused ProWesS to return control to your
program. This enables you to make a SELECT on all objects which are likely
to be actioned by the user, and thus direct the flow of your program to
where you deal with this object.
- add_info is some additional information about the object. What this is
exactly depends on the object, and on the cause for the return from the
PWactivate call. More often than not, this doesn't contain any useful
information... The content of this variable -if any- is set out in the part
of this manual concerning the types and their
tags - if a certain tag causes this variable to contain useful
information, you will be told when this tag is described. In most cases,
you can just ignore this variable.
- hit_or_do%
(an integer variable) contains an indication whether the user
hit your object, or did it, since this might be of some importance. If the
value of this variable is 0 upon return, the object was hit. If this
variable is 1, the object was done. This variable can have many other
values - the value depends directly on which action routine you indicated
when setting up an object- see below "A fake return".
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)