Progress
Language Reference


COMBO-BOX Phrase

Interfaces
OS
SpeedScript
All
All
No

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

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:

SYNTAX
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:

SYNTAX
{ 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 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 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

SEE ALSO

Format Phrase, SIZE Phrase, VIEW-AS Phrase


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