13.16. MENUS/PROMPTS

About
Functions order

13.16.1. About MENUS/PROMPTS

13.16.2. MENUS/PROMPTS functions order

13.16.2.1. Function ACHOICE()

 ACHOICE(<nTop>, <nLeft>, <nBottom>, <nRight>,
 <acMenuItems>,
 [<alSelectableItems> | <lSelectableItems>],
 [<cUserFunction>],
 [<nInitialItem>],
 [<nWindowRow>]) --> nPosition

13.16.2.1.1. Arguments

<nTop>, <nLeft> and <nBottom>, <nRight> are the upper-
  left and lower-right window coordinates. Row values can range from zero
  to MAXROW() and column values can range from zero to MAXCOL().
  
<acMenuItems> is an array of character strings to display as the
  menu items. The individual menu items are later identified by their
  numeric positions in this array.
  
<alSelectableItems> is a parallel array of logical values--one
  element for each item in <acMenuItems>--that specify the selectable menu
  items. Elements can be logical values or character strings. ACHOICE()
  will not permit a null string and stops displaying if it encounters one.
  If the element is a character string, it is evaluated as a macro
  expression which should evaluate to a logical data type. In either
  case, a value of false (.F.) means that the corresponding menu item is
  not available, and a value of true (.T.) means that it is available. If
  you specify <lSelectableItems> instead of an array, false (.F.) makes
  all menu items unavailable and true (.T.) makes all menu items
  available. By default, all menu items are available for selection.
  
<cUserFunction> is the name of a user-defined function that executes
  when an unrecognizable key is pressed. Specify the function name as a
  character expression without parentheses or arguments. Note that the
  behavior of ACHOICE() is affected by the presence of this argument.
  Refer to the discussion below for further information.
  
<nInitialItem> is the position in the <acMenuItems> array of the
  item that will be highlighted when the menu is initially displayed. If
  you specify an unavailable menu item or no argument at all, the initial
  menu item is the first selectable item in the array.
  
<nWindowRow> is the number of the window row on which the initial
  menu item will appear. Row numbering begins with zero. By default, the
  initial menu item appears as close to the top of the window as possible,
  without leaving any empty rows at the bottom. Thus, if there are enough
  menu items following the initial one to fill up the window, the initial
  form will appear on the first row (row zero) of the menu. This function
  argument is used to control the initial menu appearance when there are
  more menu items than will fit in the window.
  
  As with all functions, optional arguments are omitted by using a comma
  instead of the actual argument.

13.16.2.1.3. Description

ACHOICE() is a user interface function that can create various kinds of pop-up menus. Each menu uses an array of character strings as menu items and a parallel array of logical values to determine whether items are selectable. When you invoke ACHOICE(), the list of menu items is displayed within the specified window coordinates. When the user presses Return, the current item is selected, and ACHOICE() returns the position of the menu item in <acMenuItems>. When the user presses Esc, ACHOICE() aborts and returns zero.

The menu items scroll if the number of items in <acMenuItems> exceeds the number of rows in the menu window, and the user attempts to move the highlight beyond the top or bottom of the menu window. Note that the highlight does not wrap when you reach the top or bottom of the list of items. Pressing the first letter does, however, wrap the highlight within the set of items whose first letter matches the key you press.

Navigating the menu: ACHOICE() has two modes depending on whether the <cUserFunction> argument is specified. If it is not specified the following navigation keys are active:

ACHOICE() Keys (No User Function)
 ---------------------------------------------------------------------
 Key            Action
 ---------------------------------------------------------------------
 Up arrow       Go to previous item
 Down arrow     Go to next item
 Home           Go to first item in menu
 End            Go to last item in menu
 Ctrl+Home      Go to first item in window
 Ctrl+End       Go to last item in window
 PgUp           Go to previous page
 PgDn           Go to next page
 Ctrl+PgUp      Go to the first item in menu
 Ctrl+PgDn      Go to last item in menu
 Return         Select current item
 Esc            Abort selection
 Left arrow     Abort selection
 Right arrow    Abort selection
 First Letter   Go to next item beginning with first letter
 ---------------------------------------------------------------------
 

Color: Menu items are displayed in standard color, the highlight in enhanced color, and the unavailable items in the unselected color. For example, the following color statement

SETCOLOR("W+/N, BG+/B, , , W/N")

displays a menu that is bright white on black, the highlight is bright cyan on blue, and the unavailable menu items are dim white on black.

