!MENU - A Program Menu for the BBC Microcomputer

This document and the program described in it are copyright (C) 1989-1995, Angus J. C. Duggan.

A tar archive containing a PDF version of this document and the program itself is available from menu.tar.gz.

Contents

  1. Introduction
  2. Operation
  3. Menu format
  4. Calling the program
  5. Errors detected
  6. Memory usage
  7. Examples
  8. Bugs

Introduction

This document describes a machine code program which provides an easily configurable menu of the programs on a disc. The program program is normally called from the auto-boot file !BOOT by pressing SHIFT and BREAK together. When the program is called, it reads data from the current input stream (usually the *EXEC file from which it was called), and produces a menu of program titles which can be selected from using the cursor keys and RETURN.

Operation

The menu program is extremely simple to operate. When the menu display appears initially, the first entry is highlighted. The up and down cursor keys can then be used to move the highlight to the desired entry, and the return key can be used to execute it. If there are more choices than the screen can display, the message * * * more * * * is displayed at the top and/or bottom of the menu, depending on whether the highlight is at the top, middle, or bottom of the list. If the message disappears when a cursor key is pressed, there are no more entries to be found in that direction, and the highlight will move no further. At any time, the `S' key can be used to toggle the sound on and off, and an indicator on the bottom line of the display changes to show whether the sound is currently on or off. Note that some programs may turn the sound on when they are run, in which case this toggle will be ineffective.

Calling the program

!MENU program is normally called as the first line of a *EXEC file on auto-boot, but new menu entries can be tested by calling the program from the command line.

Menu format

The data which the program reads should be normal ASCII text with carriage returns at the end of each line. Files produced by VIEW or by *BUILD are suitable.

If the first character of a line is a backslash, then the rest of the line is ignored. This allows comments to be inserted into the configuration file. Blank lines and lines with only spaces and tabs are also ignored, and can be used to improve the readability of the file.

Lines which start with a space or a tab character and have other characters on them are command lines. When a program is selected from the menu, these lines define the commands which run the program. The commands can include complex operations such as loading multiple sections and relocating files. The command lines may include escaped characters, which will be translated into control characters when the command is executed. The escape symbol `|' is inserted into a command by doubling it to `||'. A maximum of ten command lines including both the common command lines and the menu selection command lines is allowed, and a minimum of one command line is imposed. There is a further restriction on the maximum number of characters in all the commands, which should be less than 238. This number does not include the leading spaces and/or tabs on the command lines, which are stripped off before execution.

All of the other lines which start with visible ASCII characters are title lines. These lines define the names of the menu selections, and of the title banner. Each title line precedes the commands which are associated with it.

The first title line in the input data is a special entry which defines a title banner that appears at the top of the screen in double height characters. The commands associated with the first title are common to all of the menu selections, and are executed before the entry's associated commands when the menu entry is selected. Titles may be a total of 32 characters long, including any spaces within them, and there can be a maximum of 64 titles, and a minimum of 2 titles (including the banner) in one menu.

The last line of the input data should contain a single full stop `.' and no more.

Errors detected

The program will detect some error conditions, including operating system errors. When an error is detected, the error message is printed, and the program tidies up cleanly before executing. The errors which can occur are:
Escape
This error should not happen, because the escape key is disabled by the program, but it is trapped anyway.
Line too long
This error happens when more than 256 characters are found without a carriage return separating them. This usually means that the input stream is corrupted.
No commands
If a menu entry is selected which has no associated commands, and there are none associated with the banner, this error occurs.
Title missing
This error happens if command lines are found before a title line has been found.
Title too long
This error occurs if a title line contains a title which is too long to fit on the screen. The maximum length of title lines is 32 characters.
Too few entries
There must be at least one selectable entry in the menu. This error occurs if there were too few titles found.
Too many commands
This error occurs if there were more than 10 commands given for a program, including the common banner commands.
Too many entries
This error happens if the configuration file contains more titles than are allowed. The limit is 64 titles, including the banner.

Memory usage

The auto-boot program is assembled at address &7000, and so should run on most BBC configurations, but its presence in this area may corrupt some language program areas. This is why one command is enforced for each selection, so that a language can be initialised safely. The configuration data is stored from OSHWM upwards, and should not cause any problems unless it is huge. The program uses the Econet workspace in &90-&9F, but this should not cause problems because the program is intended for disc based systems. Note that the user-defined keys 0-9 are also used and should not be redefined in the commands. Keys 10-15 can be defined if there is enough space for the definition.

Examples

A simple example of an *EXEC file is given to illustrate the points already discussed. 
*!MENU
\ Title of disc comes first
Demo Disc (C) AJCD 1986
\ All programs require escape enabled
*FX200

\ Titles of programs come next
\ Exit to VIEW
VIEW
\ use escape characters to change mode
        |V0
        *TV0 1
        *WORD
        *FX202 48

\ Exit to BASIC
BASIC
        *BASIC

\ And a demonstration of relocation
\ (only works if you have a *move command)
Countdown to Doom
        *BASIC
        *LOAD B.COUNT 1900
        *ROM
        *MOVE 1900 E00 +6400
        PAGE=&E00
        OLD
        RUN

\ end of demonstration file
.

Bugs

Centre justification can look untidy depending on the order of the filenames in the menu, and can be tidied up by adding spaces to the end of titles.
[Home] [Up]
Last modified on 12th February 2004 by angus@harlequin.com