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.
Before we start, several people have complained that there's no longer the 'excitement' of building a program week-by-week. The point is that although we're not adding to it line by line, the example program we're gradually working through is not just a trivial example but a fully working template for a professional OPL/32 application. Any building on top of this template will be to add real functions to make it into a useful program and will usually be done by you, the programmer, once you feel sufficiently expert. In fact, I'll probably lead you through a simple set of additions in future sessions, just to get you off to a flying start, and hopefully the people missing the 'excitement' will then be happier! 8-)
We dealt with a simple menu back in the days of our trivial MiLo program. What we're about to handle is somewhat more complicated but very much following the same principles.
Look back in the Action_Pen_or_Keypress: procedure and notice that there are two Key&
values for which the procedure Display_Menu: gets called. A moment's thought will
give you the answer. The first is the event code returned when the Menu key is
pressed and the second is that for the Menu command icon on the side of the
screen. Both are equally valid of course!
Jump ahead now a few lines, to the Display_Menu: procedure itself.
It's only a short bit of code. As before mINIT just starts OPL thinking that
you're about to define some menu 'cards' (columns of options).
Before we go further, press Menu in your own OPL program
editor and note the way the File menu card works. Both 'Printing' and 'More'
are gateways to 'cascade menus', little sub-menus which can be easily and
logically grouped together. We're going to try and duplicate this behaviour in
RMREvent.
Back in the code, note the mCASC keyword. The way it works is to
define the contents of the cascade first, followed by the menu card which is to
contain it, with a suitable placeholder to tell OPL exactly where to put the
cascade. The 'placeholder' here is the title of the cascade, i.e. "Printing".
Note the next line, which includes the phrase:
"Printing>",-16,
In the context of a menu option definition, the ">" character is a special flag character that tells OPL to look for an already-defined cascade that has a title matching the bit before the character ">" and to insert it in this place in the menu card.
Note also that we use -16 as the unique code to be returned. In
fact, nothing can actually be returned by the cascade itself, but only by one
of the sub-menu options within it. But OPL/32 won't let us get away with
putting in zero or a blank here, so we have to give it a value. -16 is as good
as any and has the advantage that it's a 'non-printing character' (i.e. not a
recognisable character on the standard ASCII chart) and so will show up without
a tell-tale short-cut code next to the option. Which is what we want.
Start up the RMREvent application again and press Menu:
In addition to verifying that the "Printing" cascade works
properly, browse through the rest of RMREvent's menu structure. Do you notice
how closely the layout and shortcut-keys used match those of the built-in EPOC
programs? Making your programs behave in as standard a way as possible will
ease users' learning curves and ultimately win you more friends (and sales!).
Most programmers implement Control-e to Close their application, but often
don't go much further. There are standard keypresses for Zoom in, Zoom out,
Show toolbar, Help, About etc, so make sure that you use them!
Notice the end of the View menu card:
Remember that Toolbar%, like most other 'on or off' parameters
in RMREvent, can be either set equal to KTrue% or KFalse% (-1 or zero
respectively). When false (i.e. the toolbar is 'off' and not showing), the
bracket equates to 0 and nothing untowards happens. When true (i.e. the toolbar
is currently 'on'), the bit in brackets is +1 and the hexadecimal value $2800
gets logically OR-ed to the %t short-cut value. All of this is just one
big OPL/32 'trick' that you need to make a note of. The $2800 magic number just
adds a leading tick-mark to the menu option, as you'll see if you do a bit of
experimenting in RMREvent. Don't worry if you don't quite understand the
significance of the number, or of how the logical OR works. Neither do I! The
important thing is to make a note that there is a trick so that you can copy
and paste from this example when you need it for real.
A few more minor notes:
Key& is set in the penultimate line to the value returned by
MENU minus 96. This little numerical trick is all part of RMREvent's
key-handling eccentricities and was covered a few sessions ago. MENU is called with a parameter, Minit%, which is only ever used
here in this one place. What is the point in a parameter which is never used, I
hear you cry? The answer is that it's the mechanism whereby MENU remembers
which menu option you last used and presents it as the default when you enter
the menu system the next time. Very useful, and a sign of a professional
program. Control%=KTrue% simply ensures that the key value returned by this
procedure is treated in the rest of the program in the same way as if Control
plus the appropriate short-cut key had been pressed. Next week we'll look at the extremely thorny subject of printing from OPL.
Go to next lesson | Programming index