MENUS/PROMPTS

Function ACHOICE()

 ACHOICE(<верхняя строка>, <левая колонка>,
 <нижняя строка>, <правая колонка>,
 <массив меню>,
 [<массив логических значений>|<массив выбранных значений>],
 [<функция пользователя>],
 [<позиция маркера>],
 [<строка окна>]) --> номер элемента меню

ACHOICE() - функция, обеспечивающая интерфейс с пользователем, которую можно использовать для создания различных видов всплывающих (pop-up) меню. Каждое меню использует массив символьных строк в качестве элементов меню и параллельный массив логических значений, чтобы определять, доступны элементы для выбора или нет. При вызове ACHOICE() элементы меню высвечивается внутри окна с заданными координатами. Когда пользователь нажимает клавишу <Return>, выбирается текущий элемент, и ACHOICE() возвращает номер выбранного элемента в массиве <массив меню>. Когда пользователь нажимает клавишу <Esc>, выполнение ACHOICE() прерывается и она возвращает нуль.

Если количество элементов в массиве <массив меню> превышает количество строк в окне меню и если пользователь попытается переместить выделение за пределы окна верх или вниз, то элементы меню будут сдвигаться в окне (скроллинг). Надо отметить, что светящийся маркер не переходит автоматически в начало списка элементов, когда вы достигаете его конца, и не переходит в конец, когда вы достигаете начала списка. Однако, если нажать клавишу с какой-нибудь буквой, светящийся маркер переместится на строку меню, начинающуюся с этой буквы.

Перемещение по меню. ACHOICE() имеет два режима, зависящие от того, задан ли аргумент <функция пользователя> или нет. Если он не задан, активными являются следующие клавиши перемещения.

Клавиши ACHOICE() (Нет функции пользователя)
 -------------------------------------------------------------------
 Клавиша            Действие
 -------------------------------------------------------------------
 <стрелка вверх>    к предыдущему элементу
 <стрелка вниз>     к следующему элементу
 <Home>             к первому элементу меню
 <End>              к последнему элементу меню
 <Ctrl>-<Home>      к первому элементу в окне
 <Ctrl>-<End>       к последнему элементу в окне
 <PgUp>             к предыдущей странице
 <PgDn>             к следующей странице
 <Ctrl>-<PgUp>      к первому элементу меню
 <Ctrl>-<PgDn>      к последнему элементу меню
 <Return>           выбрать текущий элемент
 <Esc>              прервать выбор
 <стрелка влево>    прервать выбор
 <стрелка вправо>   прервать выбор
 <первая буква>     к элементу, начинающемуся с этой буквы
 -------------------------------------------------------------------
 

Цвет. Элементы меню отображаются в стандартом цвете, выделенный элемент - в выделенном цвете, недоступные элементы в невыбранном цвете. Например, следующий оператор установки цвета:

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

выводит меню как яркое-белое на черном, выделяемый элемент - ярко-бирюзовый на синем, а недоступные элементы меню - белые на черном.

Функция пользователя. Подобно другим функциям интерфейса с пользователем, ACHOICE() поддерживает функцию пользователя. Функция пользователя может быть использована при создании иерархических меню или переопределении клавишей.

Если задана функция пользователя, ACHOICE() автоматически отрабатывает только ограниченный набор клавиш. Они перечислены в таблице 5-2. Нажатие остальных клавиш приводит к передаче управления на функцию пользователя для их обработки. Управление также передается функции пользователя, когда ACHOICE() неактивна (т.е. когда больше нет клавиш для обработки).

Клавиши ACHOICE() (Функции пользователя заданы)
 -------------------------------------------------------------------
 Клавиша          Действие
 -------------------------------------------------------------------
 <стрелка вверх>  к предыдущему элементу
 <стрелка вниз>   к следующему элементу
 <Ctrl>-<Home>    к первому элементу в окне
 <Ctrl>-<End>     к последнему элементу в окне
 <PgUp>           к предыдущей странице
 <PgDn>           к следующей странице
 <Ctrl>-<PgUp>    к первому элементу меню
 <Ctrl>-<PgDn>    к последнему элементу меню
 -------------------------------------------------------------------
 

Когда ACHOICE() выполняет функцию пользователя, ей автоматически передаются следующие три параметра:

текущий режим ACHOICE()

текущий элемент в массиве меню

