MENUS/PROMPTS

Function ACHOICE()

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

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

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

 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

Function ALERT()

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

The ALERT() function creates a simple modal dialog. It is useful in error handlers and other "pause" functions. The user can respond by moving a highlight bar and pressing the Return or SpaceBar keys, or by pressing the key corresponding to the first letter of the option. If <aOptions> is not supplied, a single "Ok" option is presented.

ALERT() is sensitive to the presence or absence of the xClipper full-screen I/O system. If the full-screen system is not present, ALERT() uses standard I/O to display the message and options tty-style (i.e., 80-column, without word wrap, each line ended with carriage return/linefeed).

  This example demonstrates use of an alert dialog box.  First,
 the array of options is defined, the ALERT() function gets the user's
 selection, and finally, the user's choice is handled with a DO
 CASE...ENDCASE control structure:
 
 #define AL_SAVE         1
 #define AL_CANCEL      2
 #define AL_CONT         3
 
 // Define an array of options
 aOptions := {"Save", "Don't Save", "Continue"}
 
 // Display the dialog box and get the user's selection
 nChoice  := ALERT("File has changed...", aOptions)
 
 // Handle the user's request
 DO CASE
 CASE nChoice == AL_SAVE
 ? "Save"
 CASE nChoice == AL_CANCEL
 ? "Don't Save"
 CASE nChoice == AL_CONT
 ? "Continue"
 OTHERWISE
 ? "Escape"
 ENDCASE
 //
 RETURN
 
 

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
 

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

 nOpt := A_CHOICE( 7,9,, ARRAY:t_array )   // the minimum
 
 nOpt := A_CHOICE( 7,9,, ;
 ARRAY:t_arrey ;
 USERFUNC:{|a,b| UserFunc(a,b,any1)};
 BOXTYPE:B_SINGLE  ;
 BOXTITLE:title  ;
 SHADOW:"FT" ;
 TAGCHAR:chr(17) ;
 REST_SCREEN:.F. ;
 AUTOEXEC:.F. ;
 MES_COLOR:MSG_COLOR ;
 ELEVBAR:'|' ;
 NOSELCOLOR:"bg/n" ;
 MES_COL:"C" )
 
 Check only the RETURNed element for whether tagged:
 IF( Was_Tagged(chr(17),t_arrey,nOpt), MoreProcessing(), )
 
 Check entire 't_arrey':
 Aeval( t_arrey,{|e,n| IF( Was_Tagged(chr(17),t_arrey,n ), ;
 MoreProcessing(t_arrey),NIL ) } )
 
 

Function FT_ADDER()

 FT_Adder()

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().

Function FT_BLINK()

 FT_BLINK( <cMsg>, [ <nRow> ], [ <nCol> ] ) --> NIL

A quick way to blink a msg on screen in the CURRENT colors. Restores colors on return.

 FT_BLINK( "WAIT", 5, 10 )   // Blinks "WAIT" in current colors @ 5,10
 
 @5,10 SAY "WAIT - Printing Report"
 FT_BLINK( "..." )           //  Blink "..." after wait message...

Function FT_BRWSWHL()

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

This is a demonstration of TBrowse with a WHILE condition for an indexed database.

 * This example will only show those people with last name of "JONES"
 * in the TBNames.dbf which contains at least the fields:
 * Last, First, City AND is indexed on Last + First.
 LOCAL nRecSel    := 0
 LOCAL aFields    := {}
 LOCAL bWhile     := {||TBNames->Last = "JONES"}
 LOCAL cKey       := "JONES"
 LOCAL nFreeze    := 1
 LOCAL lSaveScrn  := .t.
 LOCAL cColorList := "N/W, N/BG, B/W, B/BG, B/W, B/BG, R/W, B/R"
 LOCAL cColorShad := "N/N"
 
 USE TBNames INDEX TBNames NEW // indexed on Last + First
 
 * Pass Heading as character and Field as Block including Alias
 * To eliminate the need to use FIELDWBLOCK() function in FT_BRWSWHL()
 AADD(aFields, {"Last Name" , {||TBNames->Last}  } )
 AADD(aFields, {"First Name", {||TBNames->First} } )
 AADD(aFields, {"City"      , {||TBNames->City}  } )
 
 IF FT_BRWSWHL( aFields, bWhile, cKey, nFreeze, lSaveScrn, ;
 cColorList, cColorShad, 3, 6, MaxRow() - 2, MaxCol() - 6) == 0
 ? "Sorry, NO Records Were Selected"
 ELSE
 ? "You Selected: " + TBNames->Last +" "+ ;
 TBNames->First +" "+ TBNames->City
 ENDIF

Function FT_CLRSEL()

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

