Release 10.1A: OpenEdge Development:
Progress 4GL Reference

> ## CHOOSE statement

> After you display data, the CHOOSE statement moves a highlight bar among a series of choices and selects a choice when you press GO, RETURN, or enter a unique combination of initial characters.

> This statement is supported only for backward compatibility.

> Note: Does not apply to SpeedScript programming.

> #### Syntax

>     CHOOSE
>       {     { ROW field [ HELP char-constant ] }
>          |  { FIELD { field [ HELP char-constant ] } ... }
>       }
>       [ AUTO-RETURN ] [ COLOR color-phrase ]
>       [ GO-ON ( key-label ... ) ] [ KEYS char-variable ]
>       [ NO-ERROR ] [ PAUSE expression ]
>       { [ frame-phrase ] }

> You can specify the AUTO-RETURN, COLOR, GO-ON, KEYS, NO-ERROR, and PAUSE options in any order.

> `ROW `field``

> Tells CHOOSE to move a highlight bar among iterations of a down frame. The`field` is the name of the field that you want the highlight bar to begin highlighting. The ROW option is useful for browsing through a set of records, although `field` does not have to refer to database records.

> If you use the ROW option with the CHOOSE statement, Use the SCROLL statement as well. See the SCROLL statement reference entry examples.

> If you use ROW, you can add a COLOR statement to control the video display highlighting.

> `FIELD `field``

> Tells CHOOSE to move a highlight bar through a set of fields or set of array elements in a frame. The `field` argument is the table record or array variable with fields or elements through which you want to move the highlight bar. These fields or array elements must be defined as Progress default FILL-IN widgets (not specified with the FILL-IN NATIVE option). The FIELD option is useful for building menus. You can also supply help for `field`.

> `HELP `char-constant``

> Lets you provide help text for each field in a CHOOSE FIELD statement or for the entire CHOOSE ROW statement. For the CHOOSE ROW statement, the help text is displayed throughout the CHOOSE operation. For the CHOOSE FIELD statement, the help text you specify for a field is displayed whenever you move to the field.

> `AUTO-RETURN`

> Tells Progress to use the selection when you enter a unique string of initial characters. When you use AUTO-RETURN and the user enters a unique string of initial characters, Progress sets the value of LASTKEY to KEYCODE (return).

> `COLOR `color-phrase``

> Specifies a video attribute or color for the highlight bar. Following is the syntax for `color-phrase`:

>     {     NORMAL
>        |  INPUT
>        |  MESSAGES
>        |  protermcap-attribute
>        |  dos-hex-attribute
>        |  { [ BLINK- ] [ BRIGHT- ]
>              [ fgnd-color ] [ bgnd-color ] }
>        |  { [ BLINK- ] [ RVV- ] [ UNDERLINE- ] [ BRIGHT- ]
>              [ fgnd-color ] }
>        |  VALUE ( expression )
>     }

> For more information on `color-phrase`, see the COLOR phrase reference entry.

> `GO-ON ( `key-label` ) . . .`

> Names `key-labels` for keys that cause CHOOSE to return control to the procedure. If you do not use the GO-ON option, CHOOSE returns control to the procedure when the user presses GO, RETURN, END-ERROR, or types a unique substring when AUTO-RETURN is in effect. If you don’t specify F1, RETURN, or F4, those keys are still GO-ON keys by default.

> `KEYS `char-variable``

> If you want to highlight a particular choice when entering a CHOOSE statement, or if you want to know what keys the user pressed to make a selection, use the KEYS option. When you use the KEYS option, you must give the name of a character variable, `char-variable`. If `char-variable` is initialized to one of the choices before entering the CHOOSE statement, Progress highlights that choice. As the user presses keys to move the highlight bar, Progress saves those keystrokes in `char-variable`. You can test the value of`char-variable` after the CHOOSE statement returns control to the procedure. There is a 40-character limit when using the KEYS option.

> `NO-ERROR`

> Overrides default error handling by the CHOOSE statement, and returns control to the procedure. If you do not use the NO-ERROR option, the CHOOSE statement causes the terminal to beep when the user presses an invalid key.

> If you use the NO-ERROR option and the user presses an invalid key, the CHOOSE statement ends. At this point, you usually want to use the LASTKEY function to test the value of the last key the user pressed and then take the appropriate action.

> Note that the NO-ERROR option of the CHOOSE statement does not have any affect on the ERROR-STATUS system handle.

> `PAUSE `expression``

> Specifies a time-out period in seconds. If the user does not make a keystroke for the specified number of seconds, the CHOOSE statement times out and returns control to the procedure. The time-out period begins before the user’s first keystroke and is reset after each keystroke. If CHOOSE times out, the value of LASTKEY is -1. Use time-out period to prevent inactivity.

> ``frame-phrase``

> Specifies the overall layout and processing properties of a frame. For more information on `frame-phrase`, see the Frame phrase reference entry.

> If your procedure might eventually run on a spacetaking terminal, use the ATTR-SPACE option for the CHOOSE statement. Omitting this option makes the highlight bar invisible.

> Example

