skip to main content
OpenEdge Development: AppBuilder
Data-Display/Capture Objects : Combo boxes
 
Combo boxes
The combo box object combines a fill-in with a selection list. You might use it in cases where:
*The user will have to choose a single item from a list.
*A radio‑button set is not an appropriate representation.
A combo box will generally be a better representation than a radio set when the set of choices is large, varies in size, or involves long strings. A drop-down list or combo box will generally be a better choice than a simple list or combo box when space is at a premium, as is often the case. Drop-down lists/combo boxes also visually emphasize the current choice more than radio sets or simple lists/combo boxes do.
AppBuilder offers two different combo box objects for your use:
*The basic ABL combo box
*An ActiveX (OCX) combo box
Creating a basic combo box instance
You can find the combo box on the Object Palette.
To create and place a basic combo box instance:
1. Click the Combo Box in the Object Palette.
Be sure to select the one shown here. The other Combo Box icon (not shown) represents the OCX version.
2. Move the mouse cursor over a bare spot in your workspace and click to place the new combo box.
3. Configure and size it.
Configuring a basic combo box instance
To configure your combo box object, begin by selecting the object and choosing ToolsProperty Sheet. The Property Sheet dialog box appears:
Minimal configuration
Although you can accept the default values for many object properties, you should at least make the following changes:
*Change the object identifier and Label to better represent the role of this combo box in your application.
*Type in the items that will populate the list, one item per line. You might need to change the data type first. See the Define As and Format entries in the “Size and style configuration” section.
*If appropriate, click Advanced and, when the Advanced Properties dialog box opens, enter the Initial Value.
Size and style configuration
*No-Label — Normally cleared. Setting this check box turns off display of any label. Setting this check box does not clear the actual label text; the label string remains visible in the property sheet. The only other effect of setting or clearing this box is to alter the values in the Geometry section so that the combo box stays at the same XY location within the enclosing frame.
*Inner Lines — Type in the number of lines to be displayed by the selection‑list component when it is open. The default value is 5 lines.
*Define As — Choose the data type from the list. The default type is CHARACTER, but you can choose DATE, DECIMAL, INTEGER, INT64, or LOGICAL instead. AppBuilder will seed the list with a single item of that type.
*Format — Enter the formatting string for the data type you have chosen. If you would prefer to pick the format string from a list rather than enter it by hand, click Format.
*Tooltip — This combo box displays any text you enter here whenever the user allows the mouse cursor to hover over it.
*Help ID — If you plan to provide context‑sensitive help in your application for this object, type in a unique integer as its identifier.
*Simple / Drop‑Down / Drop‑Down-List:
*Simple — In this style, you must explicitly make the selection list component visible at design time, if it is to be visible at all. By default, AppBuilder generates the widget with only the fill-in visible. Drag the bottom handle to reveal as many lines of list as you like. In this style, the fill-in element is editable.
*Drop‑Down — In this style, the user can open and pick from the list, or type a value into the fill-in component. You can write code to permanently add the typed‑in value to the entries in the list, if you wish, or discard the entry after use.
*Drop‑Down-List — (Default) In this style, the fill-in component is read-only—the user cannot type into it. The user can only open and pick from the list. The choice then appears in the fill-in component. Note that in other major widget taxonomies, a drop‑down list is a type of selection list, not a type of combo box. Note, too, that this style is not the default for the ActiveX combo box.
*Color, type style, popup, string attributes, data field — Click the appropriate button to set these properties. For further information, see Appendix A, “Frequently Used Dialogs.”
*Geometry — Although it is often more convenient to set the XY origin and size of a widget visually in the workspace, you can set those values explicitly here, if you prefer. You can also choose a particular alignment, though the only effect this has is to change the X origin in the source code.
*Auto‑Completion — Normally cleared. Setting this box causes the combo box to attempt to complete the entry the user is typing. This option is only meaningful where the fill-in portion of the combo box is editable.
*Display — Normally set. Clearing this box prevents this combo box from automatically populating its fill-in during initialization.
*Drop-Target — Normally cleared. Setting this box causes this combo box to experience an event whenever the user drags another object onto it. You must write the appropriate event‑handling code.
*Enable — Normally set. Clearing this box makes the fill-in part unresponsive to input.
*Hidden — Normally cleared. Setting this box prevents the combo box from responding to implicit requests to display itself. It will only honor explicit requests.
*No-Tab-Stop — Normally cleared. Setting this box removes this combo box from the enclosing frame’s traversal list. Normally, pressing the key causes focus to move from one object to the next in the list. When this box is set, the object can neither lose nor gain focus when the user presses the TAB key. If the widget has the focus, it will ignore the key, and if it does not, focus will cycle through the other members of the traversal list while ignoring this widget.
Caution: Making this combo box Movable or Resizable (Advanced Properties) prevents this object from gaining input focus using the mouse. So if you also set No Tab Stop, you effectively prevent the widget from ever gaining input focus.
*No-Undo — Cleared. Cannot be set. The AVM will always journal changes to the data in this combo box.
*Remove from Layout — Cleared. Cannot be set unless defining an alternate layout.
*Shared — Cleared. Setting this box causes the combo box to be reachable outside the defining procedure.
*Sort — Normally cleared. Setting this box causes the combo box to always display the items in its drop‑down list in sorted order, regardless of their real order.
*Unique-Match — Normally cleared. (This option is not available unless you set Auto‑Completion.) Setting this box causes the combo box to wait for a unique substring before completing the entry.
Advanced properties
Click Advanced. The Advanced Properties dialog box appears:
You can change any of the following values that do not meet your needs:
*Initial Value — You can enter a value here that will appear in the fill-in component of the combo box on startup.
*Help — The text you enter here will display in the status area of the enclosing window, whenever this object has input focus. If you choose to let this combo box inherit the help string defined in the Data Dictionary’s schema, you will not be able to enter text here, even if there is no help string in the schema. If the combo box is assigned to a dialog box rather than a window, or if the window has no status area, this text will not display.
*Private Data — AppBuilder writes this data out as the value of the PRIVATE-DATA attribute. You can write code to make use of this data in any way that meets your needs.
*Generated Code Layout Unit — You can elect to have AppBuilder define this object in character (the default) or pixel units, in the source code it generates.
*Custom Lists — The custom lists are macros belonging to the enclosing frame. They allow you to treat many objects alike without having to refer to them individually. You can include this object in any or all of the lists.
*Geometry — You can set the XY origin and closed size of this combo box in pixel units. This section is identical to the corresponding section in the base property sheet apart from the type of units you use.
*Manual-Highlight — Normally cleared. Setting this box allows you to write code to define a custom highlight effect. Your custom effect will be applied whenever this combo box has input focus.
*Movable — Normally cleared. Setting this box makes it impossible for the user to give this combo box input focus by clicking with the mouse. Instead, the user can use the mouse to drag the combo box body—but not the label, which stays where it was—to a different position within the bounds of the enclosing frame.
*Resizable — Normally cleared. Setting this box makes it impossible for the user to give this combo box input focus by clicking with the mouse. Instead, if the Selectable box is also set, clicking with the mouse causes handles to appear so that the user can resize the object.
*Selectable — Normally cleared. Setting this box allows the user to select this combo box.
Caution: If you make this combo box Movable or Resizable, and you also set the No Tab Stop option in the base Property Sheet, you effectively prevent this object from ever gaining input focus.
Operating a basic combo box
The basic combo box widget consists of a joined fill-in and selection list. You can manipulate the contents of the list under program control.
Clearing the list buffer
The list of items is stored as a string, pointed at by the LIST-ITEMS attribute. You can clear the list by assigning the empty string. For example:
 
