COMBOBOX item type

Defines a line-edit with a drop-down list of values.

COMBOBOX item basics

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

Note: The COMBOBOX is best used for a short list of possible values (10 to 50, maximum).

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

Consider using localized strings when defining key/value pairs in the combobox items:

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

During an INPUT dialog, a COMBOBOX field value can only be one of the values specified in the ITEMS attribute. If the field allows NULL values, a NULL item can be placed anywhere in the combobox item list, to satisfy end-user preferences:

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 NULL item will be added automatically.

During a CONSTRUCT dialog, selecting the list item corresponding to null will be equivalent to the = query operator, which will generate a "colname is null" SQL condition. The COMBOBOX field gets an additional 'empty' item (even if the field is NOT NULL), to let the user clear the search condition. Some front-ends allow to select multiple items to produce the SQL condition "colname in (value1, value2, ... )".

A common 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"));

When using the AUTONEXT attribute, the focus will automatically go to the next editable field, when an item is selected from the combobox drop-down list:

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

Front-ends support different presentation and behavior options, which can be controlled by a STYLE attribute. For more details, see Style attributes common to all elements and ComboBox style attributes.

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 in different ways:

With an item tag and a COMBOBOX item definition in a grid-layout container (GRID, SCROLLGRID and TABLE).
As a COMBOBOX stack item in a STACK container.

Defining the widget size

In a grid-based layout, 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.

In a stack-based layout, the widget will take the full width available in the parent container.

COMBOBOX on mobile devices

On mobile devices, COMBOBOX form items are best used for a short list of possible values that can be displayed on a single page; for example, 4 to 6 elements. When a list expands to more than one page, it is recommended that you use a BUTTONEDIT with a zoom, which you can improve with a search button to find an exact item or to reduce the list of items to scroll.