User function: Like the other user interface functions, ACHOICE() supports a user function. The user function is specified when you want to nest ACHOICE() invocations to create hierarchical menus or to redefine keys.

When a user function is specified, ACHOICE() processes only a limited set of keys automatically. These are listed in the following table. All other keys generate a key exception which passes control to the user function for handling. Control is also passed to the user function when ACHOICE() goes idle (i.e., when there are no more keys to process).

ACHOICE() Keys (User Function Specified)
 ---------------------------------------------------------------------
 Key          Action
 ---------------------------------------------------------------------
 Uparrow      Go to previous item
 Dnarrow      Go to next item
 Ctrl+Home    Go to first item in window
 Ctrl+End     Go to last item in window
 PgUp         Go to previous page
 PgDn         Go to next page
 Ctrl+PgUp    Go to the first item in menu
 Ctrl+PgDn    Go to last item in menu
 ---------------------------------------------------------------------
 
When ACHOICE() executes the user function, it automatically passes the following three parameters:

- The current ACHOICE() mode

- The current element in the array of items

- The relative row position within the menu window

The mode indicates the current state of ACHOICE() depending on the key pressed and the action taken by ACHOICE() prior to executing the user function. The mode parameter has the following possible values:

ACHOICE() Modes
 ---------------------------------------------------------------------
 Mode    Achoice.ch     Description
 ---------------------------------------------------------------------
 0       AC_IDLE        Idle
 1       AC_HITTOP      Attempt to cursor past top of list
 2       AC_HITBOTTOM   Attempt to cursor past bottom of list
 3       AC_EXCEPT      Keystroke exceptions
 4       AC_NOITEM      No selectable items
 ---------------------------------------------------------------------
 

After the user function has performed whatever operations are appropriate to the ACHOICE() mode or LASTKEY(), it must RETURN a value requesting ACHOICE() to perform an operation from the following set of actions:

ACHOICE() User Function Return Values
 ---------------------------------------------------------------------
 Value   Achoice.ch     Action
 ---------------------------------------------------------------------
 0       AC_ABORT       Abort selection
 1       AC_SELECT      Make selection
 2       AC_CONT        Continue ACHOICE()
 3       AC_GOTO        Go to the next item whose first character
 matches the key pressed
 ---------------------------------------------------------------------
 

