Topic       : The GFA-Basic Compendium
Author      : GFA Systemtechnik GmbH
Version     : GFABasic.HYP v2.98 (12/31/2023)
Subject     : Documentation/Programming
Nodes       : 899
Index Size  : 28056
HCP-Version : 3
Compiled on : Atari
@charset    : atarist
@lang       : 
@default    : Document not found
@help       : Help
@options    : +g -i -s +z
@width      : 75
@hostname   : STRNGSRV
@hostname   : CAB     
@hostname   : HIGHWIRE
@hostname   : THING   
View Ref-FileON MENU GOSUB proc
MENU m$()
MENU OFF
MENU KILL
MENU x,y
MENU x,text$

proc: procedure name
m$(): string-array
x, y: iexp
text$: sexp

These commands are responsible for generating and managing a menu, and are
supported by the commands and variables in the previous section (ON MENU,
MENU()).

With ON MENU GOSUB proc, the procedure to which control will be passed on
selection of a menu entry is determined. If an accessory is currently open, the
procedure will not be called. Within the procedure, which menu entry was
selected can be found by using the variable MENU(0). MENU(0) is the index of
the selected entry in the array of the entries m$(), and m$(MENU(0)) indicates
the text clicked on the menu if OPTION BASE 0 is currently selected. If OPTION
BASE 1 has been chosen, then the text of the selected item is in m$(MENU(0)+1).

The command MENU m$() puts the menu onto the screen. The string array m$()
contains the headings, entries and reserved space for the accessories. The
following format must be used during the arrangement of the entries in the
array m$():

    m$(0)          Heading of the first menu in which accessories can exist.

    m$(1)          Name of the first entry in the first menu.

    m$(2)          A line of minus signs.

    m$(3) - m$(8)  Reserved space for accessories. These elements need only be
                   a single character long, as their contents are ignored. If
                   an accessory was loaded when the computer was switched on,
                   this will take up one of these strings. Otherwise they will
                   not be printed.

    m$(9)          An empty string, which marks the end of the first menu.

All further menus have the following format:

    1. Heading of the menu.
    2. List of the menu entries.
    3. An empty string which marks the end of the menu.

After the last menu another further empty-string marks the end of the entire
Pull-down-menu. A menu entry which begins with a minus sign is represented but
is not selectable and is shown in light text.

MENU OFF returns a menu title to 'normal video' display mode. (After an item is
chosen from a menu, the menu title is displayed in inverse video).

MENU KILL deactivates a menu but does not, however, remove the menu title list
from the screen. In addition MENU KILL turns off the ON MENU GOSUB options.

With the MENU x,y instruction the x-th entry in a menu can be given certain
attributes. The numbering of the entries corresponds to the indexing of the
array of menu entries, counting from zero and including titles, entries for
Accessories and null strings ("").

The second parameter y specifies the attribute to be given, or removed from,
the x-th menu entry as follows:

    y  Effect
    0  Checkmark to be removed, if present, from in front of a menu item
    1  Checkmark to be placed in front of a menu item -> ✓
    2  Menu item to be made non-selectable, and printed in light characters
    3  Menu item to be made selectable, and written in normal characters

With the MENU x,text$ instruction the x-th entry of a menu can have it's text
altered. The numbering of the entries corresponds to the indexing of the array
of menu entries, counting from zero and including titles, entries for
Accessories and null strings ("").

Sample Pull-down menu program:

    DIM entry$(20)
    DATA "Desk","  Test "
    DATA ----------------,1,2,3,4,5,6,""
    DATA "File","  Load ","  Save "
    DATA ---------,"  Quit ",""
    DATA "Titles","  Entry 1 ","  Entry 2 ",""
    DATA End
    '
    i%=-1
    REPEAT
      INC i%
      READ entry$(i%)
    UNTIL entry$(i%)="End"
    entry$(i%)=""
    '
    MENU entry$()
    ON MENU GOSUB evaluate
    OPENW 0
    '
    REPEAT
      ON MENU
    UNTIL MOUSEK=2
    '
    PROCEDURE evaluate
      MENU OFF
      ' MENU(0) contains array index of selected item
      m%=MENU(0)
      PRINT entry$(m%)
      '
      ALERT 0,"Checkmark before item?",0," Yes | No ",a%
      IF a%=1
        MENU m%,1
      ELSE
        MENU m%,0
      ENDIF
      '
      ALERT 0,"Lightened characters?|(Not selectable)",0," Yes | No ",a%
      IF a%=1
        MENU m%,2
      ELSE
        MENU m%,3
      ENDIF
    RETURN

--> A menu is created and monitored. When a menu item is selected, its text is
    printed and the user is asked first if it is to be checkmarked, and then
    whether it should be 'non-selectable' or not.

Memo: Menu titles are limited to 10 characters.
      Menus don't display correctly in N.Aes if hidemenu=true. This happens in
      the editor or compiled.
      The library does not honor the character width returned from
      graf_handle() and assumes 8. However the editor is ok.
      The MENU m$() commmand is limted to 18 titles.
        Object count is limited to 200 entries.
        String space is limted to about 4000 bytes.
        Internally calls MENU KILL if an menubar is already active.

      MENU x,y will accept any value for y and not complain.

      All the MENU commands will do nothing if no menu bar is active.
      No error will be issued, they are simply ignored.

menu_bar()+, menu_tnormal()+, menu_icheck()+, menu_ienable()+, menu_text()+