A ComboBox is a data handling widget that defines a drop-down list of values, allowing the user to select a value.
Purpose
The ComboBox underlying formField can be associated with a database column by changing the fieldType property to TABLE_COLUMN, and specifying the sqlTabName and colName properties.
Example
Figure 1. Combobox
Properties
case, color, colorCondition, comment, defaultValue, case, fontPitch, hidden, include, initializer, items, justify, notNull, noEntry, queryEditable, required, sample, scroll, sizePolicy, style, tag, tabIndex, Validate Like
Usage
The values of the drop-down list are defined by the items property. You can define a simple list of values like ("A","B","C","D", ... ) or you can define a list of key/label combinations like in ((1,"Paris"),(2,"Madrid"),(3,"London")). In the latter, the labels (i.e. the city names) will be displayed according to the key value (the city number) hold by the field.
The initializer property 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 with database records, for example. It is recommended that you use the tagproperty, so you can identify in the program the kind of ComboBox form item to be initialized.
If neither items nor initializer properties are specified, the form compiler automatically fills the list of items with the values of the include property, 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 property can be specified directly in the form or indirectly in the schema files.
During an INPUT, a ComboBox field value can only be one of the values specified in the items property. During an CONSTRUCT, a ComboBox field gets an additional 'empty' item (even if the field is notNull), to let the user clear the search condition.
If one of the items is explicitly defined with NULL and the notNull property is omitted; 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 a CONSTRUCT, a ComboBox is not editable by default: The end-user is forced to set one of the values of the list as defined by the items property, or set the 'empty' item. The queryEditable property can be used to force the ComboBox to be editable during a CONSTRUCT instruction, in order to allow free search criterion input such as "A*". If queryEditable is used and the items are defined with key/label combinations, the text entered by the user will be automatically searched in the list of items. If a label corresponds, the key will be used in the SQL criterion, otherwise the text entered by the user will be used. For example, if the items are defined as ((1,"Paris"),(2,"Madrid"),(3,"London")), and the user enters "Paris" in the field, the item (1,"Paris") will match and will be generate "colname = 1". If the user enters ">2", the text does not match any item so it will be used as is and generate the SQL "colname > 2". Users may enter values like "Par*", but in this case the runtime system will raise an error because this criterion does is not valid for the numeric data type of the field. To avoid end-user confusion, a ComboBox defined with key/label combinations should not use the queryEditable property.
Some front-ends support different presentation options which can be controlled by a style property. You can for example enable the first item to be selected when pressing keys.
Context Menu
The values in the list of items can be managed (add, delete) by right-clicking on the ComboBox on the form in Form Designer and selecting Edit Items. Edit the values in the columns of the dialog:
- Name - the value to be stored in the underlying formField represented by the ComboBox, for example, "W".
- Text - the value in the list to be displayed to the user, for example "West Region".
- Localize string - Specify whether the text is a localized string (true/false).