13.16.2.1.4. Example

 This example uses two literal arrays to specify the menu items
 and selection criteria.  After the menu is displayed and the user
 makes a selection, the name of the selected menu item is displayed:
 
 acMenuItems := {"One", "Two", "-------", "Three"}
 alSelectableItems := {.T., .T., .F., .T.}
 nPosition := ACHOICE(10, 10, 12, 15, acMenuItems,;
 alSelectableItems)
 ? acMenuItems[nPosition]
 
 This example declares an array of menu items and supplies a
 user-defined function which displays a message with each highlighted
 choice:
 
 #include "achoice.ch"
 #include "inkey.ch"
 
 PROCEDURE Main()
 
 LOCAL acMenuItems[4], cUserFunction, nRetVal
 LOCAL nKey, nPos
 
 acMenuItems[1] := "Add"
 acMenuItems[2] := "Edit"
 acMenuItems[3] := "Delete"
 acMenuItems[4] := "Update"
 
 CLS
 
 nPos := ACHOICE( 10, 10, 13, 15, acMenuItems,;
 .T., "cUserFunction" )
 DO CASE
 CASE nPos == 1
 //  Put ADD routine here
 CASE nPos == 2
 //  Put EDIT routine here
 CASE nPos == 3
 //  Put DELETE routine here
 CASE nPos ==4
 //  Put UPDATE routine here
 ENDCASE
 
 RETURN
 
 
 FUNCTION cUserFunction( nMode, nCurElement, nRowPos )
 
 LOCAL nRetVal := AC_CONT     // Default, Continue
 LOCAL nKey := LASTKEY()
 
 DO CASE
 // After all pending keys are processed, display message
 CASE nMode == AC_IDLE
 DO CASE
 CASE nCurElement == 1
 @ 22, 5 SAY " Adding   "
 CASE nCurElement == 2
 @ 22, 5 SAY " Editing  "
 CASE nCurElement ==  3
 @ 22, 5 SAY " Deleting "
 CASE nCurElement ==  4
 @ 22, 5 SAY " Updating "
 ENDCASE
 
 nRetVal := AC_CONT            // Continue ACHOICE()
 
 CASE nMode == AC_HITTOP          // Attempt to go past Top
 TONE( 100, 3 )
 CASE nMode == AC_HITBOTTOM       // Attempt to go past
 // Bottom
 TONE( 100, 3 )
 
 CASE nMode == AC_EXCEPT          // Key Exception
 DO CASE
 CASE nKey == K_RETURN         // If RETURN key, select
 nRetVal := AC_SELECT
 CASE nKey == K_ESC            // If ESCAPE key, abort
 nRetVal := AC_ABORT
 OTHERWISE
 nRetVal := AC_GOTO      // Otherwise, go to item
 ENDCASE
 ENDCASE
 
 RETURN nRetVal
 
 The next example declares the arrays, specifies a selection
 condition for one of the menu items, and supplies a user function:
 
 EXTERNAL UPDATED
 //
 FUNCTION MyMenu
 LOCAL acMenuItems[4], alSelectableItems[4],;
 cUserFunction := "DoIt"
 //
 acMenuItems[1] := "Add Record"
 acMenuItems[2] := "Edit Record"
 acMenuItems[3] := "Delete Record"
 acMenuItems[4] := "Update Record"
 //
 alSelectableItems[1] := .T.
 alSelectableItems[2] := .T.
 alSelectableItems[3] := .T.
 alSelectableItems[4] := "!UPDATED()"
 // Selection condition
 
 RETURN ACHOICE(10, 10, 12, 15, acMenuItems,;
 alSelectableItems, cUserFunction)
 
 This example uses two arrays to specify menu items and
 corresponding action blocks.  After the menu is displayed and the
 user makes a selection, the ACHOICE() return value is used to
 determine which action block of the aActionItems array is evaluated:
 
 PROCEDURE Main()
 LOCAL nChoice
 LOCAL aMenuItems := { "Add Record   ", ;
 "Edit Record  ", ;
 "Delete Record", ;
 "Update Record"   }
 
 LOCAL aActionItems := { {|| AddFunc()  }, ;
 {|| EditFunc() }, ;
 {|| DelFunc()  }, ;
 {|| UpdFunc()  }  }
 
 nChoice := ACHOICE( 10, 10, 13, 22, aMenuItems )
 
 IF nChoice == 0
 QUIT      // ESCAPE was pressed
 ENDIF
 
 EVAL( aActionItems[nChoice] )
 
 RETURN

13.16.2.2. Function ALERT()

 ALERT( <cMessage>, [<aOptions>] ) --> nChoice

13.16.2.3. Function FT_ACH2TB()

 FT_Ach2tb( <nToprow>,<nTopcol>[,<nBotrow>][,<nBotcol>],<aArrey>,     ;
 [<cBoxtype>],[<cBoxcolor>],[<cBoxtitle>],[<nTitlePos>],        ;
 [<cUselcolor>],[<cTitlecolor>],[<cBarcolor>],[<cHkcolor>],     ;
 [<lShadow>],[<lExecute>],[<nMsgrow>],[<nMsgcol>],              ;
 [<cMsg.color>],[cElevbar],[cEbarcolor],[<cEbarside>],          ;
 [<cNoSelcolor>],[<cTagch>],[<nStartelem>],[<lRscreen>],        ;
 [<nTimeout>],[<nTimeoutval>],[<cUserfunc>] )
 --> nOption
 

13.16.2.3.1. Arguments

<nToprow> is the top row of the box to be drawn. Required.
  
<nTopcol> is the top column of the box to be drawn. Required.
  
<nBotrow> is the bottom row of the box to be drawn. The default is
<nToprow>+Len(<aArrey>)+1 or maxrow()-2, whichever is less.
  
<nBotcol> is the bottom column of the box to be drawn. The default
  is <nTopcol>+width of the widest element in <aArrey> +2.
  
  It's been pointed out that the number of commas required to default
  the <nBotrow> and <nBotcol> params. is at least slightly confusing.
  So, some documentation on the requirements:
  Default both: 7,9,, ARRAY:
  Default <nBotrow>, specify <nBotcol>: 7,9,,20 ARRAY:
  Default <nBotcol>, specify <nBotrow>: 7,9,15, ARRAY:
  
<aArrey> is the arrey of options to present to the user. Each
  element can hold as many as five subelements, or as few as one.
  Required. Additional documentation below.
  
