COMBOBOX item type

COMBOBOX item basics

The COMBOBOX form item defines a field that can open a list of possible values the end user can choose from.

All COMBOBOX items will be transmitted to the front-end. Consider limiting the number of items to get better performances. When several hundred or thousand of items are possible, use a BUTTONEDIT instead of a COMBOBOX.

Defining a COMBOBOX

The values of the drop-down list are defined by the ITEMS attribute. Define a simple list of values like ("A","B","C","D", ... ) or a list of key/value pairs like in ((1,"Paris"),(2,"Madrid"),(3,"London")). In the second case, the labels (city names) display depending on the key value (the city number) held by the field.

COMBOBOX ...
   ITEMS=((1,"Paris"),(2,"Madrid"),(3,"London"));

COMBOBOX ...
   ITEMS=((1,%"cities.paris"),
          (2,%"cities.madrid"),
          (3,%"cities.london"));

The INITIALIZER attribute allows you to define an initialization function for the COMBOBOX. This function is invoked at runtime when the form is loaded, to fill the item list dynamically, for example with database records. It is recommended that you use the TAG attribute, so you can identify in the program the kind of COMBOBOX form item to be initialized. The initialization function name is converted to lowercase by fglform.

COMBOBOX ...
   TAG = "city", INITIALIZER = city_module.cmb_init;

If neither ITEMS nor INITIALIZER attributes are specified, the form compiler automatically fills the list of items with the values of the INCLUDE attribute, when specified. However, the item list will not automatically be populated with include range values (i.e. values defined using the TO keyword). The INCLUDE attribute can be specified directly in the form or indirectly in the schema files.

COMBOBOX ...
   INCLUDE=("A","B","C","D","E");

COMBOBOX ...
   ITEMS=((NULL,"<Undefined>"),
          (1,"Red"),
          (2,"Yellow"),
          (3,"Green"));

During an INPUT dialog, if the field allows NULL values, and no NULL item is specified in the item list, a NULL item (with empty label) will be added automatically at the end of the item list, to let the end-user set the field value to NULL. If the field is defined with NOT NULL, no default item for NULL will be added automatically.

During a CONSTRUCT dialog, the COMBOBOX drop down list allows to select multiple items, to produce "value1|value2|..." and generate the SQL condition "colname in (value1,value2,...)". If only one item is selected, the SQL condition will be "colname=value". To clear the query field, the user can deselect all items, or use the DEL key in the drop down list. If the field allows NULL, automatic items will be added to specify if a value is defined by using != (to generate "colname is not null"), or specify that the value is undefined by using "=" (to generate "colname is null"). If the item list contains an explicit item for NULL, selecting this item during a CONSTRUCT will set =, show the corresponding item label, and generate a "colname is null" SQL condition.

Avoid to define COMBOBOX items for NULL and CONSTRUCT operators "=", "!=": These are provided by default when the field allows nulls. Item labels are localized by default, and if really needed, they can be redefined with GBC customization.

A good practice is to deny nulls with the NOT NULL attribute, and add a special item such as (0,"<Undefined>") to identify a non-specified-value:

COMBOBOX ...
   NOT NULL,
   ITEMS=((0,"<Undefined>"),
          (1,"Red"),
          (2,"Yellow"),
          (3,"Green"));

COMBOBOX cb1 = customer.cust_city,
   AUTONEXT, ITEMS = ... ;

Detecting COMBOBOX item selection

To inform the dialog when the value changes, define an ON CHANGE block for the COMBOBOX field. The program can then react immediately to user changes in the field:

-- Form file (grid layout)
COMBOBOX cb1 = customer.cust_city,
   ITEMS = ... ;

-- Program file:
ON CHANGE cust_city
   -- A new item was selected in the combobox list

For more details, see Reacting to field value changes.

Where to use a COMBOBOX

A COMBOBOX form item can be defined with an item tag and a COMBOBOX item definition in a GRID, SCROLLGRID and TABLE/TREE.

Defining the widget size

The size of a COMBOBOX widget is computed from the SIZEPOLICY and SAMPLE attributes, and by following the layout rules as described in Widget width inside hbox tags.