Difference between revisions of "ACHOICE()"

Latest revision as of 13:48, 26 July 2010

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(), ARRAY(), ASCAN(), ASIZE(), ASORT(), ASTORE(), ASTRING(), ASUBSCRIPT(), ASUM(), COPY TO ARRAY, DBEDIT(), DECLARE, DIMENSION, GATHER, IN_ARRAY(), IS_ARRAY(), 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.

Return Values

The UDF must return one of the following values:

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