Release 10.1A: OpenEdge Development:
Progress 4GL Reference

> ## COMBO-BOX phrase

> Describes a combo-box widget. A combo-box represents a field or variable, and consists of a field value and an associated drop-down list of possible values.

> Note: Does not apply to SpeedScript programming.

> #### Syntax

>     COMBO-BOX
>       [ LIST-ITEMS item-list | LIST-ITEM-PAIRS item-pair-list ]
>       [ INNER-LINES lines ] [ size-phrase ] [ SORT ]
>       [ TOOLTIP tooltip ]
>       [ SIMPLE | DROP-DOWN | DROP-DOWN-LIST ]
>       [ MAX-CHARS characters ]
>       [ AUTO-COMPLETION [ UNIQUE-MATCH ] ]

> `LIST-ITEMS `item-list``

> Specifies the items to appear in the drop-down list. `item-list` represents a comma-separated list of valid values for the field or variable.

> `LIST-ITEM-PAIRS `item-pair-list``

> Specifies a list of label-value pairs. Each pair represents the label and value of a field or variable. When the drop-down list appears, it displays each pair’s label. Then, if the user selects a label, Progress assigns the corresponding value to the field or variable. The syntax for `item-pair-list` is as follows:

>     label , value [ , label , value ] ...

> ``label``

> A character string representing the label of the field or variable.

> ``value``

> A value that Progress assigns to the field or variable if the user selects the corresponding label.

> `INNER-LINES `lines``

> Specifies the number of lines visible in the drop-down list for a DROP-DOWN or DROP-DOWN-LIST combo-box widget. The value for `lines` must be 3 or greater. If the number of lines you specify is less than the number of items in the drop-down list, the list is scrollable.

> The INNER-LINES option in a SIMPLE combo-box definition is ignored.

> ``size-phrase``

> Specifies the outside dimensions (width and height) of the combo-box widget and its drop-down list using the SIZE phrase. You must specify a SIZE phrase in the definition of a SIMPLE or DROP-DOWN combo-box widget. The syntax for the SIZE phrase is as follows:

>     { SIZE | SIZE-CHARS | SIZE-PIXELS } width BY height

> For more information, see the SIZE phrase reference entry.

> Note: The `height` value is ignored for DROP-DOWN and DROP-DOWN-LIST combo-box widgets. The height is always set to the height of a fill-in for the current font.

> `SORT`

> Specifies that list items be sorted prior to display.

> `TOOLTIP `tooltip``

> Allows you to define a help text message for a text field or text variable. Progress automatically displays this text when the user pauses the mouse button over a text field or text variable for which a tooltip is defined.

> You can add or change the TOOLTIP option at any time. If TOOLTIP is set to “” or the Unknown value (`?`), then the tooltip is removed. No tooltip is the default. The TOOLTIP option is supported in Windows only.

> `SIMPLE`

> Specifies a combo-box widget with a read/write edit control and a list that is always visible. This option is supported in graphical interfaces only, and only in Windows. If you specify a SIMPLE combo-box widget in a character interface, Progress treats it as a DROP-DOWN-LIST combo-box widget.

> `DROP-DOWN`

> Specifies a combo-box widget with a read/write edit control and a drop-down list that appears when you click the drop-down button. This option is supported in graphical interfaces only, and only in Windows. If you specify a DROP-DOWN combo-box widget in a character interface, Progress treats it as a DROP-DOWN-LIST combo-box widget.

> `DROP-DOWN-LIST`

> Specifies a combo-box widget with a read-only edit control and a drop-down list that appears when you click the drop-down button. This is the default.

> `MAX-CHARS `characters``

> The maximum number of characters the edit control can hold. The `characters` parameter must be a positive integer constant. If `characters` is zero or the Unknown value (`?`), MAX-CHARS is set to 255 characters by default.

> Use MAX-CHARS with only SIMPLE and DROP-DOWN combo-boxes. It is ignored for DROP-DOWN-LIST combo-boxes. This option is supported in graphical interfaces only, and only in Windows.

> `AUTO-COMPLETION`

> Specifies that the edit control automatically complete keyboard input to the combo-box, based on a potential match, by searching through the items in the drop-down list. This option is supported in graphical interfaces only, and only in Windows.

> `UNIQUE-MATCH`

> Specifies that the edit control complete keyboard input to the combo-box based on a unique match. This option is supported in graphical interfaces only, and only in Windows.

> Examples

> The first example, `r-combo.p`, views a date field as a combo-box. When you run this procedure, you can choose a date value from the drop-down list. When you choose a new value, the VALUE-CHANGED trigger updates the value of out-string to an event associated with the new date value.

> The example initializes the drop-down list by building a comma-separated list of values and then assigning the string to the LIST-ITEMS attribute of the combo-box.