<cnBoxtype> is the type of box to draw. Uses DispBox(). The
  default is a double-line box.
  
<cBoxcolor> is the color with which to draw the box. The default is
  Setcolor().
  
<cBoxtitle> is title of the box drawn on <nToprow>. The default is
  no title.
  
<nTitlepos> is the starting column position (to the right of
<nTopcol>) at which to draw <cBoxtitle>. The default is 1.
  
<cUselcolor> is the color with which to draw unselected options.
  The default is Setcolor().
  
<cTitlecolor> is the color with which to draw the box title. The
  default is yellow on red.
  
<cBarcolor> is the color with which to draw the selection bar.
  The default is yellow on black.
  
<cHkcolor> is the default color with which to draw the hotkeys for
  for each option. This is used when no hotkey color is supplied
  in <aArrey>. The default is hiwhite on the current background
  color.
  
<cShadow> is a character string, either "L" or "R" (for left or
  right) to designate the side of the box where a shadow will appear.
  Leave this NIL to avoid drawing a shadow. You might also leave
  this NIL if you choose to use a .C or .ASM shadow function, which
  is a good idea. Shadoww(), included below, is flat-out SLOW.
  
<lExecute> turn on/off execution of option when first letter is
  pressed. Rule: setting in element 5 of each <aArrey> subarray
  overrides <lexecute>. If that element is left NIL, the <lexecute>
  setting is used. If <lexecute> is not passed and element 5 is NIL,
  auto execution is turned ON.
  
<nMsgrow> is the row on which to draw a message for each option.
  The default is two rows below the bottom of the box.
  
<nMsgcol> is the column at which to draw a message for each option.
  The default is <nTopcol> +2. To CENTER the message, pass "C".
  
<cMsgcolor> is the default color with which to draw messages. This
  color is used when element 4 of each <aArrey> subarray is left NIL.
  The default is Setcolor().
  
<cElevbar> is the ASCII character to use as the elevator bar drawn
  on the box. Leave this NIL to draw no elevator bar.
  
<cEbarcolor> is the color with which to draw the elevator bar.
  This is ignored if <cElevbar> is NIL.
  
<cEbarside> is a character string, either "L" or "R" (for left or
  right) to designate the side of the box on which to draw the
  elevator bar. This is ignored if <cElevbar> is NIL.
  
<cNoselcolor> is the color with which to draw unselectable options.
  The default is white on black.
  
<cTagchar> is the ASCII character to use to draw tags that would
  appear to the right of each option. The default is *DIS*abled
  tagging. The default tag is chr(251).
  
<nStartelem> is the number of the option where the selection bar
  will first be placed. Leave this NIL to begin at option 1.
  
<lRestscrn> is a logical to designate whether or not the screen
  coordinates occupied by the box and/or shadow should be restored
  before FT_Ach2tb() returns. The default is .T.
  
<nTimeout> is the number of seconds after which FT_ACH2TB() will
  timeout and return to the function/proced. which called it. The
  default is 0.
  
<nTimeoutVal> is an optional alternative numeric value FT_ACH2TB() will
  RETURN when/if it times out. The default is the current element
  number.
  
<bUserfunc> is a code block containing a function call to be
  executed after each key press. You need to write just two formal
  parameters to allow the run-time passing of the key pressed and the
  current element number, e.g.:
  { |key,num| Myfunc( key,num [,other params.] ) }
  Unlimited extra parameters may be passed. Of course, make certain
  to also write 'receptors' for them in 'Myfunc()' itself...as in the
  above example. The default is NO user function.
  

13.16.2.3.3. Description

FT_Ach2tb() is a greatly enhanced, fully featured, and now mouse- supported replacement for Achoice(), based on a Tbrowse object. Each element of <aArray> (the array you pass to it) is itself an array. Each element can solely composed of "Option" (below), but may be composed as follows to take full advantage of the function's features:

Option , Message ,HotKeyPos,HotKeyColor,Selectable { "Utilities","System Utilities", 3 ,"+gr/b" ,.T. }

All elements except for the first, the option itself, are optional. IF 'Message' is NIL, no message is displayed. 'HotKeyPos' is the position within 'Option' of the hotkey. In the example above, the hotkey for 'Utilities' is the first 'i', i.e., at position 3. The default is 1. 'HotKeyColor' is the color to use for the hotkey display. The default is hiwhite on the current background color. 'Selectable' is a logical indicating whether or not that option can be selected. The default is .T.

