Click above to get retro games delivered to your door ever month!

LITE_MENU2()

    LITE_MENU2() is extremely similar to LITE_MENU(), with the following
    important differences:

    . It supports messages for each menu option.
    . It supports different colors for each message.
    . You can attach an action block to each menu option, which will
      then be executed if that option is selected.
    . You can initially highlight a menu option other than #1.
    . You can display a "ticking" clock, or continuously execute any other
      function, as you wait for the user to make a selection.
    . You can specify a time-out period which saves the screen or executes
      a specified function after a given period of inactivity.
    . You can specify a WHEN clause for each menu option.
    . You can specify global colors for the menu.
    ... and best of all, it uses standard Clipper syntax!!

    Note: You must include the file GRUMPM.CH in your program to use this
    function!!

    Syntax for @..PROMPT

    @ <r>, <c> PROMPT <prompt> [MESSAGE <message>] [WHEN <when>]      ;
               [MESSAGECOLOR <msgcolor>] [ACTION <action> [TO <var>] ];
               [TRIGGERCOLOR <trigcolor>] [DISPLAY]

    Required Parameters

    <r> and <c> are numerics representing the row and column at which
    to display the menu item.

    <prompt> is a character expression representing the menu item.
    To specify an alternate trigger letter, simply precede the desired
    letter with a tilde ("~") in the <prompt>.  See the sample below.

    Optional Parameters

    <message> is a character expression representing the message to be
    displayed when the corresponding menu option is highlighted.

    <when> is a Clipper expression that evaluates to a logical value.
    If the expression tests True, the menu option will be selectable;
    if False, it will not.

    <msgcolor> is a character string representing the color in which to
    display <message>.

    <action> is the name of a function to be called if the corresponding
    menu option is selected. Do not enclose this in quotes.  If you use
    the <action> clause, you can optionally save the return value from
    that function to a variable by using the TO <var> syntax.  Note that
    <var> should be declared prior to this statement.  (See below for
    an example of this usage.)

    <triggercolor> is a character string representing the color to use
    for highlighting the trigger letters.  If you do not use this,
    the trigger letters will be displayed in the high intensity
    equivalent of the unselected color.  Note that this <triggercolor>
    applies to each individual menu option, and overrides the global
    <triggercolor> below.

    The DISPLAY keyword causes the menu option to be displayed
    immediately.  By default, menu options are not displayed until the
    MENU TO statement is invoked.

    Syntax for MENU TO

    MENU TO <variable> [COLOR <cColor>] [INITIAL <nInitial>] [CLOCK] ;
             [EVENT <event>] [TIMEOUT <timeout>] [EXITEVENT <exit>]  ;
             [TRIGGERCOLOR <trigcolor>] [LEFT <left>] [RIGHT <right>] ;
             [PULLDOWN] [SAVE]

    Required Parameter

    <variable> is the name of the variable to be assigned the result of
    the menu operation.  This will be numeric, corresponding directly to
    the menu item selected.  If the user presses Esc, the value returned
    from LITE_MENU2() will be zero.

    Optional Clauses

    The optional COLOR clause allows you to specify the color in which
    to display the menu options. The format is:

                "<color1>,<color2>,[<color3>]"

    The <color1> color specification will be used for unselected
    options. The high intensity equivalent of <color1> will be used to
    display the trigger letters for each unselected menu option, so I
    suggest that you do not use a high intensity color.

    <color2> will be used for the currently selected option.

    Optional parameter <color3> will be used for any unavailable menu
    options. If you do not use this, the default will be gray on black.

    If you choose not to use the COLOR clause, the current SETCOLOR()
    setting will be used. The standard setting will be used for
    unselected options, enhanced will be used for selected options, and
    unselected will be used for unavailable options. For example, if the
    current color setting is "W/N,+W/N,N/N,N/N,N/W", unselected menu
    options will be displayed in white on black.  The trigger letters
    will be high white on black unless you use the <triggercolor>
    clause. The currently selected menu option will be high white on
    black. Any unavailable menu options will be displayed in black on
    white.

    Optional clause INITIAL allows you to highlight a menu option other
    than the first.  The default is one (1).

    Optional clause CLOCK will display a continuously "ticking" clock
    during the menu display.  The clock will be displayed at the top
    right corner in the current color.  If you wish to change these
    defaults, use the EVENT clause.

    (The function GFClock() is used to display the clock.  It can be
    found in the source file LITEMEN2.PRG.)

    Optional clause EVENT is similar to CLOCK, except that it allows
    you to specify any event to be continuously executed during the
    menu display.  For example, if you want to change the display
    characteristics of the clock to display at the bottom left in
    white on blue, you could use the following clause:

    EVENT gfclock(maxrow(), 0, 'w/b')

    Optional clause TIMEOUT will either call your exitevent (see below)
    or invoke the Grumpfish planetarium screen saver if the user does
    not press a key within the specified number of seconds.

    Optional clause EXITEVENT specifies a function that will be called
    in the event of an inactivity timeout.  If you do not specify this,
    the screen will be saved using the BlankScr3() function.

    Optional clause TRIGGERCOLOR specifies the color to use for
    highlighting trigger letters.  This serves as the global default
    for all menu options, and can be overridden by specifying the
    TRIGGERCOLOR clause for individual menu options (with @..PROMPT).

    Optional clauses LEFT and RIGHT specify character strings that will
    be stuffed into the keyboard buffer if the left or right arrows are
    pressed within the MENU TO keypress loop.  Because these will most
    often be used in conjunction with a pulldown menu system, you can
    instead simply specify the PULLDOWN clause.  This will stuff an
    <<ESC + Left Arrow + Enter>> combination if you press the Left
    arrow, and <<ESC + Right Arrow + Enter>> if you press the Right
    arrow.

    Optional clause SAVE will cause your Menulist array to be retained
    rather than cleared.  In most circumstances you will not need to
    do this.  However, if you are pre-building your arrays for use with
    Lite_Menu2() rather than using the alternate @..PROMPT command,
    then you may have a use for this.

    Notes

    The beauty of LITE_MENU2() is that it adds so much functionality to
    the basic menu, whilst allowing you to continue using the same
    familiar Clipper syntax.

    As with LITE_MENU(), LITE_MENU2() will append a plus sign onto the
    color setting to display the trigger letter.  Therefore, passing a
    high intensity color as your unselected color is totally senseless.

    LITE_MENU2() supports the following keys:

    Up Arrow - move up one option, or if at first option, jump to
               last option (thus effectively simulating SET WRAP ON)

    Down Arrow - move down one option, or if at last option, move
                 to first option

    Home - jump to first option

    End - jump to last option

    Enter - select highlighted option and exit

    Esc - exit and return zero

    Minor Caveat

    In the same fashion that Clipper 5.0 carries around a PUBLIC
    variable GETLIST for GETs, LITE_MENU2() needs to use the variable
    MENULIST. Therefore, to avoid compiler warnings, I recommend that
    you include this line of code at the top of your program:

       local menulist := {}

    Dynamic Menu Options

    It is entirely possible to have menu prompts that change at
    run-time based upon global settings and the like.  However, if you
    prepare your arrays ahead of time for use with LITE_MENU2()
    (rather than using the replacement @..PROMPT directive), you
    cannot simply rely upon a function call to change the prompt, as
    shown below:

    { 1,1," Toggle Me " + if(whatever(), chr(251), chr(32)),,, ;
    { || toggle()}, }                                           

    Therefore, if LITE_MENU2() detects menu prompts that contain code
    blocks rather than character strings, it will evaluate them to
    determine the prompt. The following code snippet shows how you
    would rephrase the above example in the form of a code block:

    { 1,1, { || " Toggle Me " + if(whatever(), chr(251), chr(32)) },,,;
    { || toggle()}, }                                                  


    Sample Usage

    #include "grumpm.ch"                                              
    local menulist := {}, sel, sec_level := 0, x                      
    @ 10, 20 PROMPT 'Data entry' MESSAGE 'Enter data' ;               
                                 MESSAGECOLOR '+W/B' ACTION dataent() 
    @ 11, 20 PROMPT 'Reports' MESSAGE 'Output data' ACTION reps() TO x
    @ 12, 20 PROMPT 'Invoices'   MESSAGE 'Get money!' ;               
                                 MESSAGECOLOR '+W/R' ACTION inv()     
    // note: trigger letter for next option will be "F"               
    @ 13, 20 PROMPT 'Reindex ~Files' ACTION maint()                   
    // note: trigger letter for next option will be "S" and           
    // will only be selectable by users with a security level above 0 
    @ 14, 20 PROMPT 'Dumb ~Stuff' WHEN sec_level > 0 ACTION dumbstuf()
    @ 15, 20 PROMPT 'Quit'                                            
    // highlight 2nd option, display clock, save screen after 5 mins. 
    MENU TO sel CLOCK INITIAL 2 TIMEOUT 300 TRIGGERCOLOR "n/bg"