> r-combo.p
>     DEFINE VARIABLE hist-date AS DATE FORMAT "99/99/9999"
>             VIEW-AS COMBO-BOX
>             LIST-ITEMS 07/04/1776, 07/11/1969, 09/10/1993.
>     DEFINE VARIABLE hist-event AS CHARACTER INITIAL
>       "Declaration of Independence,Man walks on moon,Progress Version 7
>       ships".
>     DEFINE VARIABLE out-string AS CHARACTER FORMAT "x(36)".

>     DEFINE FRAME main-frame
>        hist-date out-string
>        WITH NO-LABELS TITLE "Historic Events".

>     ON VALUE-CHANGED OF hist-date
>        DO:
>           out-string = ENTRY(SELF:LOOKUP(SELF:SCREEN-VALUE), hist-event).
>           DISPLAY out-string WITH FRAME main-frame.
>        END.

>     ENABLE hist-date WITH FRAME main-frame.

>     APPLY "VALUE-CHANGED" TO hist-date IN FRAME main-frame.

>     WAIT-FOR WINDOW-CLOSE OF CURRENT-WINDOW.

> The following example, `r-combo.p`, builds a combo-box based on field values from a database. It defines triggers that allow you to change the value of the combo-box without displaying the drop-down list. They allow you to scroll through the values using the CURSOR-DOWN and CURSOR-UP keys or to jump to a specific value by typing its first letter.

> r-combo2.p
>     DEFINE VARIABLE i AS INTEGER.
>     DEFINE VARIABLE rep AS CHARACTER LABEL "Rep" VIEW-AS COMBO-BOX.
>     DEFINE VARIABLE temp-string AS CHARACTER.
>     FORM
>        rep
>        WITH FRAME main-frame SIDE-LABELS.
>     ON ANY-PRINTABLE OF rep
>        DO:
>           /* Find the first entry in the drop-down list
>              that begins with the character typed. Set
>              the SCREEN-VALUE of the combo box to that value. */
>           seek-item:
>           DO i = 1 TO SELF:NUM-ITEMS:
>              IF SELF:ENTRY(i) BEGINS LAST-EVENT:FUNCTION
>              THEN DO:
>                  SELF:SCREEN-VALUE = SELF:ENTRY(i).
>                  LEAVE seek-item.
>              END.
>           END.
>           IF i > SELF:NUM-ITEMS
>           THEN BELL.
>        END.
>     ON CURSOR-DOWN OF rep
>        DO:
>           /* Change the SCREEN-VALUE of the combo box
>              to the next value from the drop-down list. */
>           i = SELF:LOOKUP(SELF:SCREEN-VALUE).
>           IF i < SELF:NUM-ITEMS
>           THEN SELF:SCREEN-VALUE = SELF:ENTRY(i + 1).
>        END.
>     ON CURSOR-UP OF rep
>        DO:
>           /* Change the SCREEN-VALUE of the combo box
>              to the prev value from the drop-down list. */
>           i = SELF:LOOKUP(SELF:SCREEN-VALUE).
>           IF i > 1
>           THEN SELF:SCREEN-VALUE = SELF:ENTRY(i - 1).
>        END.temp-string = "".
>     FOR EACH Salesrep NO-LOCK:
>        IF temp-string = ""
>        THEN temp-string = Salesrep.sales-rep.
>        ELSE temp-string = temp-string + "," + Salesrep.sales-rep.
>     END.
>     ASSIGN rep:LIST-ITEMS IN FRAME main-frame = temp-string.
>     ENABLE rep WITH FRAME main-frame.

> #### Notes

> - When the drop-down list appears, if it contains the value associated with the field or variable, that value is initially highlighted. Otherwise, no value in the drop-down list is initially highlighted.

> - The LIST-ITEMS option of the COMBO-BOX phrase requires a list of items (possibly quoted, depending on the combo-box’s data type), such as ("a", "b", "c"), whereas the LIST-ITEMS attribute of a combo-box requires a quoted list of items, such as ("a, b, c"). Similarly, the LIST-ITEM-PAIRS option of the COMBO-BOX phrase requires a list of items (possibly quoted, depending on the combo-box’s data type), such as ("a", 1, "b", 2, "c", 3), whereas the LIST-ITEM-PAIRS attribute of a combo-box requires a quoted list of items, such as ("a, 1, b, 2, c, 3").

> - If you do not specify the LIST-ITEMS or LIST-ITEM-PAIRS option, the screen value of the variable or field becomes the null string (" "). To display or set values in the combo-box, you must first set the LIST-ITEMS or LIST-ITEM-PAIRS attribute to assign a drop-down list that specifies the available values.

> - If you specify the SORT option for a COMBO-BOX, then any items you add with the ADD-FIRST, ADD-LAST, or INSERT methods are added in sorted order rather than the order you specify.

> - Windows allows the user to transfer focus to the drop-down list by pressing ALT and one of the letters in the label. This is called a mnemonic.

> - When you use the SIMPLE and DROP-DOWN options to define a character-field or character-variable combo-box widget, the FORMAT string for the field or variable is ignored.

> - Items in a combo-box are case insensitive.

> #### See also

> Format phrase, SIZE phrase, VIEW-AS phrase

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