The A_CHOICE() UDC in FT_ACH2T.CH makes using FT_ACH2TB() a breeze. The myriad of parameters can be written in any order. Only <nToprow>, <nTopcol>, and <aArrey> are required. See the example below.

There may be some confusion over 'unselected' and 'unselectable' options. The former refers to any option not currently covered by the selection bar. The latter refers to options you have designated unselectable in subelement 5 of <aArray>, i.e., by writing .F.

To enable tagging, pass any ASCII character as <cTagchar>. To tag/untag all options, press [SPACE]. To tag/untag individual options, press [+] and [-] respectively. On press of [+], browse moves to the next element in the display. To test for the tagged status of an option, use the WAS_TAGGED() UDC in FT_ACH2T.CH. To check the entire array for tags, use Aeval() in conjunction with Was_Tagged() as in the example below. When tagging is enabled, the string "Tags" will be written across the bottom row of the box in hiwhite on the current background color.

Because FT_ACH2TB() takes over the [SPACE],[+], and [-] keys, it saves any SET KEY procedures you might have set them to, and restores same on returning. Any other procedures you might have SET KEYs to will fly when FT_ACH2TB() is called...thanks to the Inkey() replacement, SKINkey().

The pice de resistance of FT_ACH2TB() is its ability to execute a user function designed entirely by you. It is called after each keypress, and because it is completely open-ended, extends the the reach of FT_ACH2TB() to the limits of Clipper. See the docu- mentation under <bUserfunc> above.

Test compile: CLIPPER ft_ach2t /n/w/m/dFT_TEST Test link : RTLINK FI ft_ach2t LIB nanfor /pll:base50

Mouse support

Mouse support is provided via the Nanforum Toolkit FT_M* functions. Most actions are tied to the left button. The equivalent of pressing [Esc] comes via the right button. These left button clicks will produce the designated actions:

Mouse cursor outside box : K_ENTER (select option)

Mouse cursor at box top left corner : browse:goTop()

bottom left corner : browse:goBottom()

top right corner : browse:pageUp()

bottom right corner : browse:pageDown()

Mouse cursor at option, tagging ENabled

Selection bar moves to option, subsequent press to tag or untag. Do this for as many options as you want to tag/untag, then move mouse cursor outside the box. Press again to select. Tagging overrides <lExecute>, so with tagging on and <lExecute> .F., subsequent presses while inside the box coordinates simply tag/untag.

Mouse cursor at option, tagging DISabled

IF <lExecute> is turned on, the option is immediately selected. If turned off, selection bar moves to option. Press again to select.

To Disable Mouse Support

Compile with /dNOMOUSE

13.16.2.4. Function FT_ADDER()

 FT_Adder()

13.16.2.4.3. Description

PopAdder() gives you an adding machine inside your Clipper 5.2 application. It has the basic functions add, subtract, multiply, and divide. You may move it from one side of the screen to the other. It even displays a scrollable tape, if you want it.

There are a few HOT Keys while using the Adder:

<D>ecimals - change # of decimals <M>ove - the Adder from right display to left <T>ape - turn the Tape Display On or Off <S>croll - the tape display <DEL> --- -- 1st Clear entry -- 2nd Clear ADDER <ESC> - Quit <F10> - return a <TOTAL> to the active get

A couple of notes about the adder:

1.) It was designed to be used on an Enhanced keyboard with separate <DELETE> key. <DELETE> is used to clear the adder. However, it will still work on a Standard keyboard.

2.) You do not have to display the tape. You may turn it on at any time by pressing <T>. You may SCROLL back through the tape once there are more than 16 entries in the adder, by pressing <S>.

3.) To Quit the Adder just press <ESC>. To return your Total to the application press <F10>. The adder will place the Total in the active GET variable using oGet:VarPut(). The adder will only return a Total to a numerical GET!

4.) There are many support functions that you might find interesting. They are part of my personal library, but are necessary to the operation of the adder. You might want to pull these out to reduce the overall size of the adder. Many are worth at least a little time studying.

5.) To make FT_Adder a Hot key from inside your application at the beginning of your application add the line:

SET KEY K_ALT_A TO FT_Adder

This will make <ALT-A> a key "Hot" and permit you to Pop - Up the adder from anywhere in the application.

