FT_ACH2TB()
Replace ACHOICE() with a Tbrowse object & multiple features.
Syntax
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
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.
Returns
the number of the selected option, or 0 if [Esc] is pressed.
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 pi.ce 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
Examples
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 ) } )
Source: ACH2TB.PRG