comboExample:LIST-ITEMS = "" .
Setting LIST-ITEMS to the empty string clears the buffer immediately.
Caution: The combo box widget is created with a single item in its list. You should always clear that item as part of your initialization process.
You can also use a loop to delete the line items one by one. For example:
 
DO WHILE comboExample:DELETE (1): /* empty statement */ END.
In the example code, the DELETE method is called in a WHILE loop to repeatedly delete line item 1. When the buffer is empty of lines, DELETE will return FALSE and the WHILE loop will terminate.
Adding a line item
Using the INSERT() method, you can add a line item at any offset in the list, regardless of the Sort option.
The ADD-FIRST() and ADD-LAST() methods have a different result depending on whether the Sort option is set. If the option is not set, new items will be added to the top or bottom of the list, depending on which method you call. If the Sort option is set, new items will be inserted in sorted order regardless of which method you call.
The INSERT(), ADD-FIRST() and ADD-LAST() methods all return TRUE if they succeed, and FALSE if they cannot perform the insertion:
*The following adds a simple item as the new fifth line:
 
comboExample:INSERT ( "Toy Item", 5 ).
*The following finds the first exact match of "Target Item" and inserts "Toy Item" as a new line above it:
 
comboExample:INSERT ( "Toy Item", "Target Item" ).
*The following adds a simple item as the new first line:
 