6.) If you use FT_INKEY(), you can even have active hotkeys in an INKEY().

13.16.2.6. Function FT_BRWSWHL()

 FT_BRWSWHL( <aFields>, <bWhileCond>, <cKey>,                  ;
 [ <nFreeze> ], [ <lSaveScrn> ], [ <cColorList> ], ;
 [ <cColorShadow> ], [ <nTop> ], [ <nLeft> ],      ;
 [ <nBottom> ], [ <nRight> ] -> nRecno

13.16.2.7. Function FT_CLRSEL()

 FT_ClrSel( <aClrData>, [ <lClrMode> ], [ <cTestChr> ]  -> aClrData

13.16.2.7.1. Arguments

<aClrData> is an array of subarrays, with each subarray containing
  information about the colour settings.
  
  The subarray has the following structure:
  
  [1] cName is the name of this colour setting i.e. "Pick List"
  Maximum length is 20 bytes
  
  [2] cClrStr is the current colour string
  Default is "W/N,N/W,N/N,N/N,N/W"
  
  If Setting type is "M" (Menu) the colours are...
  1. Prompt Colour
  2. Message Colour
  3. HotKey Colour
  4. LightBar Colour
  5. LightBar HotKey Colour
  
  Note: While there are many ways to code the individual
  colour combinations, they should be in the same
  format that gets returned from SETCOLOR(), so
  the defaults can be found in the colour palette.
  
  foreground [+] / background [*]
  i.e. "GR+/BG*, N/W*, N+/N, , W/N"
  
  [3] cType is the type of colour setting
  Default is "W" (Window)
  
  T = Title Only 1 colour element
  D = Desktop Background colour and character
  M = Menu For FT_Menuto() style menus
  W = Window Windows with radio buttons
  G = Get For use with @ SAY...
  B = Browse For tBrowse() and *dbEdit()
  A = aChoice Pick-lists etc...
  
  W/G/B/A are functionally the same but will provide
  a more appropriate test display.
  
  [4] cFillChar is the character (for desktop background only)
  Default is CHR(177) " "
  
  
<lClrMode> .T. use colour palette
  .F. use monochrome palette
  
  Default is the ISCOLOR() setting
  
<cTestChr> 2 Byte character string for colour test display
  
  Default is the CHR(254)+CHR(254)
  

13.16.2.8. Function FT_DISPMSG()

 FT_DISPMSG( <aMessageArray>, [ <cKey2Check> ],
 [ <nTopBoxRow> ], [ <nLeftBoxColumn> ],
 [ <cnBoxType> ], [ <lShadow> ] ) -> lKeyMatch

13.16.2.8.1. Arguments

<aMessageArray> is a multidimensional array of messages to be
  displayed and the color attributes for each message.
  
  The first dimension of the array contains one or more elements,
  each representing one line in the message box, up to the maximum
  number of rows on the screen.
  
  Within each line of the message individual characters or groups
  of characters may be delimited with braces ([]). The braces will
  be stripped out and the character(s) inside those braces will be
  highlighted.
  
  The second dimension of the array contains a color attribute for
  the corresponding element in dimension one, plus one additional
  element for the color of the box border. Dimension two will
  always contain one more element than dimension one. If an
  attribute is omitted, the last color selected will be used.
  
<Key2Check> is a character string of one or more keys to check
  for. If omitted, the message is displayed and control is returned
  to the calling procedure. If one character is specified,
  FT_DISPMSG() waits for one keypress, restores the screen and
  returns. If multiple characters are specified, FT_DISPMSG()
  remains in a loop until one of the specified keys has been
  pressed, then restores the screen and returns.
  
<nTopBoxRow> is the upper row for the message box. If omitted, the
  box is centered vertically.
  
<nLeftBoxColumn> is the leftmost column for the box. If omitted, the
  box is centered horizontally.
  
<cnBoxType> is a string of characters or a variable for the box
  border. See the DISPBOX() function. If omitted, a double box is
  drawn.
  
<lShadow> is a logical variable. If true (.T.) or omitted, it
  uses FT_SHADOW() to add a transparent shadow to the box. If
  false (.F.), the box is drawn without the shadow.

13.16.2.9. Function FT_FILL()

 FT_FILL( <aSubArrayName>, <cMenuSelection>, <bFunction>,
 <lSelectable> ) -> NIL

13.16.2.10. Function FT_MENU1()

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

13.16.2.10.4. Example

 // 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.

13.16.2.11. Function FT_MENU2()

 FT_MENU2( <aMenuarray> [, <cColors> ] ) -> NIL

13.16.2.13. Function FT_PENDING()

 FT_PENDING ( <cMsg>, [ <nRow> ], [ <nCol> ], ;
 [ <nWait> ], [ <cColor> ] ) -> NIL

13.16.2.15. Function FT_PROMPT()

 #include "FTMENUTO.CH"
 
 @ <nRow>, <nCol> PROMPT <cPrompt>                     ;
 [COLOR <cColor>]                     ;
 [MESSAGE <cMessage>]                 ;
 [MSGROW <nMsgRow>]                   ;
 [MSGCOL <nMsgCol>]                   ;
 [MSGCOLOR <cMsgColor>]               ;
 [TRIGGER <nTrigger>]                 ;
 [TRIGGERCOLOR <cTriggerColor>]       ;
 [HOME <nHome>]                       ;
 [END <nEnd>]                         ;
 [UP <nUp>]                           ;
 [DOWN <nDown>]                       ;
 [LEFT <nLeft>]                       ;
 [RIGHT <nRight>]                     ;
 [EXECUTE <bExec>]                    ;
 

13.16.2.15.1. Arguments

<nRow> is the row at which the prompt is to appear.
  
<nCol> is the column at which the prompt will appear.
  
<cPrompt> is the menu item string.
  
<cColor> is optional and is the color attribute of the prompt. Note
  that two colors are required; one for the standard setting and one
  for the enhanced setting (i.e. the light bar color). See the example
  below if this isn't clear. If <cColor> is not specified then the
  current SetColor() value is used by default.
  
<cMessage> is optional and is the message associated with the
  prompt. If not specified, then no message will be displayed.
  
<nMsgRow> is optional and is the row at which the message, if any,
  will appear. If not specified, the default is the current setting
  of the SET MESSAGE TO command.
  
<nMsgCol> is optional and is the column at which the message, if
  any, will appear. If not specified, the default is either zero or
  centered, depending on the current setting of the CENTER option of
  the SET MESSAGE TO command.
  
<cMsgColor> is optional and is the color attribute of the message.
  If not specified, the default is the same as the prompt color.
  
<nTrigger> is optional and is the position within the prompt string
  where the trigger character is located. If not specified, the
  default is one.
  
<cTriggerColor> is optional and is the color attribute of the trigger
  character. Note that two colors are required; one for the standard
  setting and one for the enhanced setting (i.e. the light bar color).
  See the example below if this isn't clear. If <cTriggerColor> is not
  specified then the default is the same color as the rest of the
  prompt.
  
<nHome> is optional and specifies which prompt becomes active
  when the home key is pressed. If not specified, the default is
  the first prompt.
  
<nEnd> is optional and specifies which prompt becomes active
  when the end key is pressed. If not specified, the default is
  the last prompt.
  
<nUp> is optional and specifies which prompt becomes active
  when the up arrow key is pressed. If not specified, the
  default is the previous prompt. The current setting of SET
  WRAP TO is obeyed.
  
<nDown> is optional and specifies which prompt becomes
  active when the down arrow key is pressed. If not
  specified, the default is the next prompt. The current
  setting of SET WRAP TO is obeyed.
  
<nRight> is optional and specifies which prompt becomes
  active when the right arrow key is pressed. If not
  specified, the default is the next prompt. The current
  setting of SET WRAP TO is obeyed.
  
<nLeft> is optional and specifies which prompt becomes
  active when the left arrow is pressed. If not specified,
  the default is the previous prompt. The current setting of
  SET WRAP TO is obeyed.
  
<bExec> is optional and is a code block to evaluate whenever
  the menu item to which it belongs is selected.

13.16.2.16. Function FT_SLEEP

 FT_SLEEP( <nSeconds>, [<nInitial>] ) -> nil

13.16.2.17. Function FT_XBOX()

 FT_XBOX( [ <cJustType> ], [ <cRetWait> ], [ <cBorType> ],   ;
 [ <cBorColor> ], [ <cBoxColor> ], [ <nStartRow> ], ;
 [ <nStartCol> ], <cLine1>,  <cLine2>, <cLine3>,    ;
 <cLine4>, <cLine5>, <cLine6>, <cLine7>, <cLine8> ) -> NIL