This function allows users to select their own colour combinations for all the different types of screen I/O in a typical application. This facilitates an easy implementation of Ted Means' replacement of the @..PROMPT/MENU TO found in the NanForum Toolkit. If you are not using FT_MENUTO(), you can specify "A" for setting type and have a normal colour string returned.

 LOCAL aClrs   := {}
 LOCAL lColour := ISCOLOR()
 LOCAL cChr    := CHR(254) + CHR(254)
 
 SET SCOREBOARD Off
 SETBLINK( .F. )       // Allow bright backgrounds
 
 *.... a typical application might have the following different settings
 *     normally these would be stored in a .dbf/.dbv
 aClrs := {;
 { "Desktop",        "N/BG",                         "D", " " }, ;
 { "Title",          "N/W",                          "T"      }, ;
 { "Top Menu",       "N/BG,N/W,W+/BG,W+/N,GR+/N",    "M"      }, ;
 { "Sub Menu",       "W+/N*,GR+/N*,GR+/N*,W+/R,G+/R","M"      }, ;
 { "Standard Gets",  "W/B,  W+/N,,, W/N",            "G"      }, ;
 { "Nested Gets",    "N/BG, W+/N,,, W/N",            "G"      }, ;
 { "Help",           "N/G,  W+/N,,, W/N",            "W"      }, ;
 { "Error Messages", "W+/R*,N/GR*,,,N/R*",           "W"      }, ;
 { "Database Query", "N/BG, N/GR*,,,N+/BG",          "B"      }, ;
 { "Pick List",      "N/GR*,W+/B,,, BG/GR*",         "A"      }  ;
 }
 
 aClrs := FT_ClrSel( aClrs, lColour, cChr )

Function FT_DISPMSG()

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

FT_DISPMSG() is a multi-purpose pop-up for user messages. Multiple lines may be displayed, each with a different attribute. The box will be automatically centered on the screen, or the row and/or column can be specified by the programmer. It also centers each line of the message within the box.

 The following example displays a simple two-line message
 and returns immediately to the calling routine.
 
 FT_DISPMSG( { { "Printing Report"                    , ;
 "Press [ESC] To Interrupt" }         , ;
 { "W+/B*", "W/B", "GR+/B" } } )
 
 The next example displays a message and waits for a key press.
 
 FT_DISPMSG( { { "Press [D] To Confirm Deletion"      , ;
 "Or Any Other Key To Abort" }        , ;
 { "W+/B", "W+/B", "GR+/B" } }          , ;
 "D" )
 
 The next example displays a one-line message centered on row 5
 and returns to the calling procedure.
 
 FT_DISPMSG( { { "Please Do Not Interrupt" }   , ;
 { "W+/B", "GR+/B" } }          , ;
 , 5, )

Function FT_FILL()

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

FT_FILL() is a function used to set up the menu options prior to calling FT_MENU1().

 FT_FILL( aOptions[1], 'A. Execute A Dummy Procedure' , {|| fubar()}, .t. )
 
 The above would be added to the sub-menu associated with the first menu
 bar item, would execute the function FUBAR() when that option was
 selected, and would be selectable.
 
 
 FT_FILL( aOptions[3], 'B. Enter Daily Charges'       , {|| .t.},     .f. )
 
 The above would be added to the sub-menu associated with the third menu
 bar item, and would be unselectable.
 
 
 FT_FILL( aOptions[2], 'C. Enter Payments On Accounts', {|| .t.},     .t. )
 
 The above would be added to the sub-menu associated with the second menu
 bar item, and would be selectable, but would do nothing when selected.
 
 
 FT_FILL( aOptions[4], 'C. Exit'                      , {|| .f.},     .t. )
 
 The above would be added to the sub-menu associated with the fourth menu
 bar item, and would be selectable, and would exit FT_MENU1() when chosen.

Function FT_MENU1()

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

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

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

Function FT_MENU2()

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

This function greatly simplifies the process of displaying light-bar menus. All prompts are padded out with spaces so they are the same length, a box is drawn around the prompts, the box is automatically centered on the screen, and the underlying screen is restored after a menu selection has been made.

Additionally, because you can tie action blocks to each menu option, you can save on a lot of DO CASE or IF..ELSEIF code in your main program. See the test code for a succinct demonstration.

 LOCAL mainmenu := ;
 { { "Data Entry", "Enter data",   { || FT_MENU2(datamenu)  } }, ;
 { "Reports",    "Hard copy",    { || FT_MENU2(repmenu)   } }, ;
 { "Maintenance","Reindex files",{ || FT_MENU2(maintmenu) } }, ;
 { "Quit", "See ya later" } }
 FT_MENU2(mainmenu)

Function FT_MENUTO()

 #include "FTMENUTO.CH"
 
 MENU TO <var> [COLD]

This enhanced version of MENU TO requires the inclusion of the header file FTMENUTO.CH in any source file that uses it. It may be used in place of the standard Clipper MENU TO command. However, in the interests of functionality it is NOT 100% compatible (in particular, you should make sure that the target memvar exists before executing the menu -- the Clipper version will create a PRIVATE memvar for you if it does not already exist, but this version does not). No whining! If compatibility is such a big deal then use the standard Clipper command.

Note that this command can also be called using function-style syntax. See the entry for FT_MENUTO() for further details.

 #include "FTMENUTO.CH"
 
 // Simple command
 
 MENU TO memvar
 

