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.

Note: Such form field should be 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/label pairs like in ((1,"Paris"),(2,"Madrid"),(3,"London")). In the second case, the labels (i.e. the city names) display according to 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 will be 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=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, consider adding an item to reference the NULL value. However, the best practice is to deny nulls with the NOT NULL attribute, and add a special item such as (0,"<Undefined>") to specify a non-specified-value:

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

Note: If one of the items is explicitly defined with NULL; In INPUT, selecting the corresponding combobox list item sets the field value to null. In CONSTRUCT, selecting the list item corresponding to null will be equivalent to the = query operator, which will generate a "colname is null" SQL condition. During an CONSTRUCT, a 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 support different presentation and behavior options, which can be controlled by a STYLE attribute. For more details, see Common style attributes 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
   -- An 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 two 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 according to the SIZEPOLICY and SAMPLE attributes, and according to layout rules as described in Widget size within hbox tags.

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

COMBOBOX on mobile devices

On a mobile devices, COMBOBOX form items should be used for a short list of values that can be displayed on a single page; for example, 4 to 6 elements. When a list will expand 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.