Please visit the sponsor of this series, and don't forget to say where you heard of them!
Please ensure you have the latest version (1.4) of the RMREvent example program before reading through this tutorial. If you use an older version, some of the text may not make sense.
Do you remember looking at the procedure Action_Pen_or_Keypress: with me a while back?
At the time we glossed over the lines
ELSEIF Key&=Pointer_Used
IF TBarOffer%:(A&(3),A&(4),A&(6),A&(7))
RETURN
ELSEIF A&(4)=1
Pointer_Event:(A&(3),A&(6),A&(7))
ENDIF
etc.
but it's now time to look more closely at exactly how we can interact with the toolbar. Before looking closely, run the RMREvent program again, tap on the toolbar a few times and on the main screen and note the program's responses. Handling of the possible places for pen-taps certainly seems to be working well - so how does the 'magic' work?
There are two things to check once we detect that the pen has
been used on the touch-screen. Firstly we 'offer' the pen event, with all the
necessary parameters (window name, event type and x and y coordinates), to the
toolbar that we set up in an earlier session. Don't worry too much for now
about exactly how it all works, but essentially the Psion-written toolbar
routine 'returns' -1 ('true') or zero ('false') depending on whether the window
name and coordinates make sense to it (i.e. whether it 'accepts' the parameters
as valid). Note the "%" character at the end of the procedure name. This is
what tells us (and OPL) that the procedure returns a value to the part of the
program it was called from.
If the toolbar likes the information it's been given, it
automatically actions the correct procedure for the button that was tapped (see
below) and returns -1 (true). RETURN is then used to return back to the main
RMREvent event loop now that the right response has been made to the user's
action. Note that in addition to 'liking' taps on the buttons themselves, the
toolbar also 'likes' taps on the toolbar title or on the clock and
automatically handles the display of open files and the changing of the clock
type.
If the toolbar doesn't like the numbers given to it, it just
returns zero (false) and so our code skips on to pass the pen event coordinates
to our own Pointer_Event: procedure instead. Note that RMREvent only actually does
this if the pen event 'type' is equal to 1. Looking in my OPL/32 manual, type 1
is generated when the pen is lifted from the screen ('pen up'). It's equally as
valid in general to detect 'pen down' or 'pen drag' and to do things with them,
but for RMREvent's purposes we've chosen to use the moment the user lifts the
pen after tapping as the point at which we start to do stuff. Note that each
user pen-tap can involve 2 or more actual pen events ('down', maybe a 'drag' or
two and 'up' again) and that you wouldn't generally want to use all of
these. One is quite sufficient for us here.
So how does TBarOffer%: manage to action procedures within RMREvent? The
answer is that Psion have provided a standard mechanism. Each button is set up
with a unique letter code of it's own. You'll remember seeing the special
TBarButt: setup lines in the Init: procedure, which set our four buttons up
with the letter codes "a", "b", "c" and "d":
The Psion toolbar simply calls procedures Cmda%:, Cmdb%:, Cmdc%: and Cmdd%: as
necessary. Locate and study these procedures in the RMREvent source code:
Note that by making these Cmdx%: procedure names your
standard action procedures in the program you can simplify things slightly and
avoid duplication, i.e. The Menu function "Find" and the shortcut Control-f and
the toolbar button "Find" could all be set to point at procedure Cmdf%:, which
of course is where you put the code to do the actual finding (or whatever).
There's a lot going on here, so the simpler you can make your program and the
fewer the number of strictly unnecessary steps and procedures the better!
If you're a SIBO (OPL/16) programmer and are desperately hanging in here trying to make sense of how to relate all this to the Series 3 range, just remember that it's almost as easy as ripping out everything to do with the pen and touch-screen and using 'normal' (%) integers rather than 'long' ( ones. Maybe we'll do a version of RMREvent for OPL/16? Watch this space.
Next week we'll look at RMREvent's menu in detail....
Go to next lesson | Programming index