87h MN$1DSP display one line menu
Input D register - Terminating bit-mask.
X register - Address of menu-list.
Output
A register -  Flag to indicate the type of contents in the X register.
If A register equals 0, X has the address of the subroutine associated with the item selected, else X points to the name of the selected item in the menu-list.
B register - Terminating key press.
X register - Depends on value of A register.
UTW_S0 - Number of the menu item selected (0 for first item).
Description

Displays a menu according to the specified menu-list at X, allowing the user to scroll through the menu using the arrow keys or by pressing the first letter of the item to be selected.

Does exactly the same as MN$DISP except that the menu is displayed in one line only and scrolls horizontally. The remaining 3 lines of the screen are left intact. The line which the menu is displayed will be the line containing the cursor in its current position, DPB_CPOS.

It is suggested that the followng DP$EMIT control codes be used to position the cursor:

24 - prints a dotted line (using UDG 2) on 2nd line and puts cursor on top line.
25 - prints a dotted line (using UDG 2) on 3rd line and puts cursor on bottom line.

Note that DPB_CPOS should not be poke'd directly.

The menu-list consists of item names (with leading byte-count), each followed by the address of an associated subroutine, or by 0.

The list is terminated by a name of length 0. The maximum name length is 16. The items are displayed (and numbered) in the same order as in the menu-list.

The error 202 is returned when

  • the menu-list is so large that the total number of characters displayed (including the spaces inserted for padding) exceeds 254, or
  • the menu has no items (ie. 0 in the first byte of the menu-list).

In the terminating mask, the n'th bit set corresponds to allowing termination on pressing key value n+1. For instance, bit 0 set corresponds to allowing termination on pressing the ON/CLEAR key, which has value 1. Bit 12 should always be set to allow termination by pressing EXE.

MN$1DSP exits when the user either

  • presses any of the keys specified by the bit-mask, or
  • selects by pressing its first letter, an item with a unique first letter, but only when the EXE key is also specified in the terminating bit-mask. (In this case, the terminating key press as if returned in B will be EXE, since MN$1DSP forces an exit as if EXE has been pressed too).

When the routine terminates, it returns in X the address of the subroutine corresponding to the item selected, unless this address is is 0. If it is 0 then the routine returns in X the address of the item's name in the menu-list. The B register is returned with the terminating key press, (or with EXE when terminating on pressing an item's initial letter). The A register is returned with 0 if the item had an associated subroutine address (non-zero), and otherwise A equals 1. UTW_S0 is returned with the number of the menu item, where 0 specifies the first item.

If the D register is passed as 0 then the routine will never exit as there will be no valid terminating character.

Also note that this routine puts the keyboard state into alpha shift.

The system variable MNB_CPTZ ($209C) is used to decide whether the menu should be capitalized or not when in 4-line mode. The default is 0, meaning that all menu's are capitalized. If it is 1, then all menu's are displayed exactly as they were stored.

An undocumented feature is that the menu routines use dpb_vsiz ($65) to hold the number of items in the menu and dpb_vlin ($64) to hold the currently selected one (0=first item etc).

LZ users, see also MN$XDSP and MN$TITL

This call is not available on CM/XP machines.

Example Displays a menu on the top-line only, scrolling horizontally.
        OS      UT$DISP
        DB      24,0            ;position cursor on top line
        LDX     #MENU_LIST      ;point to the menu-list
        LDD     #1000h          ;terminate on EXE only
        OS      MN$1DSP         ;call the service
        RTS

MENU_LIST:
        ASCIC   "FIND"
        DW      TL_FIND
        ASCIC   "SAVE"
        DW      TL_SAVE

        ...etc...

        DB      0
Errors 202 - menu error