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.6) of the RMREvent program from the RMR web site before reading through this tutorial. If you use an older version, some of the text may not make sense.
If there are still any OPL/16 programmers reading this, a brief apology is in order. I said almost ten lessons ago that it would be quite easy to adapt the examples for the Series 3 range - well, it seems I was largely wrong, with almost every clever snippet being peculiar to OPL/32 and/or EPOC. Rest assured, though, Alan Richey and I have made plans for a special 16-bit RMREvent example, and you should see the first tutorial based on it by Christmas. In the meantime, hang in there and absorb what you can!
We look this week at the thorny subject of printing from OPL. Although
OPL's always had a trivial (but useful, especially when 'debugging') LPRINT
command, anything more complicated usually involves some clever footwork. In
order to get print preview, page setup etc, OPL/16 authors need to seek out a
third party printing addon. OPL/32 programmers have it much easier, with Psion
supplying all the main bits you need in the ROM, in the form of a special
'printer.opx' library file.
Start up RMREvent again and look in detail at the 'Printing' menu cascade:
Notice that the example uses all the standard EPOC printing
components and that they even work properly (try it with a printer attached and
see)! I said a while ago that we'd return to OPXes in more detail and I think
that time is upon us. An OPX (it stands for 'OPl eXtension') is just a set of
clever C++ library routines that Psion or third party authors have made
available to us OPL/32 programmers to extend the possibilities of what OPL
itself can do. In most cases, the functions and commands in an OPX are used
almost exactly like the built-in OPL commands, making them a doddle to use. The
only thing we have to do in our applications is to to 'include' the special
'header file' for the OPX right at the top of our code. Look again at the first
few lines of RMREvent:
INCLUDE "CONST.OPH"
INCLUDE "PRINTER.OXH"
INCLUDE "SYSTEM.OXH"
INCLUDE "DBASE.OXH"
Notice that the first item quoted is of type .OPH, which stands for 'OPl Header file' and just contains a list of constants that Psion thought might be useful. The other three are true .OXH ('Opl eXtension Header files') and each refer to a set of library routines in the appropriate .OPX in the Series 5 ROM.
Printer.opx, as you'd expect, contains functions that have to with printing; System.opx handles tricky system things like starting and stopping other processes, turning off sound etc; and Dbase.opx contains advanced database handling routines (more of that much, much later).
In a previous session, you created local copies of the 'OPL standard files' from the ROM. One of them should be 'printer.oxh', so open it up now and have a browse:
Notice that an OPX header file normally contains two types of
line. Firstly there are extra constant definitions that are peculiar to the
function of the OPX. And secondly there are the extra functions themselves,
e.g. InsertSpecialChar:(character%, pos Don't worry about understanding all the different parameters to all the different functions, you'll probably only ever need a small fraction of them and can work them out as you go along. For now, just make a mental note of the sort of thing available. It includes support for text and its various attributes, plus simple bitmaps. If you want to graduate to line graphics, shaded boxes and the like, you'll need to get a copy of Andy Clarkson's gprinter.opx (but I'll cover that another time). Text is fine for this session though, so move on with me through the program. Find the Printkey: procedure:
This procedure is called when the program's received a
Key& key event (or menu equivalent) that it considers might be relevant to
printing. Within the code, each valid print-related key code is checked and
acted upon. If the supplied Key& event doesn't match, the ONERR OFF: RETURN line just
returns OPL back to the main event-handling routines.
PageSetupDialog:, PrintRangeDialog:, PrintPreviewDialog: and PrintDialog: are all standard functions in
printer.opx and handle the basic page layout, range printing, print previewing
and printing of the text and image information placed in the printing 'buffer'
by the user. This buffer is an area of memory in the operating system which can
be used to store information ready for printing. For example, a more advanced
program might copy a bitmapped logo and several paragraphs of text into the
buffer. The user then selects 'Print preview' and verifies that the layout is
correct, before going for a final print, at which time the contents of the
buffer are moved to the specified printer. For the purposes of the RMREvent
example, its Print: procedure just puts a simple line of text in the buffer
(you might like to seek out this code and examine it - we'll be covering
exactly how the filling of the buffer happens in a future lesson).
A few things for you to note:
ResetPrinting: function just clears everything from the buffer and is a
useful thing to do (just in case) before creating new content in the
buffer ONERR to trap a serious problem with the printing
routines (e.g. the printer was 'off-line' or not plugged in). Normally, this
sort of problem is a real pain to handle reliably, but the technique used here
works well. Essentially, the ONERR command says to OPL "Look, if a serious
error happens between now and when I say 'ONERR OFF', don't terminate the
program with a loud error message, just tell me instead and I'll take care of
things!". Any problems encountered thus send the program to the Printquit:: label,
where the special error handling can be turned off, a relevant error message
flashed up and things then carry on as normal 
Experiment with these functions in your own program. It's not
hard to add printing support to most applications and may just give them the
final 'professional touch' you've been looking for.
Next week, we'll look at exactly how to create content for the printing buffer. Then the week after that, we'll examine creating icons for the RMREvent toolbar. See you then!
Go to next lesson | Programming index