Tutorial 2008-03: Dynamic Combo List Box

The dynamic combo list box can be pupulated with static form data and dynamically within the 4gl code. Combo List Box entries are fully manageable with standard 4GL function calls.

In Querix 4GL versions prior to 4.3 and BDS (Dynamic 4GL), combo boxes were populated statically using an INCLUDE statement as part of the Form file.

With Version 4.3 and later, Combo Widgets no longer carry this limitation; instead, management of the Combo/List field is done with a set of functions. In other words, combo box entries are fully manageable with standard 4GL function calls.

.

Form Definition Attributes Syntax:

<tag> =  <field>, 
  widget=”combo”
  include=(item 1, item2, item n);

To include numeric values in the list (form only fields), type=<data type> is required

Example of a combo field definition with default list data

ATTRIBUTES
f_combo=formonly.f_combo,
 widget="combo",
   class="combo",
 include=("Monday",
  "Tuesday",
  "Wednesday",
  "Thursday",
  "Friday",
  "Saturday",
  "Sunday");

Screen space issue with small combo list fields (width)

Because of it’s field decoration (button), Combo lists (just like function button fields) require more space than normal fields.
Never define a combo field in the screen section with only one character space.

Screen section example

[f]  Would  never be able to show the value
[f ] Would be enough space to show a single char

Difference between List Box and Combo Box

A list box allows the user to select a pre-defined set of data (default)
A combo box allows the both, to select a pre-defined set of data OR to enter data freely

The default behaviour is 'List box' . To define a list box to a combo box add following line to the form field definition

CLASS = “combo”

Example:

f1 =  country, 
  widget=”combo”,
  class="combo",
  include=("item 1", "item 2", "item n");

Normal Include Field to Combo auto-converter

By default, all normal fields with an include clause will be rendered as combo list boxes.
For better control, we recommend to change all normal fields which should be rendered as combo lists with combo/list box widgets in the form definition.

This auto-converter can be turned off by using the field level script option:

App.win.form.field.noCombo : TRUE
Example ?.?.?.?.noCombo: TRUE will turn it off globally

Combo List Management Functions are:

fgl_list_set(field_name, index, value)  - Replaces an existing entry.
fgl_list_insert(field_name, index, value) – Inserts a new entry
fgl_list_count(field_name) - Counts the number of items.
fgl_list_clear(field_name, index-start, index-end) - Deletes an entry (or range)
fgl_list_restore(field_name) - Restores the ‘Include’ list
fgl_list_get(field_name, index) - Retrieves a specific item
gl_list_sort(field_name,direction) – Sorts Asc. Or Descending
fgl_list_find(field_name, value) -  Searches for an entry.

Information on the arguments:

<field_name> is the form field name of the combo field. The name must be specified as a string. i.e. "my_field"
<index> The combo list can be seen as a one dimensional array. The index (type integer) specifies the location of an entry within this list. The list can not have empty entries. Creating/Inserting two entries on index position 1 and 3, will create the entries on index position 1 and 2.
<index start/end> defines simply a range of entries within the entry array.
<value> is the entry value - example "Monday" or "Tuesday"
<direction> boolean value used for specifying the sorting direction. 1=Up/Ascending 0=Down/Descending

The difference between fgl_list_insert() and fgl_list_set()

fgl_list_set() replaces the entry if it exists on the specified index location. Otherwise, it will operate identical to fgl_list_insert()

Adding a new entry to the end of the list

Simply use a large index number i.e. 9999 to add an entry to the end of the list. This saves you the time to query the list for the last used index number.

Detailed information on each of this functions can be found in the 'Build in Functions Guide'

Example function to populate a combo list dynamically

FUNCTION populate_data_combo_list(p_cb_field_name)
  …  
  DECLARE c_string_scroll2 CURSOR FOR
     SELECT qxt_string_tool.string_data
      FROM qxt_string_tool
      ORDER BY string_data ASC
   … 
  LET count = 1 
  FOREACH c_string_scroll2 INTO l_string_data
     CALL fgl_list_set(p_cb_field_name,count,l_string_data)
     LET count = count + 1
  END FOREACH
END FUNCTION

Example - allowing the user to update the combo list

#f1 is the combo field name
#v1 is the combo field variable
INPUT...f1...v1
  ...
  AFTER Field f1
    IF NOT fgl_list_find("f1", v1) THEN      --  Searches for an entry.
      CALL fgl_list_insert("f1", 9999, v1) – Inserts the new entry
    END IF
...
END INPUT

Updating the selected list entry to the field variable

The selected combo list entry is written to the variable when the cursor leaves the field (i.e. navigation to another field). You could however, add the attribute 'AUTONEXT' in the form definition to autmatically update the variable after an item is picked from the list.

Example:

f1 =  country,
  widget=”combo”,
  AUTONEXT,
  include=(item 1, item2, item n);

Combo Box navigation for the operator/user

The field level sript option 4glCombo defines, if the combo field should behavour in a classic 4gl manner or modern windows behaivour
4glCombo: TRUE #Classic
4glCombo: FALSE #Modern

The main difference between the two is the navigation behaivour for the use. FALSE (which is default) insructs the client to use a Windows style navigation.

NOTE:

It will also sort the entries in ascending order automatically.

Navigation for the operator/user by default

(4glCombo: FALSE)

Cursor Key
Up – Down Cursors for Navigation
Alpha-numeric Key Presses
Typing an alpha-numeric character while the focus is on the combo box will return a value pertaining to the first letter of the character entered

Demo Program

The combo list management functions are also demonstrated with the demo program 'fgl_list_xxx_function' located in the functions demo project.