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.7) 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.
Last time, we looked at calling the special printing routines built into Psion's printer.opx OPl eXtension. One thing you'll have noticed I didn't talk much about was how you actually put content into the special printing 'buffer' (ready to be previewed or printed) and we're going to rectify that now.
Locate the Printkey: procedure again:
Notice how both the main print lines are prefaced by a call
to an RMREvent procedure, simply called Print:. Don't be confused by the extra
colon in the middle of each line. We've seen this colon before, it's simply a
way of putting code that would normally be on two lines onto a single line
instead, for neatness sake. Using colons in this way is not normally
encouraged, but for very short lines in the middle of IF...ELSEIF...ENDIF sections it does
make for more compact and easier-to-understand source code.
Anyway, procedure Print: is the key to this session and the next thing
to find in the code:
Apart from ResetPrinting:, which we saw last week, RMREvent uses
five different calls to printer.opx routines, each performing a different task.
In all there are no less than 32 different routines available in the OPX and
it's well worth a browse through a reference that covers them in detail. I use
Tim Richardson's excellent
HLP-format OPL/32 database, which covers both the built-in OPL commands and the
Psion-produced OPXes.
Let's step through each of the five lines. Remember that we're simply
filling up a special buffer in the Psion's memory with text and images in a
logical order, nothing whatsoever gets formatted for (let alone sent to)
a printer until we exit this procedure and call PrintPreviewDialog: or PrintDialog:. You can
just think of the buffer as a 'virtual' piece of paper within the machine -
doing this will allow us to talk about the current 'insertion point', i.e. the
point on the imaginary page where text etc. would appear next.
SetFontName:("Courier") - The function here is obvious. Other valid choices of font
names might be "Arial" or "Times New Roman". Or, of course, other fonts if
installed using PsiWin, though this is a complex subject and definitely a
matter for elsewhere. SetFontHeight:(200) - For some reason, the font sizes used need to be specified
in 'twips'. No, I haven't heard of that word before, either! Apparently a twip
is 1/1440-th of an inch. Ah well. All printing routines end up being largely
trial and error anyway, to see what looks good on paper. SendStringToPrinter:("Printer Demonstration") - The bread and butter routine of the printing system, this
simply sends the specified text to the buffer using the font name and height
already set up. It's important to note that Psion's printer.opx routines are
quite intelligent and powerful - if your text should extend beyond the right
hand margin, word wrapping happens completely automatically. Neat. SendNewParaToPrinter: - As you'd expect from the name, this puts a 'virtual'
carriage return (line feed) into the 'virtual' buffer! In other words, the
insertion point is put at the start of the next blank line. SendBitmapToPrinter:(RMRId - The special name that each graphical object is assigned in an OPL program comes in useful for many things - not least here, as a way of telling the printing routines which bitmapped graphic to put in the buffer at the insertion point. Notice that when finally sent to the printer, the bitmap prints out very large. A more useful call in real life might be to SendScaledBitmapToPrinter:, which allows you to specify scale factors both horizontally and vertically (each from 0 to 1000 [0 to 100%]). Again, see a proper OPL/32 reference text for full details and syntax.
The complete set of printer.opx routines make up what is a
very powerful set of logical printing commands. They make it possible for
programmers to write Print: procedures without needing knowledge of the exact
printer the user will use.
Always remember that you're just filling up from the top a blank sheet of 'virtual' paper, you're NOT using a page description language like PostScript - in other words, you can't tell OPL exactly where on the paper you want each object and text string to go. The advantage of Psion's approach here is that the programmer doesn't really even need to know (within reason) what size paper the final printout will appear on, as the OPX routines handle final placement on the programmer's behalf.
Several people have asked whether I'll be publishing this series of tutorials in paper form. Well, it might happen, but don't hold your breath! When I get to the next useful break, I will bundle the tutorial files together into a single downloadable archive, for your convenience. In the meantime, thanks for all the positive feedback I've received and remember you can always show your appreciation in a practical way by registering some of my Series 3 and Series 5 programs...
Next week we'll examine creating icons for the RMREvent toolbar. See you then!
Go to next lesson | Programming index