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.
You may remember we touched on the subject of OPL graphics and 'drawables' as early as lesson 8 in this series. I'd like to revisit it with our OPL/32 focus firmly switched in and with a view to finding out how RMREvent manages to get a pretty icon to appear on its toolbar. Start the program and have a look at the toolbar in detail.
Because this is an example program, Alan's only
bothered to set up one icon (for the 'Find' button), but the principle is of
course exactly the same for the other three.
Most EPOC programs tend to get their images from ".MBM" files. Standing for 'MultiBitMap', the file type is essentially a compressed archive of one or more 'EPOC pictures'. For example, a game might have a single archive called GRAPHICS.MBM containing 30 or 40 icons, game elements and assorted pictures, all appended together within the one file. Putting graphics together in this way saves disk space (because of cluster size problems) and reduces the number of files that your application needs (not strictly needed, but the smaller the number of support files, the more elegant the program will seem).
You'll have noted in the OPL manual/book/help file that the gLOADBIT
command has an optional mystery third parameter, usually referred to as index%
or id%. This is where it's possible to tell OPL which bitmap you wish to
load from a Multi-BitMap file. The number is usually expressed as an offset
from the start of the file, e.g. the first bitmap would have an offset of 0,
the second an offset of 1 etc.
Jump ahead in the RMREvent code to the Init: procedure, and find the
lines:
Icon$=Path$+"RMREvent.mbm"
IF Device:(Icon$)
Icon$=Dev$+Icon$
Upid&=gLOADBIT(Icon$,0,0)
Downid&=gLOADBIT(Icon$,0,1)
Sliderid&=gLOADBIT(Icon$,0,2)
FindId&=gLOADBIT(Icon$,0,3)
RMRId&=gLOADBIT(Icon$,0,7)
ELSE
ALERT ("MBM file not found")
STOP
ENDIF
This is a good model to follow in handling the bitmaps in
your program. We start by setting up a string variable to point to where the
.MBM file archive is supposed to be and then check that it exists (bringing up
an error if it doesn't, of course!) Don't worry about how the Device: procedure
works for now, we'll come back to that in a lot more detail at a later date.
Suffice it to say that it checks for a file in the given folder on each disk on
the machine and returns 'False' if it doesn't find it.
Notice how each drawable in the program is loaded up from the main
Icon$ file by quoting an offset. It's at this point that you'll start wanting
to take a look inside the RMREvent.mbm file, to examine its contents. Several
programs are available to do this. Try MBMView or PicSee in the first instance
and see how you get on. It's important to notice that the bitmaps in the
Multi-BitMap archive don't have to be the same size (thus the RMR logo at
offset 7 is much bigger than the Find icon at offset 3).
Having loaded the icon for the Find button into the drawable
FindId&, the next stage is to tell the toolbar about it. In
lesson 26 we first saw the TBarButt: routine and
concentrated on the first, alphabetic, character (which tells the program which
procedure to call should that button ever get pressed). Move down a few lines
and take a look at the button setup code again:
TBarButt:("a",1,"",0,One&,One&,0)
TBarButt:("b",2,"Find",0,FindId&,FindId&,0)
TBarButt:("c",3,"Yes\No",0,Three&,Three&,0)
TBarButt:("d",4,"Raise"+CHR$(10)+"Error",0,Four&,Four&,0)
The second parameter to the TBarButt: routine is, of course,
just the number (from the top) of the button being set up. Just as obviously,
the third parameter is the text label to be printed next to the icon, though
note that you have no control over the font used and will have to keep your
label very short. If you really need more space you can embed a 'line feed'
character (ASCII 10) in the label, like this:
TBarButt:("b",2,"Find"+chr$(10)+"Next",0,FindId&,FindId&,0)
Next up in the list of parameters comes the 'state' you want the button to start up in, i.e. raised or depressed. If you're not sure, just leave this at zero ('raised').
Finally we come to mention the drawables we so caringly set up earlier.
The TBarButt: routine actually asks for two drawables. The first for the bitmap
itself, and the second for a 'mask'. A mask is a special bitmap that can 'mask
out' bits of the original image if needed. The handling of masks was discussed
in lesson 21. For most purposes, just quote the
drawable name twice and the icon then gets masked with itself, which (by
definition) leaves it untouched.
The final parameter is an advanced flag, which we need not concern ourselves with here - just leave it at zero.
You should now understand how to get a bitmap from a MultiBitMap file onto a standard toolbar button. There's one vital piece of the jigsaw I haven't touched on, though. How do you get pictures into an MBM file in the first place? The most common is to use the BMCONV tool that Psion supply on the PsiWin 2.x CD. I've no space here for a BMCONV tutorial, but check out Phil Spencer's web pages, which have some hints and tips for getting the best out of it. See also TechTopics in issue 20 of Palmtop magazine, which covers SIBO and EPOC picture conversion.
Next week we'll take a deep breath and have a look at how RMREvent has tackled the tricky subject of scrollbars.
Go to next lesson | Programming index