A COMBO-BOX provides the features of a LIST-BOX and ENTRY-FIELD combined. The user may enter data into the entry field directly, or may select a value from a list.
The set of COMBO-BOX properties includes:
Common Properties
TITLE
Combo boxes do not have titles.
VALUE
Combo boxes have alphanumeric values that represent the data in the entry field portion of the control. For combo boxes with the DROP-LIST style (see below), the value represents the selected list item. In this case, the handling of the value is the same as for list boxes (see above).
SIZE
The SIZE value describes the width of the entry field portion of the combo box. It is interpreted in the same fashion as for an ENTRY-FIELD control. The LINES value describes the number of lines shown in the combo box. The entry field portion of the box counts as one of the lines. The remaining lines are part of the list box. Any overhead needed for boxes and other sub-controls (such as scroll bars) is added to these values. Note that a vertical scroll bar is automatically added when the number of items in the list exceeds the value of LINES.
When the program executes on a non-graphical system, the values specified in the CLINES and CSIZE phrases, if present, replace the values specified by the LINES and SIZE phrases.
The default LINES value is "5". The default SIZE value depends on whether or not a VALUE is specified when the combo box is created. If a VALUE is specified, the default SIZE value equals the size of the VALUE literal or data item. Otherwise, the default SIZE is "12".
COLOR
Any foreground and background colors specified in the program are used. If the background color is not specified, the owning subwindow's background color is used. If the foreground color is not specified, a system-default color is used. Note that color handling in combo boxes is tricky because there are several components that make up a control. You will not be able to control all of the colors shown using just foreground and background colors. For this reason, we suggest using the default colors.
STYLES
DROP-DOWN This style indicates that the list portion of the control is normally hidden. To see the list, the user pushes a button shown beside the entry field portion, causing it to drop down from the entry field. This is the default style.
STATIC-LIST This style causes the list to be permanently displayed on the screen.
DROP-LIST This style is similar to the DROP-DOWN style, except that the entry field is replaced by a static display of the currently selected list item.
UNSORTED This style is the same as the LIST-BOX style of the same name.
3-D This style behaves identically to the 3-D ENTRY-FIELD style of the same name.
LOWER This style converts all the text in the box to lower-case.
UPPER This style converts all the text in the box to upper-case.
NOTIFY-DBLCLICK This style causes the combo box to generate CMD-DBLCLICK events. Normally, double-clicking on an item in the combo box has no special effect. If you specify this style, double clicking on an item will generate a CMD-DBLCLICK event. This will usually terminate the current ACCEPT statement and allow your program to act on the selection immediately. You can also use an embedded EXCEPTION PROCEDURE in the Screen Section to perform immediate processing. Note that this style is generally useful only for STATIC-LIST style boxes because the other types of combo boxes close their drop-down list as soon as the user clicks on an item (effectively preventing the ability to perform a double-click). See also the TERMINATION-VALUE and EXCEPTION-VALUE properties below for related topics.
NOTIFY-SELCHANGE This style causes the combo box to generate NTF-SELCHANGE events. Normally, selecting an item in the combo box has no special effect. If you specify this style, a selection change will generate a NTF-SELCHANGE event. This allows your program to act immediately on the new selection.
Special Properties
MAX-TEXT (numeric) This property is the same as the ENTRY-FIELD property of the same name.
ITEM-TO-ADD (alphanumeric) This property is the same as the LIST-BOX property of the same name.
MASS-UPDATE (numeric) This property behaves the same as the LIST-BOX property of the same name.
RESET-LIST (numeric) This property is the same as the LIST-BOX property of the same name.
ITEM-TO-DELETE (numeric) This property is the same as the LIST-BOX property of the same name.
INSERTION-INDEX (numeric) This property is the same as the LIST-BOX property of the same name.
TERMINATION-VALUE (numeric) This property produces the same behavior as the TERMINATION-VALUE push button property, except that it acts on the CMD-DBLCLICK event instead of the CMD-CLICKED event. This property is used only when the NOTIFY-DBLCLICK style is also used. The compiler applies the NOTIFY-DBLCLICK style automatically if this property is explicitly named when the control is initially created. Note that this does not occur if you use the PROPERTY phrase to supply the property value (by giving its identifying number).
EXCEPTION-VALUE (numeric) This property produces the same behavior as the push button property of the same name, except that it acts on the CMD-DBLCLICK event instead of the CMD-CLICKED event. This property is used only when the NOTIFY-DBLCLICK style is also used. The compiler applies the NOTIFY-DBLCLICK style automatically if this property is explicitly named when the control is initially created. Note that this does not occur if you use the PROPERTY phrase to supply the property value (by giving its identifying number).
Events
CMD-DBLCLICK
CMD-GOTO
CMD-HELP
MSG-VALIDATE
NTF-SELCHANGE
Using Special Keys
When a combo box has the input focus, the Home and End keys position the cursor at the beginning or end of a line of text. The Page-Up and Page-Down keys can be used to scroll the combo box. Setting KEYSTROKE configuration entries does not affect these actions.
Examples
The first example creates a drop-down combo box (the default style) that contains a one-line entry field and a four-line list box (total of five lines):
DISPLAY COMBO-BOX, LINES 5, HANDLE IN COMBO-BOX-1.
Here is the Screen Section equivalent. This definition also specifies a data item in which the combo box choice will be stored:
03 COMBO-BOX-1, COMBO-BOX, TO COMBO-BOX-DATA, LINES 5.
Here is an example of code that adds 10 items to the combo box:
PERFORM VARYING IDX FROM 1 BY 1 UNTIL IDX > 10
MODIFY BOX-1, ITEM-TO-ADD = BOX-DATA( IDX )
END-PERFORM.
The following combo box does not use a drop-down list (the list is always displayed):
03 COMBO-BOX, USING BOX-DATA, STATIC-LIST, LINE 5,
COLUMN 40, SIZE 20, LINES 8.