> The following procedure displays a strip menu with four choices. The procedure defines two arrays; one holds the items for selection on the menu, the other holds the names of the programs associated with the menu selections. The CHOOSE statement allows the user to select an item from the strip menu. Progress finds the number (within the array) associated with the item selected and the program associated with that number in the proglist array. Progress runs the program, if it exists, and displays a message. It also allows the user to select another item if the program does not exist. (In your own application, you associate actions with items selected by the CHOOSE statement.)

> r-chsmnu.p
>     DEFINE VARIABLE menu AS CHARACTER EXTENT 4 FORMAT "x(7)"
>       INITIAL [ "Browse", "Create", "Update", "Exit" ].
>     DEFINE VARIABLE proglist AS CHARACTER EXTENT 4
>       INITIAL [ "brws.p", "cre.p", "upd.p", "exit.p"].

>     FORM "Use the sample strip menu to select an action."
>       WITH FRAME instruc CENTERED ROW 10.

>     REPEAT:
>       VIEW FRAME instruc.
>       DISPLAY menu WITH NO-LABELS ROW 21 NO-BOX ATTR-SPACE
>         FRAME f-menu CENTERED.
>       HIDE MESSAGE.
>       CHOOSE FIELD menu GO-ON (F5) AUTO-RETURN
>         WITH FRAME f-menu.
>       IF SEARCH(proglist[FRAME-INDEX]) = ?
>       THEN DO:
>         MESSAGE "The program" proglist[FRAME-INDEX] "does not exist.".
>         MESSAGE "Please make another choice.".
>       END.
>       ELSE RUN VALUE(proglist[FRAME-INDEX]).
>     END.

> The GO-ON option sets the GET key to perform an action like GO. With the LASTKEY function, you could check for F5 and take another action relevant to your application.

> #### Notes

> - If you do not specify help text in the CHOOSE statement, any help text you specify for the field in the Data Dictionary is displayed instead. If no help text is specified in either the CHOOSE statement or Data Dictionary, then the status default message is displayed throughout the CHOOSE statement.

> - The CHOOSE statement takes different actions depending on the key you press and whether you use the NO-ERROR option, as shown in Table 11.

> Table 11: CHOOSE statement actions
> Key | NO-ERROR | Action
> --- | --- | ---
> Valid cursor motion.1 | N/A | Clear saved keys, move highlight bar.
> Invalid cursor motion.2 | NO | Clear saved keys, beep terminal.
> Invalid cursor motion.2 | YES | Clear saved keys, return control to procedure.
> A non-unique string followed by an alphanumeric character that does not form a matchable string.3 | NO | Clear saved keys, try to match the last key entered. If no match is available, beep terminal.
> A non-unique string followed by an alphanumeric character that does not form a matchable string with the other characters. | YES | Return control to procedure.
> An invalid string. | NO | Beep terminal.
> An invalid string. | YES | Return control to the procedure and, if the KEYS option was used, save any printable keys.
> Other keys.4 | NO | Beep terminal.
> Other keys.4 | YES | Return control to procedure.
> Valid cursor motion keys within a frame are CURSOR UP, CURSOR DOWN, CURSOR RIGHT, CURSOR LEFT, SPACEBAR, TAB, and BACKTAB. Invalid cursor motion keys are CURSOR UP, CURSOR DOWN, CURSOR RIGHT, and CURSOR LEFT that cause the cursor to move outside the frame. The `r-chs1.p` procedure below, shows what the CHOOSE statement does when the user enters a non-unique string followed by a character that, together with the rest of the string, does not match anything. Other keys are non-cursor-motion, non-alphanumeric keys (function keys, BACKSPACE) except for: HELP, STOP, RETURN, GO, END, ERROR, END-ERROR. Keys defined to do the actions of these keys still do so.

> r-chs1.p
>       DEFINE VARIABLE abc AS CHARACTER FORMAT "x(3)" EXTENT 42.
>       DEFINE VARIABLE i AS INTEGER.

>       DO i = 1 TO 42:
>         abc[i] = STRING(i,">9").
>       END.

>       DISPLAY abc NO-LABELS WITH ATTR-SPACE CENTERED ROW 4
>         TITLE " CHOOSE STATEMENT " FRAME f-choose WIDTH 36.
>       DISPLAY "Enter your selection " WITH CENTERED NO-BOX
>         FRAME f-instruct.
>       PAUSE 1 BEFORE-HIDE NO-MESSAGE.

>       REPEAT:
>         HIDE MESSAGE.
>         CHOOSE FIELD abc AUTO-RETURN WITH FRAME f-choose.
>         MESSAGE "You selected -> " FRAME-VALUE.
>       END.

> Once you run this procedure, your window looks like the following:

> - When you press 2, CHOOSE moves the highlight bar to 2. When you press 4, CHOOSE moves the bar to 24. When you press 6, CHOOSE looks for the string 246. Because it cannot find the string, it matches the last key pressed (6) and places the highlight bar on 6.

> - A choose field can temporarily become a handle type for internal purposes, but is not actually a widget since it does not have its own set of attributes and widgets. Therefore, you might see myhandle:TYPE = choose field in the widget tree, but you cannot manipulate the choose field.

> #### See also

> COLOR phrase, Frame phrase, SCROLL statement, STATUS statement

Copyright © 2005 Progress Software Corporation www.progress.com Voice: (781) 280-4000 Fax: (781) 280-4095