| xHarbour Reference Documentation > Function Reference | |
 |
 |
 |
Displays a list of items to select one from.
AChoice( [<nTop>] , ;
[<nLeft>] , ;
[<nBottom>] , ;
[<nRight>] , ;
<acItems> , ;
[<aSelectable>], ;
[<cUserFunc>] , ;
[<nFirstItem>] , ;
[<nFirstRow>] ) --> nSelectedItem
Note: No element in <acItems> may contain a null-string (""). A null-string is treated as End-of-list marker.
When an array is passed, it must have at least the same number of elements as <acItems> and is treated as parallel array indicating individual elements that can be selected. If an element of <aSelectable> contains .T. (true), the corresponding item in <acItems> is selectable, otherwise it is displayed but not selectable.
As an alternative, elements in <aSelectable> may contain character strings. They are treated as macro-expressions and are evaluated with the macro-operator. The result of the macro-expression must be a logical value.
AChoice() returns a numeric value. It indicates the position of the selcted item in <acItems>. When the user makes no selection, the return value is zero.
AChoice() is a console window function that presents to the user a list of items to select one from. The function maintains a window region and displays in it the items specified as the <acItems> array containing character strings. The colors for display are taken from the current SetColor() string. That is, normal items are displayed in Standard color, the highlight in Enhanced color and unselectable items with the Unselected color
The user can navigate through the list using cursor keys. AChoice() automatically scrolls the list within the defined window region if the user attempts to navigate the highlight bar outside the window. The user selects an item by pressing the Return key or by double clicking an item, and aborts selection with the Esc key.
Direct navigation to an item as accomplished by pressing letter keys. In this case, AChoice() moves the highlight to the next item whose first letter matches the pressed key.
Navigation without user function
AChoice() recognizes in its default navigation mode the keys listed in following table. The default mode is present when no user function <cUserFunc> is specified.
AChoice() default navigation
| Key | Navigation |
|---|---|
| Up arrow | Go to previous item |
| Down arrow | Go to next item |
| Home | Go to first item in menu |
| End | Go to last item in menu |
| Ctrl+Home | Go to first item in window |
| Ctrl+End | Go to last item in window |
| PgUp | Go to previous page |
| PgDn | Go to next page |
| Ctrl+PgUp | Go to the first item in menu |
| Ctrl+PgDn | Go to last item in menu |
| Return | Select current item |
| Esc | Abort selection |
| Left arrow | Abort selection |
| Right arrow | Abort selection |
| First letter | Go to next item beginning with first letter |
| Left click *) | Go to clicked item |
| Left double click *) | Select clicked item |
| *) Mouse keys must be activated with SET EVENTMASK | |
Navigation with user function
AChoice() processes some very basic navigation keys automatically when a user function is specified. This nvigation occurs before the user function is called. All keys not listed in the following table are passed on to the user function which may instruct AChoice() to take appropriate action.
AChoice() restricted navigation
| Key | Navigation |
|---|---|
| Down arrow | Go to next item |
| Ctrl+Home | Go to first item in window |
| Ctrl+End | Go to last item in window |
| PgUp | Go to previous page |
| PgDn | Go to next page |
| Ctrl+PgUp | Go to the first item in menu |
| Ctrl+PgDn | Go to last item in menu |
| Left click *) | Go to clicked item |
| *) Mouse keys must be activated with SET EVENTMASK | |
After default action is taken, AChoice() invokes the user function, passing three parameters for further processing:
| 1) | The current AChoice() mode (see table below). |
| 2) | The current element in the array of items. |
| 3) | The relative row position of the highlight bar within the window region. |
AChoice() modes passed to the user function indicate the internal state. They are encoded as numeric values for which #define constants exist in the ACHOICE.CH file.
AChoice() modes
| Constant | Mode | Description |
|---|---|---|
| AC_IDLE | 0 | Idle |
| AC_HITTOP | 1 | Attempt to move cursor past top of list |
| AC_HITBOTTOM | 2 | Attempt to move cursor past bottom of list |
| AC_EXCEPT | 3 | Unknown key pressed |
| AC_NOITEM | 4 | No selectable items |
The user function can process the passed parameters. It then instructs AChoice() how to proceed by returning one of the following numeric values. All user-function return values are also available as #define constants.
User-function return values for AChoice()
| Constant | Value | Action |
|---|---|---|
| AC_ABORT | 0 | Abort selection |
| AC_SELECT | 1 | Make selection |
| AC_CONT | 2 | Continue AChoice() |
| AC_GOTO | 3 | Go to the next item whose first character matches the key pressed |
| See also: | @...PROMPT, DbEdit(), MENU TO, TBrowseNew() |
| Category: | Array functions , UI functions |
| Header: | achoice.ch |
| Source: | rtl/achoice.prg |
| LIB: | xhb.lib |
| DLL: | xhbdll.dll |
// The example uses AChoice() to display names of files in the current
// directory. Only files with the TXT or PRG extension can be selected.
// A selected file is displayed using MemoEdit(). Note how the return
// value of the user function triggers the AChoice() action.
#include "Achoice.ch"
#include "Inkey.ch"
MEMVAR aFiles
PROCEDURE Main
LOCAL nSelect
LOCAL aItems := Directory()
LOCAL i, imax := Len( aItems )
LOCAL aSelect := Array( imax )
LOCAL cScreen
SetColor( "W/N" )
CLS
SetColor( "N/BG,W+/B,,,W/BG" )
PRIVATE aFiles := AClone( aItems )
FOR i:=1 TO imax
aItems[i] := Upper( aItems[i,1] )
aSelect[i] := ( ".TXT" $ aItems[i] .OR. ;
".PRG" $ aItems[i] )
NEXT
DO WHILE LastKey() <> K_ESC
nSelect := Achoice( 2, 2, MaxRow()-5, 30, ;
aItems, aSelect, "USERFUNC" )
IF nSelect <> 0
// Display selected file
SAVE SCREEN TO cScreen
MemoEdit( MemoRead( aItems[nSelect] ) )
RESTORE SCREEN FROM cScreen
KEYBOARD Chr(255) // sets Lastkey() to 255
Inkey()
ENDIF
ENDDO
RETURN
FUNCTION UserFunc( nMode, nElement, nRow )
LOCAL nKey := LastKey()
LOCAL nRet := AC_CONT
LOCAL cMsg
DO CASE
CASE nMode == AC_IDLE
// do some idle processing
cMsg := " File: " + aFiles[nElement,1] + ;
" Size: " + Str( aFiles[nElement,2] ) + ;
" Date: " + DtoC( aFiles[nElement,3] ) + ;
" Time: " + aFiles[nElement,4]
DispOutAt( MaxRow(), 0, Padr(cMsg, MaxCol()+1), "W+/R" )
CASE nMode == AC_EXCEPT
// key handling for unknown keys
IF nKey == K_ESC
nRet := AC_ABORT
ELSEIF nKey == K_RETURN .OR. nKey == K_LDBLCLK
nRet := AC_SELECT
ELSEIF nKey > 31 .AND. nKey < 255
nRet := AC_GOTO
ENDIF
ENDCASE
RETURN nRet
http://www.xHarbour.com