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.

SYNTAX

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

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

Interfaces OS SpeedScript

All All No

COMBO-BOX

[

|

]

[

] [

] [

]

[

]

[

|

|

]

[

]

[

[

] ]

SYNTAX

label , value

[

] ...

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:

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.

SYNTAX

{

|

|

}

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 unknown (?), 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

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.

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-combo.p

r-combo2.p

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