The Absolute Beginners Guide to OPL

Part 9 - A helping hand with dialogs

---

Quite rightly, some people have commented that the "Press the Menu key to proceed" flashing gIPRINT I've used in my main loop is slightly at odds with the similar flashing messages which MiLo currently displays when "Help" or "About" are chosen from the main menu. The one tends to overwrite the other!

I hadn't worried too much about this 'feature' as I knew the "Help" and "About" messages were only temporary anyway. The time has come to flesh out those two procedures more thoroughly!

A very useful feature of OPL that we haven't yet touched on is the 'dialog'. Used throughout Psion's own applications, these '3D-effect' choice boxes can let us ask the user for information very quickly without having to write lots of code to record and handle what he or she types in. We'll deal with these 'question' dialogs in a future session, but I'd like to look at a special case.

The advantage of using a dialog to present (or ask for) information is that it 'floats' over the top of your existing display and can be removed again without having to redraw anything. One of OPL's dialog commands is dTEXT, used to simply display a line of text, and we'll use it to construct simple "Help" and "About" dialogs.

The general procedure for making a dialog always follows the same pattern:

1. Initialise the dialog with dINIT
2. Set up all lines (and questions) in the dialog
3. Define some buttons if required (e.g. "Cancel", "OK" etc)
4. Call the DIALOG up
5. Handle the values returned if necessary

Find the PROC about: line in your code and replace the gIPRINT by the following code:

LOCAL i%
dINIT "About MiLo"
dTEXT "","This is an example OPL program,"
dTEXT "","designed to run on OPL/16 and OPL/32,"
dTEXT "","from the 3-Lib web site."
dBUTTONS "OK",13
i%=DIALOG

Feel free to translate and run the program to try out the new "About" screen.

A few notes about the code you've just typed in:

1. Always use a title with dINIT if you're using OPL/32, as a blank line at the top of a dialog just looks silly. OPL/16 users needn't worry as the program just misses out a blank dialog title line.
2. The extra "", before each line of display text is needed. It's just the way the syntax of dTEXT works (see Psion's manual for a full explanation of all the possibilities).
3. You can display as many buttons at the bottom of the dialog as you want, though in practice you're usually limited to about 3 by the screen width of your Psion. Note that OPL/16 and OPL/32 buttons look slightly different, though they work in the same way.
4. The "13" after "OK" is the ASCII code for "Carriage Return" (i.e. the Enter key). The Psion knows this and puts up a label on the button telling the user what to press.
5. If the user decides to press Esc rather than Enter, the dialog still gets cleared from the screen but with i% set to zero rather than 13. In our trivial "About" screen example this doesn't make any difference, but in more advanced programs it's usually very handy to know whether the user pressed Enter to confirm the dialog or Esc to cancel it!

In the same way, we can make up a simple help screen. Move the cursor up a screens-worth and replace the gIPRINT in PROC help: with the following:

LOCAL i%
dINIT "Help"
dTEXT "","This is a very simple help screen."
dTEXT "","Use the -Generate numbers- menu command"
dTEXT "","as required and then use -Exit- to quit MiLo."
dBUTTONS "OK",13
i%=DIALOG

Translate and run as usual. The simple help message should appear in a similar way to our "About" screen:

It's worth noting that for any real-world programs any more complicated than MiLo you wouldn't use simple DIALOG boxes to display help screens. OPL/16 authors should use the special Help compiler utilities to make .RSC files than can be browsed through with the built-in Help engine and OPL/32 authors should use DATA itself, using a special predefined label setup and format. More of that in a later session, though.

If for any reason you've got your program code confused and wish to 'synchronise' with me, the MiLo code (as of the end of this session) is available here as a plain text file, milo9.txt.

See you next week, when we'll look at creating a Preferences screen where the user can make choices about how the program works.