Function FT_PENDING()

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

A good way to display information messages during the running of an application is to send them all to the SAME line on the screen where users are expected to look for them. In order to give users a chance to read the current message before the next one is displayed we may need to insert a delay after each message.

FT_PENDING() function displays messages by keeping track of the time of the last message and providing a delay ONLY if the next pending message is issued much too soon after the current one.

 FT_PENDING("Message one",20,0,3,"W+/G") // Displays "Message one."
 // sets row to 20, col to 0.
 // wait to 3 and color to
 // bright white over green.
 FT_PENDING("Message two")   // Displays "Message two", after 5 sec.
 FT_PENDING("Message three") // Displays "Message three", after 5 sec.
 
 
 Note that default row, col, wait time and color need to be set only
 once in the very first call to FT_PENDING() and only if the internal
 default values are not appropriate.
 

Function FT_PICKDAY()

 FT_PICKDAY() --> cDayOfWeek

This function is ideal if you need the user to select a day.

 mday := FT_PICKDAY()

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>]                    ;
 

Clipper's @...PROMPT and MENU TO commands are fine as far as they go. But many times you need more flexibility. As you'll no doubt notice if you read the argument list, this function is almost completely flexible. You can adjust locations and colors for every part of the prompt and its associated message. In addition, since you can control the effect of the arrow keys, you can allow both horizontal and vertical movement, or even disable certain arrow keys if you so desire. Support for nested menus is also available, since the prompts are stored in stack-based static arrays.

Note that this command can also be called using function-style syntax. See the entry for FT_PROMPT() for further details.

This enhanced version of @...PROMPT requires the inclusion of the header file FTMENUTO.CH in any source file that uses it. It is may be used in place of the standard Clipper @...PROMPT command. However, in the interests of functionality it is NOT 100% compatible. No whining! If compatibility is such a big deal then use the standard Clipper commands.

 #include "FTMENUTO.CH"
 
 // Simple prompt
 @ 1, 1 PROMPT "Menu choice #1"
 
 // Prompt with color
 @ 3, 1 PROMPT "Menu choice #2" COLOR "W+/R,W+/B"
 
 // Prompt with a message
 @ 5, 1 PROMPT "Menu choice #3" MESSAGE "Go to lunch"
 
 // Prompt with pinpoint message control
 @ 7, 1 PROMPT "Menu choice #4" MESSAGE "Drop Dead" ;
 MSGROW 22 MSGCOL 4 MSGCOLOR "GR+/N"
 
 // Prompt with a trigger character ("#" character)
 @11, 1 PROMPT "Menu choice #6" TRIGGER 13
 
 // Prompt with trigger character color control
 @13, 1 PROMPT "Menu Choice #7" TRIGGER 13 TRIGGERCOLOR "R+/BG,G+/N"
 
 // Prompt with right and left arrow keys disabled
 @15, 1 PROMPT "Menu Choice #8" RIGHT 8 LEFT 8

Function FT_SLEEP

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

This routine will wait a specified period of time. It provides resolution based upon the execution of the SECONDS() function. It does not use an input state such as INKEY(). The specified time is the minimum time sleeping and will usually be slightly longer.

The second optional argument allows one to begin timing an event prior to executing some operation. This is useful when, for example, you input a key or mouse click and wish to do something but still want to note if the user double entered (mouse or key) within a certain time which in turn may have meaning within your program's context.

The routine correctly handles passing through midnight but will not work for more than 24 hours.

 Example 1:
 FT_SLEEP(10.0)    && Sleep for 10.0 seconds
 Example 2:
 nTime=SECONDS()   && usually after some interupt from mouse or
 && keyboard
 
 ... intervening code ...
 
 FT_SLEEP(0.5, nTime) && Sleep until the sytem clock is
 && nTime+0.5 seconds.
 

Function FT_XBOX()

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

FT_XBOX() allows the programmer to display a message box on the screen without needing to calculate the dimensions of the box. Only the upper left corner needs to be defined. The function will calculate the lower right corner based on the number and length of strings passed.

A maximum of eight strings can be displayed. If a string is too long to fit on the screen it is truncated.

The first seven parameters are optional. The default settings are: Lines of text are centered. Control is returned to the calling routine immediately. A single line border is painted. The border is black on white. The text is white on black. The box is centered both vertically and horizontally.

WARNING: Shadowing is achieved by a call to FT_SHADOW(), an assembly routine not found in this .PRG. In order to use XBOX, SHADOW.OBJ must also be present somewhere (if you are using NANFOR.LIB, then it is).

 The following displays a two-line box with default settings:
 
 FT_XBOX(,,,,,,,'This is a test','of the XBOX() function')
 
 The following uses all optional parameters and displays a three-line
 box.  The box is left-justified with a double border.  It has a yellow
 on red border and white on blue text.  The function will wait for a
 keypress before returning control to the calling routine.
 
 FT_XBOX('L','W','D','GR+/R','W/B',5,10,'It is so nice',;
 'to not have to do the messy chore',;
 'of calculating the box size!')