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 ] ]

Use the following syntax to specify a combo-box widget for displaying values in a browse column:

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

LIST-ITEMS item-list

Specifies that the items 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, the AVM 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 the AVM 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.

This option is invalid for combo-box browse columns. The AVM sets the ROW-HEIGHT-CHARS and ROW-HEIGHT-PIXELS attributes for a browse to the height of the combo-box, by default. You can override these settings after the browse is created.

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. The AVM 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.

This option is invalid for combo-box browse columns.

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, the AVM treats it as a DROP-DOWN-LIST combo-box widget.

This option is invalid for combo-box browse columns.

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, the AVM treats it as a DROP-DOWN-LIST combo-box widget.

For combo-box browse columns, a drop-down button appears only when an editable combo-box column has focus. You can use a DROP-DOWN combo-box only for a CHARACTER column. If the current value of the combo-box is not a valid value in the combo-box's item list, the AVM still displays the value in the combo-box's edit control.

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.

For combo-box browse columns, a drop-down button appears only when an editable combo-box column has focus. You can use a DROP-DOWN-LIST combo-box for a CHARACTER, DECIMAL, INTEGER, INT64, DATE, or LOGICAL column. If the current value of the combo-box is not a valid value, the AVM does not display the value in the combo-box's edit control when the combo-box receives focus.

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      NO-UNDO 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 NO-UNDO INITIAL
  "Declaration of Independence,Man walks on moon,Progress Version 7 ships".
DEFINE VARIABLE out-string AS CHARACTER NO-UNDO 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-combo2.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 ix          AS INTEGER   NO-UNDO.
DEFINE VARIABLE rep         AS CHARACTER NO-UNDO LABEL "Rep" 
  VIEW-AS COMBO-BOX.
DEFINE VARIABLE temp-string AS CHARACTER NO-UNDO.

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 ix = 1 TO SELF:NUM-ITEMS:
    IF SELF:ENTRY(ix) BEGINS LAST-EVENT:FUNCTION THEN DO:
      SELF:SCREEN-VALUE = SELF:ENTRY(ix).
      LEAVE seek-item.
    END.
  END.
  IF ix > 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. */
  ix = SELF:LOOKUP(SELF:SCREEN-VALUE).
  IF ix < SELF:NUM-ITEMS THEN
    SELF:SCREEN-VALUE = SELF:ENTRY(ix + 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. */
  ix = SELF:LOOKUP(SELF:SCREEN-VALUE).
  IF ix > 1 THEN 
    SELF:SCREEN-VALUE = SELF:ENTRY(ix - 1).
END.
temp-string = "".

FOR EACH Salesrep NO-LOCK:
  temp-string = IF temp-string = "" THEN SalesRep.SalesRep 
    ELSE temp-string + "," + SalesRep.SalesRep.
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.

COMBO-BOX phrase

Syntax

Examples

Notes

See also