Back to Contents

The ComboBox class

Summary:

• Syntax
• Methods
• Usage
  • Defining the default initializer for ComboBoxes
  • Searching for a ComboBox in the current form
  • Clearing the item list of a ComboBox
  • Adding an element to the ComboBox item list
  • Getting the name of the form field table prefix
  • Getting the name of the form field
  • Getting the ComboBox tag value
  • Getting the number of items in a ComboBox
  • Getting an item name by position
  • Getting an item position by name
  • Getting an item text by position
  • Getting an item text by item name
  • Removing an item from the ComboBox
• Examples

See also: Classes and Objects, Form Specification File

Syntax

The ComboBox class provides an interface to the COMBOBOX form field view in the Abstract User Interface tree.

Syntax:

ui.ComboBox

Methods:

Usage:

When you declare a COMBOBOX form field in the form specification file, you declare both a form field and a view for that model. The ComboBox class is an interface to the view of a COMBOBOX form field.

Defining the default initializer for ComboBoxes

Use the ui.ComboBox.setDefaultInitializer() class method to define the default initialization function that will be called each time a ComboBox object is created. That function is called with the ComboBox object as the parameter:

01 CALL ui.ComboBox.setDefaultInitializer("initcombobox")
02 
03 FUNCTION initcombobox(cb)
04   DEFINE cb ui.ComboBox
05   CALL cb.clear()
06   CALL cb.addItem(1,"Paris")
07   CALL cb.addItem(2,"London")
08   CALL cb.addItem(3,"Madrid")
09 END FUNCTION

Note that you must specify the initialization function name in lower-case letters to the setDefaultInitializer() method. The BDL syntax allows case-insensitive function names, but the runtime system must reference functions in lower-case letters internally. 

You can also define a specific initialization function in the form specification file, by using the INITIALIZER attribute (as shown in the second example below).

Searching for a ComboBox in the current form

The ui.ComboBox.forName() class method searches for a COMBOBOX object by form field name in the current form. Typically, after loading a form with OPEN WINDOW WITH FORM, you use the class method to retrieve a COMBOBOX view object into a variable defined as a ui.ComboBox:

01 DEFINE cb ui.ComboBox
02 LET cb = ui.ComboBox.forName("formonly.airport")

It is recommended that you verify if that function has returned an object, because the form field may not exist:

01 IF cb IS NULL THEN
02   ERROR "Form field not found in current form"
03   EXIT PROGRAM
04 END IF

Once instantiated, the ComboBox object can be used; for example, to set up the items of the drop down list:

01 CALL cb.clear()
02 CALL cb.addItem(1,"Paris")
03 CALL cb.addItem(2,"London")
04 CALL cb.addItem(3,"Madrid")

Clearing the item list of a ComboBox

The clear() method clears the item list. If the item list is empty, the ComboBox drop-down button will show an empty list on the client side.

Adding an element to the ComboBox item list

The addItem() method adds an item to the end of the list. It takes two parameters: the first is the real form field value, and the second is the value to be displayed in the drop down list. If the second parameter is NULL, the runtime system automatically uses the first parameter as the display value.

Trailing spaces should be avoided when populating the first parameter because values get truncated when field validation occurs, and the resulting value (without trailing spaces) will no longer match the ComboBox item name. Additionally, trailing spaces in the second parameter may cause the ComboBox to be much wider than expected. In order to avoid such problems, use VARCHAR or STRING variables, or use the CLIPPED operator with CHAR variables.

Getting the name of the form field table prefix

The getTableName() method returns the name of the form field table prefix. Not that this prefix can be NULL if not defined at the form field level.

Getting the name of the form field

The getColumnName() method returns the name of the form field table prefix. Not that this prefix can be NULL if not defined at the form field level.

You can use the getTableName() and getColumnName() methods to get the table and column name of the form field associated with the ComboBox:

01 DISPLAY cb.getTableName()||"."||cb.getColumnName()

Getting the ComboBox tag value

The getTag() method returns the value of the TAG attribute if defined in the form file.

Getting an item position by name

The getIndexOf() method takes an item name as parameter and returns the position of the item in the list. Returns 0 if the item name does not exist.

With this method you can check if an item exists:

01 IF cb.getIndexOf("SFO") == 0 THEN
02   CALL cb.addItem("SFO", "San Francisco International Airport, CA" )
03 END IF

Getting the number of items in a ComboBox

You can get the current number of items defined in a ComboBox with the getItemCount() method. If no items are defined, the method returns zero.

Getting an item name by position

The getItemName() method takes an item position as parameter and returns the identifier of that item. First item starts at position 1.

Getting an item text by position

The getItemText() method takes an item position as parameter and returns the value of that item. First item starts at position 1.

Getting an item text by name

The getTextOf() method takes an item name as parameter and returns the value of that item. Returns NULL if the item name does not exist.

Removing an item by name

Use the removeItem() method to delete an item from the ComboBox. Item name must be passed as parameter. 

Examples

Example 1: Get a COMBOBOX form field view and fill the item list

Form Specification File:

01 DATABASE FORMONLY
02 LAYOUT
03 GRID
04 {
05   Airport:  [cb01                 ]
06 }
07 END
08 END
09 ATTRIBUTES
10 COMBOBOX cb01 = FORMONLY.airport TYPE CHAR;
11 END

Program File:

01 MAIN
02   DEFINE cb ui.ComboBox
03   DEFINE airport CHAR(3)
04
05   OPEN FORM f1 FROM "combobox"
06   DISPLAY FORM f1
07   LET cb = ui.ComboBox.forName("formonly.airport")
08   IF cb IS NULL THEN
09      ERROR "Form field not found in current form"
10      EXIT PROGRAM
11   END IF
12   CALL cb.clear()
13   CALL cb.addItem("CDG", "Paris-Charles de Gaulle, France")
14   CALL cb.addItem("LCY", "London-City Airport, UK")
15   CALL cb.addItem("LHR", "London-Heathrow, UK")
16   CALL cb.addItem("FRA", "Frankfurt Airport, Germany")
17   IF cb.getIndexOf("SFO") == 0 THEN
18      CALL cb.addItem("SFO", "San Francisco International Airport, CA" )
19   END IF
20
21   INPUT BY NAME airport
22
23 END MAIN

Example 2: Using the INITIALIZER attribute in the form file

Form Specification File:

01 DATABASE FORMONLY
02 LAYOUT
03 GRID
04 {
05   Airport:  [cb01                 ]
06 }
07 END
08 END
09 ATTRIBUTES
10 COMBOBOX cb01 = FORMONLY.airport TYPE CHAR, INITIALIZER=initcombobox;
11 END

Initialization function:

01 FUNCTION initcombobox(cb)
02   DEFINE cb ui.ComboBox
03   CALL cb.clear()
04   CALL cb.addItem("CDG", "Paris-Charles de Gaulle, France")
05   CALL cb.addItem("LCY", "London-City Airport, UK")
06   CALL cb.addItem("LHR", "London-Heathrow, UK")
07   CALL cb.addItem("FRA", "Frankfurt Airport, Germany")
08   CALL cb.addItem("SFO", "San Francisco International Airport, CA" )
09 END FUNCTION