относительная позиция строки в окне меню.

Режим показывает текущее состояние ACHOICE(), зависящее от того, какая клавиша была нажата, и действие, предпринятое ACHOICE() перед выполнением функции пользователя. Параметр режима имеет следующие возможные значения:

Режимы ACHOICE()
 -------------------------------------------------------------------
 Режим    Achoice.ch      Описание
 -------------------------------------------------------------------
 0      AC_IDLE         неактивно
 1      AC_HITTOP       пытается продвинуть маркер вверх за список
 2      AC_HITBOTTOM    пытается продвинуть маркер за конец списка
 3      AC_EXCEPT       необрабатываемая клавиша
 4      AC_NOITEM       невыбранные элементы
 -------------------------------------------------------------------
 

После того, как функция пользователя будет выполнена, она должна вернуть в ACHOICE() код, определяющий последующие действия ACHOICE(). Ниже приводится набор этих кодов:

Значения, возвращаемые функцией пользователя ACHOICE().
 -------------------------------------------------------------------
 Значение   Achoce.ch    Действие
 -------------------------------------------------------------------
 0        AC_ABORT     прервать выбор
 1        AC_SELECT    сделать выбор
 2        AC_CONT      продолжить ACHOICE()
 3        AC_GOTO      к следующему элементу меню, первая буква
 которого совпадает с нажатой клавишей
 -------------------------------------------------------------------
 

 Этот пример содержит два символьных массива, чтобы задать
 элементы меню и критерии выбора. После того, как меню высвечено,
 и пользователь сделал выбор, имя выбранного элемента меню
 высвечивается:
 
 acMenuItems = {ONE, TWO, "", THREE}
 alSelectableItems = {.T., .T., .F., .T.}
 nPosition = ACHOICE(10, 10, 12, 15, acMenuItems, alSelectableItems)
 ? acMenuItems(nPosition)
 
 В следующем примере объявлены массивы, для одного из элементов меню
 задано условие выбора и имеется функция пользователя:
 
 FUNCTION MyMenu
 LOCAL acMenuItems[4], alSelectableItems[4], cUserFunction:="DoIt"
 //
 acMenuItems[1] = "Добавить запись"
 acMenuItems[2] = "Редактировать запись"
 acMenuItems[3] = "Удалить запись"
 acMenuItems[4] = "Обновить запись"
 //
 alSelectableItems[1] = .T.
 alSelectableItems[2] = .T.
 alSelectableItems[3] = .T.
 alSelectableItems[4] = "!UPDATED()" // Условие выбора
 RETURN ACHOICE(10, 10, 12, 15, acMenuItems,;
 alSelectableItems, cUserFunction)

Function ALERT()

 ALERT( <сообщение> [,<массив предложений>] ) --> <номер предложения>

Функция ALERT() создает диалоговое окно. Это бывает полезно при обработке ошибок или в других ситуациях, где необходима пауза. Пользователь может перемещать выделенную строку нажатием клавиши <Пробел>, осуществить выбор нажатием клавиши <RETURN>, или клавиши, соответствующей первой букве выбираемого ответа. Если <массив предложений> не задан, то высвечивается предложение "OK" (да). ALERT() чувствительна к наличию или отсутствию xClipper-системы полноэкранного ввода-вывода. Если такая система отсутствует, то ALERT() использует стандартную систему телетайпного ввода-вывода.

  В этом примере демонстрируется, как использовать диалоговое окно.
 Сначала определяется массив предложений, затем вызывается функция
 ALERT(), и пользователь делает свой выбор. Далее этот выбор
 обрабатывается с помощью управляющей структуры DO CASE...ENDCASE.
 
 #define AL_SAVE  1
 #define AL_CANCEL 2
 #define AL_CONT  3
 
 // Определяется массив предложений
 aOptions := {"Сохранить", "Не сохранять", "Продолжить"}
 
 // Открытие диалогового окна
 nChoice  := ALERT("Файл был изменен...", aOptions)
 
 // Обработка выбора пользователя
 DO CASE
 CASE nChoice == AL_SAVE
 ? "Сохранение"
 CASE nChoice == AL_CANCEL
 ? "Отказ от сохранения"
 CASE nChoice == AL_CONT
 ? "Продолжение работы"
 OTHERWISE
 ? "Отказ от выбора"
 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!')