ADD-FIRST( ) method

Adds one or more items to the top of a combo box or selection list.

Return type:

LOGICAL

Applies to:

BROWSE widget (column), COMBO-BOX widget, SELECTION-LIST widget

 

Syntax 

ADD-FIRST ( { item-list | label , value } )

item-list

A character-string expression that represents one or more items, delimiter-separated.

label

A character-string expression that represents the label of a label-value pair.

value

The value the AVM assigns to the field or variable if the user selects the corresponding label.

The delimiter is the value of the DELIMITER attribute, which defaults to comma. If the SORT attribute is TRUE, the AVM sorts new items by label before adding them to the widget. If the operation is successful, ADD-FIRST returns TRUE.

If the widget’s entries consist of single items, use item-list. If the widget’s entries consist of label-value pairs, use label and value.

If the widget’s entries consist of single items, each call to ADD-FIRST can add multiple entries. If the widget’s entries consist of label-value pairs, each call to ADD-FIRST can add one entry.

For browses, this method applies only to combo-box browse columns.

The following examples modify widgets whose entries consist of single items:

 

return-code = my-widget-hdl:ADD-FIRST("Seoul").

 

return-code = my-widget-hdl:ADD-FIRST("Bogota, Seoul, Los Angeles").

The following example modifies a combo-box widget of type INTEGER whose entries consist of label-value pairs:

 

return-code = my-widget-hdl:ADD-FIRST("Bogota", 15).