[<<Previous Entry]
[^^Up^^]
[Next Entry>>]
[Menu]
[About The Guide]
ACHOICE()
ACHOICE() executes a pop-up menu using an array of character strings as
choices.
Syntax
ACHOICE(<expN1>,<expN2>,<expN3>,<expN4>,<array1>[,<array2>,[,<expC>
[,<expN5>[,<expN6>]]]])
Argument
<expN1..expN4> are the top, left, bottom and right window coordinates
respectively.
<array1> is an array of character strings to display as menu choices.
<array2> is a parallel array of logical values, one for each menu
choice. If an element is false (.F.), the parallel menu choice is not
available. You can, however, specify this argument as a single logical
value and the menu is treated as if you specified an array filled with
that value. This is valuable when you want all choices to be either
available or unavailable.
<expC> is a user-defined function that executes generally when a key
exception is pressed. Be sure to specify the function name without the
parenthetical suffix or any arguments. Note that the behavior of
ACHOICE() is affected by the presence of this argument. Refer to the
discussion below for further information.
<expN5> is the initial choice element. If not specified, the default
initial choice is element one in <array1>.
<expN6> is the initial relative window row. If not specified, the
initial relative window row is first choice in the window, which is
position zero.
Returns
A numeric value.
ACHOICE() returns the position of the menu choice in the array of
choices. Making a selection terminates the menu and returns the
current element position in <array1>. Aborting the selection
terminates the menu and returns zero.
Usage
ACHOICE() has two modes depending on whether or not you specify the
user-defined function argument (<expC>). If you do not specify a user
function, ACHOICE() displays the list of choices within the given
screen coordinates. It then executes the following actions when you
press the corresponding keys.
ACHOICE() Active Keys - No User Function
Key Action
Uparrow Up one element
Dnarrow Down one element
Home First element
End Last element
Leftarrow Abort selection, returning zero
Rightarrow Abort selection, returning zero
PgUp Up the number of elements defined for the menu window
to the same relative row position
PgDn Down the number of elements defined for the menu window
to the same relative row position
Ctrl-PgUp First element
Ctrl-PgDn Last element
Return Select element, returning position
Esc Abort selection, returning zero
First letter Next element with same first letter (does not select)
If the number of choices in <array1> exceeds the number of rows in the
menu window, the choices scroll when you attempt to cursor 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 choices. Pressing
the first letter does, however, wrap the highlight within the set of
choices whose first letter matches the key you are pressing.
The User Function: If you specify a user function, the behavior of
ACHOICE() changes to some degree. Primarily, fewer keys are not
automatically executed by ACHOICE() and control passes to the user
function where you can process the key pressed and execute an
appropriate action. The following are keys that ACHOICE() executes
when you specify a user function. These keys generate an idle (mode 0)
while all other keys generate a keyboard exception (mode 3).
ACHOICE() Active Keys - User Function
Key Action
Uparrow Up one element
Dnarrow Down one element
PgUp Up the number of elements defined for the menu window
to the same relative row position
PgDn Down the number of elements defined for the menu window
to the same relative row position
Ctrl-PgUp First element
Ctrl-PgDn Last element
Note that Home, End, Return, and Esc now generate a keyboard exception
(mode 3).
When ACHOICE() executes the user function, it automatically passes the
following three parameters: mode, current element in the array of
choices, and the relative position within the menu window. The mode
indicates the current state of ACHOICE() depending on the key pressed
and action taken by ACHOICE() prior to executing the user function.
The mode parameter has the following possible values:
ACHOICE() Modes
Mode Description
0 Idle
1 Cursor past top of list
2 Cursor past end of list
3 Keystroke exception
4 No item selectable
After your user function has performed whatever operations are
appropriate to the ACHOICE() mode or the last key pressed, you RETURN a
value instructing ACHOICE() what operation to perform next. The
following table summarizes the possible return values:
Return Values to ACHOICE() from User Function
Value Action
0 Abort selection, return zero
1 Make selection, return cursor element
2 Continue selection process
3 Go to next element whose first character matches last key
pressed
Color: Choices are displayed in standard color, the highlight is in
enhanced color, and the unavailable choices are displayed in the
unselected color. For example, the following color statement:
SET COLOR TO 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 choices are dim white on black.
If you are executing ACHOICE() with all choices unavailable in order to
have a display-only list, assign the unselected setting to the same
setting as the standard.
Nesting: You can call multiple copies of ACHOICE() within each copy
of ACHOICE(), allowing you to create nested or hierarchical menus.
See Also:
MENU
SET MESSAGE
DBEDIT()
This page created by ng2html v1.05, the Norton guide to HTML conversion utility.
Written by Dave Pearson