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.
This week sees us exploring one of the great mysteries of Psion programming - how to associate programs with individual documents so that the system screen's file commands do the right thing.
Most of us will have written standalone applications by now, in which the program stands alone, perhaps using its own settings file (tucked away in some dark corner) but certainly not making its mark in any of the main document directories. We've looked enviously at other programs for which 'New' files can be created, each with the correct program icon. It's time now to redress the balance, again using the RMREvent example program.
The first thing to notice is the line FLAGS 1 in the opening APP...ENDA
section. This is vital, letting the system screen know that our application is
capable of handling 'New' files etc. You can verify that it's working by going
to the system screen, tapping on 'New file' and spotting 'RMREvent' in the list
of possible types.
The second part of the jigsaw is the variable SystemCommandLetter$, which RMREvent
gets from the system screen via CMD$(3). This will always contain the
appropriate instruction, expressed in single-letter form, e.g. 'C' for
'Create', 'O' for 'Open', 'R' for 'Run' (i.e. when called from the Extras bar
and we aren't told explicitly which document to open) and 'X' for 'eXit' (i.e.
Close). Having gotten the initial instruction, one of the first things RMREvent
does is call ActionSystemEvent: to deal with it and set things in motion.
Find PROC ActionSystemEvent: in the main code:
PROC ActionSystemEvent:
IF SystemCommandLetter$=KCmdLetterCreate$
Create:(DocumentName$)
ELSEIF SystemCommandLetter$=KCmdLetterOpen$
Openfile:
ELSEIF SystemCommandLetter$=KCmdLetterRun$
Resumefile:
ELSEIF SystemCommandLetter$=KCmdLetterExit$
STOP
ENDIF
ENDP
Note that the procedure is basically just a set of IF...ELSE statements,
covering the four possibilities. By the way, RMR have chosen to simply STOP
dead when asked to by the system screen. In an application that saves its data
as it goes along, this might be fine, but in general it's good practice to make
a shutdown: procedure, giving you a place to put all those last minute tidying up
operations prior to the all-important STOP command.
For each system command, a different procedure is called. Let's take the
first as our example, Create:(DocumentName$). Find it in the main code.
Don't worry that the code here looks a bit inpenetrable, we'll step through it logically.
SETDOC File$ is a special OPL/32 command that tells OPL that the file
called file$ created immediately afterwards is to be treated as a
'system-screen-compliant' document file and given the right binary information
to show up with RMREvent's icon. CREATE command. Don't worry about all
the database bits that follow it, as we'll cover them in far more detail in a
future session. Suffice it to say that some information is added to the newly
created file. DocumentName$=File$ and LastUsed$=File$ Having successfully created our new file, it's
important to set the appropriate variables in the program to point to it as the
document currently being worked on. giPRINT "File created" is always a good idea. Whenever you do something major, e.g.
creating a new file, deleting an old one, switching files, changing the current
mode etc, it rarely hurts to tell the user about it discreetly with a giPRINT.
Even if you end up taking some of these statements out in the very final
version, they can help enormously during the development and testing phase. The
giPRINT command is especially useful during the debugging phase for reporting
progress and the value of variables as it doesn't alter any of the existing
graphics screens. So there we have it. One new file created, in theory. Verify that it actually works in the RMREvent example program and look for a new file with the RMREvent icon on the system screen. Tap on this file and watch the system screen launch the application. Neat, eh? 8-)
The code to open an existing document is similar, though slightly more involved as there are several choices and checks that need to be made. We'll come to that at a later date.
Associated with this technique of responding to the system screen's
instruction when starting up is the way RMREvent handles similar instructions
in the course of its routine operation. Go back to the top of the Run:
procedure we looked at in the last session.
The first IF clause should now make a bit more sense to you - I'll
paraphrase it slightly:
If the special 'command' event detected from the system
Get the complete command ('letter' and 'filename') from the system
with GETCMD$
Strip off the leftmost character (the command
letter) and set the rest as the document name to be used
Call
ActionSystemEvent: to process whatever the command said to do
(In case you were wondering, I can't work out the point of the next line at all, but it's not doing any harm so I'll leave it in! 8-) In fact, this is often a good principle when debugging or working on someone else's code: just because you don't understand a line of code doesn't mean that it can be safely deleted!)
Next week we'll return to the thorny subject of the toolbar and getting it to respond properly.
Go to next lesson | Programming index