comboExample:ADD-FIRST ( "Toy Item" ).
*The following adds a simple item as the new last line:
 
comboExample:ADD-LAST ( "Toy Item" ).
If you are using simple line items—not item/value pairs—you can add more than one in a single call by combining them into a comma-separated list: "Item 1, Item 2, . . .,Item n".
*The following adds three simple items as the new 5th, 6th, and 7th lines:
 
comboExample:INSERT ( "Line 5 text,Line 6 text,Line 7 text", 5 ).
If you are adding item/value pairs, you can only add one line per call.
*The following adds three item/value pairs as the new 5th, 6th, and 7th lines, with values 25, 48, and 16:
 
comboExample:INSERT ( "Line 5", 25, 5).
comboExample:INSERT ( "Line 6", 48, 6).
comboExample:INSERT ( "Line 7", 16, 7).
Multiple item/value pairs cannot be added using a single call. The following code looks reasonable but would not compile successfully:
 
comboExample:ADD-FIRST ( "Line 5", 25, 5, 
                         "Line 6", 48, 6, 
                         "Line 7, 16, 7 ) .
Adding a user-supplied line item
Although a combo box appears to be a combined fill-in and list, you cannot capture user input as new items. The fill-in’s function is only to provide a way to select a list item other than by scrolling to find it.
To allow the user to add items to the list, use a separate fill-in to capture the text for the new item or item/value pair and call the appropriate insertion method to add it, as shown in the following:
The fiNewItem code, if used as the CHOOSE trigger for the pbAppend button, will move non-empty strings from the fill-in to the list in the combo box, as shown:
 
IF fiNewItem:SCREEN-VALUE <> "" THEN DO: /* ignore event if field empty */
  ASSIGN fiNewItem.                      /* set the value of the Fill-in */
  cbList:ADD-LAST( fiNewItem ).          /* append the new value to list */
  fiNewItem:SCREEN-VALUE = "".           /* clear Fill-in’s image... */
  fiNewItem = "" .                       /* ...and its value */
END.
Deleting a line from the list
Deleting a line requires only that you know the line number. The following code will delete line 5 if it exists:
 
comboExample:DELETE ( 5 ).
Finding a line or item in the list
*You can determine the line offset of some item using the LOOKUP() method, as shown:
 
lineoffset = comboExample:LOOKUP( "Line Item of Interest" ). 
Note that LOOKUP():
*Always finds the first instance of the string, if there are duplicates.
*Returns 0 (zero) if the string is not found.
*You can determine the string value of some item using the ENTRY() method, as shown:
 
strItemValue = comboExample:ENTRY ( 5 ).
Note that ENTRY() will complain and return the undefined value (?) if you pass an argument that does not index an item in the list.
Creating an ActiveX combo box instance
The ActiveX version of the combo box is also available on the Object Palette.
To create and place an ActiveX combo box instance:
1. Click the CSCombo Box in the Object Palette.
Be sure to select the one shown here. The other combo box icon (not shown) represents the version defined in ABL.
2. Move the mouse cursor over a bare spot in your workspace and click to place the new combo box.
3. Configure and size it.
Configuring an ActiveX combo box instance
ActiveX (OCX) objects are functionally similar to native ABL objects, but written to the Component Object Model (COM) standard defined by Microsoft. To adapt them for use in the OpenEdge environment, AppBuilder automatically supplies a two‑layer interface object, the control frame. Control frames translate between the COM world and the AVM world.
When you select an ActiveX (OCX) object and choose ToolsProperty Sheet, the dialog box that opens in response displays the few properties belonging to the ABL layer of the control frame. See the “ActiveX control frame properties” section for further information.
To open the properties dialog box for the combo box itself, double‑click on the object. The special ActiveX‑style properties dialog box appears:
References in your code to the native ActiveX properties of the combo box instance must take the indirect form Com‑Handle:ActiveX‑Identifier:Property‑Identifier.
Minimal configuration
While you can accept many of the default settings, you will need to make the following changes:
*Replace the default object identifier for the control frame with one that more clearly represents the role of this combo box instance in your application. You can do this directly in the main AppBuilder window, when the instance is selected. You need not change the identifier of the actual ActiveX object itself, though you can if you wish.
*Populate the list of choices that the combo box will use.
To populate the list of choices:
1. Click in the [Custom] property data field to expose the ellipsis (. . .) button, then click the ellipsis button to open the Custom Properties dialog box:
2. Choose the Contents tab to expose that field:
Type in this combo box’s list of items, one item per line. When finished, click OK to close the dialog box.
Additional property configuration
Choose from three different styles:
*0 Dropdown Combo — Default. The user can open and pick from the list, or type a value into the fill-in component. Note that this style is not the default style for the ABL combo box.
*1 Simple Combo — In this style, you must explicitly make the selection list component visible at design time, if it is to be visible at all. By default, AppBuilder generates the widget with only the fill-in visible. Drag the bottom handle to reveal as much of the list element as you like. In this style, the fill-in element is editable.
*2 Dropdown List — In this style, the fill-in component is read‑only—the user cannot type into it. The user can only open and pick from the list. The choice then appears in the fill-in component. Note that, in other taxonomies, a drop‑down list is a type of selection list, not a type of combo box configuration
Code configuration
When you run a workspace for the first time after placing your first ActiveX (OCX) object in it, AppBuilder creates the control_load procedure. You can inspect that procedure in the Section Editor, but not edit it.
In that procedure, AppBuilder creates the variable of type COM-HANDLE that you will use when you write event handlers. The identifier of the variable is the same as the identifier you assign to the control frame’s Object field, with ch prepended. Thus, if you assign the identifier Example to the control frame, the COM-HANDLE identifier will be chExample.
The combo box stores its current string value in the Value property. To determine the index value of that string (the topmost list item is index 0), pass the Value property to the FindStringExact() method.
Presuming you use the object identifier Example for the OCX control frame, this toy code will detect the user’s selection, and print out the string and index values:
 
/* Add to the Definitions section */
DEFINE VARIABLE sSelection AS CHARACTER NO-UNDO.
DEFINE VARIABLE iSelection AS INTEGER   NO-UNDO.
 
/* Add as the Trigger for event OCX.Click */
ASSIGN
  sSelection = chExample:CSComboBox:Value
  iSelection = chExample:CSComboBox:FindStringExact( sSelection, -1 ).
 
MESSAGE "Selection is " sSelection "at index" iSelection .
For further information about events, methods, and properties for the three OCX objects that AppBuilder supplies in the Object Palette, see the online help.