Back to Contents

The ComboBox class

Summary:

• Basics
• Examples

See also: Built-in Classes, Form Specification File

Basics

Purpose:

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 an a view for that model. The ComboBox class is an interface to the view of a COMBOBOX form field.

The ui.ComboBox.forName() 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.field1")

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")

The clear() method clears the 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:

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()

With the ui.ComboBox.setDefaultInitializer() class method, you can set 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 

Warning: You must give 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).

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   ComboBox example:  [cb01                 ]
06 }
07 END
08 END
09 ATTRIBUTES
10 COMBOBOX cb01 = FORMONLY.field1 TYPE INTEGER;
11 END

Program File:

01 MAIN
02   DEFINE cb ui.ComboBox
03   DEFINE field1 INTEGER
04
05   OPEN WINDOW w1 AT 1,1 WITH FORM "combobox"
06   LET cb = ui.ComboBox.forName("formonly.field1")
07   IF cb IS NULL THEN
08      ERROR "Form field not found in current form"
09      EXIT PROGRAM
10   END IF
11   CALL cb.clear()
12   CALL cb.addItem(1,"Paris")
13   CALL cb.addItem(2,"London")
14   CALL cb.addItem(3,"Madrid")
15
16   INPUT BY NAME field1
17
18 END MAIN

Example 2: Using the INITIALIZER attribute in the form file:

Form Specification File:

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

Program File:

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