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.
We finished the last lesson by touching on the APP...ENDA section that
starts the RMREvent example application. We're now going to examine it in more
detail.
Note the number that follows the application name. For EPOC
(and thus for OPL/32 on the Series 5), Psion wanted to do away with the
sensible (but fairly old-fashioned) DOS file extension system (.TXT, .WRD, .SPR
etc). They came up with a system of Unique IDentifiers (UIDs), the idea being
that each application has its own unique number which is stamped into the front
of all files created by it. In this way, the operating system knows which icon
to display next to each file. Of course, many programs (especially games and
reference) don't actually create files, but the principle is still enforced and
every Series 5 program is supposed to use a different UID, allocated by
Psion/Symbian from their EPOC World site.
Email them for UIDs for your own programs and note that if you ask nicely you
can get a block of ten numbers to save you pestering them again!
The ICON line (obviously) just tells OPL which graphic
icon to use when constructing the translated application file. At its simplest
an icon is just a 48x48 EPOC picture file, often given the file extension .MBM,
standing for MultiBitMap. To do things properly though, you also need to
specify another bitmap of the same size, called the 'mask', which tells the
system screen how much of the icon's area to leave transparent. Both the main
icon and the mask can be created in SKETCH and exported as EPOC pictures. In
theory, you also have to create 32x32 and 24x24 pixel versions so that the
system screen has something to display at different zoom levels, but EPOC does
its best to do the right thing most of the time and in practice a 48x48 version
of the icon is all that's needed. The system screen itself does some fancy
resizing if need be.
OPL/32 is flexible enough that you can either use ICON
several times, one for each icon or mask, or use their DOS BMCONV tool to build
the different bitmaps into a true Multi BitMap file. It's up to you. I normally
just use a single 48x48 bitmap for quick and dirty programs and a pair of
ICON lines to cope with the icon and mask of more serious applications.
The FLAGS 1 line is a standard command that tells EPOC that the
application is allowed to create new files. It therefore then appears in the
system screen's "New file" dialog as one of the options. If your program
doesn't use document files of any kind you can normally just miss this line
out. There's one more OPL/32 command that you'll sometimes find in this
section: CAPTION, but it's too advanced to go into here.
And now for something completely different. And rather
clever. You'll remember that in the MiLo program we used several constants,
i.e. variables whose value we set right at the start of the program. These give
us the flexibility to change their value easily and conveniently without having
to search out and replace multiple instances throughout the program. Well, the
CONST command is one step further in the same direction. Rather than use a
variable, which might get changed by accident, declaring a constant with
CONST ensures that nothing OPL will ever do will change its value.
RMR have used constants in the Event example program in two useful ways. The order's important, so pay attention! Firstly, a standard .OPH file is INCLUDEd. As you might imagine, INCLUDing lists of definitions from pre-prepared header files is an excellent way of saving having to define the same old constants again and again in each program you write. Psion ship several such header files in the Series 5 ROM, including the ones used in RMR Event right here. Any files with .OPH after them tend to just be lists of CONSTANTS (you can make your own if you like) and files ending in .OXH tend to be lists of procedures found in EPOC's OPX library system, i.e.extra functions that people have programmed to extend the standard capabilities of OPL/32. Don't worry about OPXes for now, we'll cover them in a lot more detail later on.
If you would like to take a look at CONST.OPH, just use OPL/32's menu
option "Create standard files". When browsing through it, you'll note that
Psion tend to be quite terse with their constant names and it's not always
obvious what each one refers to. Which is why the RMR Event program goes on
(after the OXH includes) to define its own versions of some of these constants,
in much clearer english! Remember, you can call constants whatever you like as
at the end of the day as they're only shortcuts to standard numbers, saving you
from having to remember and quote them in the main body of your programs.
For example, RMR rightly decided that Program_To_Foreground was a lot
clearer to understand than the rather 'techy' KEvFocusGained. Anyway, don't panic
whenever you see a name/function you don't recognise in the main code, remember
to check the header files and CONSTant sections at the top of the program -
it may just be a reference to a number that the author's defined for extra
convenience.
The particular constants re-defined here are mainly some of the 'magic' numbers that OPL/32 uses to tell different types of event from each other, and using these english names will make your event loops (much more of that later on, too!) a lot easier to understand.
Next week, we'll look at defining an OPL/32 toolbar. See you then!
Go to next lesson | Programming index