FT_MENU1()
 Pulldown menu system
------------------------------------------------------------------------------

 Syntax

      FT_MENU1( <acBarNames>, <acOptions>, <acAction>,
                <acColors> [, <nTopRow> ], [ <lShadow> ] ) -> NIL

 Arguments

     <acBarNames> is a character array containing the names to appear
     on the menu bar.

     <acOptions> is a multi-dimensional array with one element for each
     selection to appear on the pulldown menus.

     <acColors> is an array containing the colors for the menu groups.

     <nTopRow> is a numeric value that determines the row for the menu
     bar.  If omitted, it defaults to 0.

     <lShadow> is a logical variable.  If true (.T.) or omitted, it
     uses FT_SHADOW() to add a transparent shadow to the each
     pulldown menu.  If false (.F.), the menu is drawn without
     the shadow.

     All arguments except nTopRow and lShadow are required.

 Returns

     NIL

 Description

     FT_MENU1() is a function that displays a pulldown menu for each item
     on the menu bar and executes the corresponding function for the item
     selected.  When a called function returns false, FT_MENU1 returns
     control to the calling program.

     Valid keystrokes and their corresponding actions:

     Home             -  Activates Pulldown for first item on the menu bar
     End              -  Activates Pulldown for last item on the menu bar
     Left Arrow       -  Activates next Pulldown to the left
     Right Arrow      -  Activates next Pulldown to the right
     Tab              -  Same as Right Arrow
     Shift-Tab        -  Same as Left Arrow
     Page Up          -  Top item on current Pulldown menu
     Page Down        -  Bottom item on current Pulldown menu
     Enter            -  Selects current item
     Alpha Character  -  Moves to closest match and selects
     Alt-<Key>        -  Moves to corresponding menu bar item
     Escape           -  Prompts for confirmation and either returns to
                         the calling routine or resumes

 Examples

     // Declare arrays
     LOCAL aColors  := {}
     LOCAL aBar     := { " ENTER/EDIT ", " REPORTS ", " DISPLAY " }

     // Include the following two lines of code in your program, as is.
     // The first creates aOptions with the same length as aBar.  The
     // second assigns a three-element array to each element of aOptions.
     LOCAL aOptions[ LEN( aBar ) ]
     AEVAL( aBar, { |x,i| aOptions[i] := { {},{},{} } } )

     // fill color array
     // Box Border, Menu Options, Menu Bar, Current Selection, Unselected
     aColors := IF( lColor, {"W+/G", "N/G", "N/G", "N/W", "N+/G"}, ;
                            {"W+/N", "W+/N", "W/N", "N/W","W/N"} )

  // array for first pulldown menu
  FT_FILL( aOptions[1], 'A. Execute A Dummy Procedure' , {|| fubar()}, .t. )
  FT_FILL( aOptions[1], 'B. Enter Daily Charges'       , {|| .t.},     .f. )
  FT_FILL( aOptions[1], 'C. Enter Payments On Accounts', {|| .t.},     .t. )

  // array for second pulldown menu
  FT_FILL( aOptions[2], 'A. Print Member List'         , {|| .t.},     .t. )
  FT_FILL( aOptions[2], 'B. Print Active Auto Charges' , {|| .t.},     .t. )

  // array for third pulldown menu
  FT_FILL( aOptions[3], 'A. Transaction Totals Display', {|| .t.},     .t. )
  FT_FILL( aOptions[3], 'B. Display Invoice Totals'    , {|| .t.},     .t. )
  FT_FILL( aOptions[3], 'C. Exit To DOS'               , {|| .f.},     .t. )

     Call FT_FILL() once for each item on each pulldown menu, passing it
     three parameters:

        FT_FILL( <cMenuSelection>, <bCodeBlock>, <lSelectable>

     <cMenuSelection> is a character string which will be displayed on
      the pulldown menu.

     <bCodeBlock> should contain one of the following:

        A function name to execute, which in turn should return .T. or .F.
        FT_MENU1 WILL RETURN CONTROL TO THE CALLING PROGRAM IF .F. IS
        RETURNED OR CONTINUE IF .T. IS RETURNED.

        .F. WHICH WILL CAUSE FT_MENU1 TO RETURN CONTROL TO THE CALLING
        PROGRAM.

        .T. WHICH WILL DO NOTHING.  THIS ALLOWS THE DEVELOPER TO DESIGN A
        SKELETON MENU STRUCTURE PRIOR TO COMPLETING ALL OF THE SUBROUTINES.

     // CALL FT_MENU1
     FT_MENU1( aBar, aOptions, aColors, 0 )

     NOTE: FT_MENU1() disables Alt-C and Alt-D in order to make them
           available for the menu bar.  It enables Alt-D and resets
           Alt-C to its previous state prior to calling each function.

 Source: MENU1.PRG

 Author: Paul Ferrara