ACHOICE()

Class

Array Processing

Purpose

Function to display an array of choices in a popup menu

Syntax

ACHOICE(<expN1>, <expN2>, <expN3>, <expN4>, <array1> [,<array2>] [,<expC>] [,<expN5>] [,<expN6>])

See Also

AADD(), AAVERAGE(), ABROWSE(), ACOL(), ACOPY(), ADEL(), ADESC(), ADIR(), AELEMENT(), AFIELDS(), AFILL(), AINS(), ALEN(), AMAX(), AMIN(), APPEND FROM ARRAY, AROW(), ASCAN(), ASIZE(), ASORT(), ASTORE(), ASTRING(), ASUBSCRIPT(), ASUM(), COPY TO ARRAY, DBEDIT(), DECLARE, DIMENSION, GATHER, LOCAL, PRIVATE, PUBLIC, RELEASE, RESTORE, SAVE, SCATTER, SET BORDER

Description

The ACHOICE() function executes a popup menu using an array of character strings as choices. The screen is automatically saved and restored if SET SCREENMAP is ON. The menu is framed in a box where <expN1> to <expN4> represent the coordinates <row>, <col>, <endrow>, <endcol>. The menu border can be disabled with the SET BORDER TO NONE command.

The array <array1> is the name of an array where all the elements are character strings. These character strings make up the menu items. The ACHOICE() function displays a scrollable menu of up to 1000 elements. The optional <array2> is used in parallel with <array1>. If an element in <array2> is .F. (or an expression that evaluates to .F.), the corresponding element in <array1> will be included in the menu but not available for selection.

By default, only the [RETURN], [ABANDON] and [EXIT SAVE] keys and the cursor navigation keys are active within ACHOICE(). The cursor navigation keys are [CURSOR LEFT], [CURSOR RIGHT], [CURSOR UP], [CURSOR DOWN], [PAGE UP] and [PAGE DOWN]. The optional expression <expC> is the name of a User Defined Function (UDF) to handle any other keystrokes.

UDF Parameters

The ACHOICE () function automatically passes three parameters to the UDF: the current ACHOICE() status (see the table below), the current element number in the array, and the relative position within the menu window.

Status	Description
0	ACHOICE() is idle, no keystrokes are pending.
1	An attempt was made to move beyond the top of the array.
2	An attempt was made to move beyond the bottom of the array.
3	A key was pressed that cannot be automatically handled by ACHOICE(). The LASTKEY() function can be used to check the key pressed.
4	No selectable items.

Return Values

The UDF must return one of the following values:

Value	Description
0	Quit ACHOICE(), returning 0.
1	Make selection, returning index of current item.
2	Continue selection process.
3	Go to the next item whose first character matches the last key pressed.

If the optional <expN5> is specified, the highlight bar will be displayed on <expN5> when ACHOICE() is activated. If <expN5> is not specified, the default is the first menu item.

The optional expression <expN6> may be used to specify an initial relative starting row in the window. ACHOICE() returns the position of the selected array element, or 0 if the [ABANDON] key was pressed.

Example

function ach_udf
parameters ach_mode, ach_element, ach_row
do case
case ach_mode = 0
    ach_action = 2
case ach_mode = 1 
    @ 0,0 CLEAR TO 0,79 
    @ 0,0 SAY "Attempt to move past the top of file."
    ach_action = 2
case ach_mode = 2
    @ 0,0 CLEAR TO 0,79
    @ 0,0 SAY "Attempt to move past the end of file."
    ach_action = 2
case ach_mode = 4
    // no item selectable
    ach_action = 0
case ach_mode = 3
    // go to first element starting with this letter
    ach_action = 3
otherwise 
    ach_action = 2
endcase 
return ach_action
 
clear
use cust index cust.ndx 
declare cust_array[reccount(),1]
copy to array cust_array fields last_name
private m_var
m_var = achoice(1,1,23,78,cust_array,,"db_udf")

Products

Recital Mirage Server, Recital Terminal Developer