Adding lines to a listbox¶
listbox_add() |
Add one or more lines to a listbox |
SYNTAX
listbox_add(listbox_id, field_id | expression, line)
Adds one or more lines to a listbox.
The field_id is the field containing the value to be added.
If field_id is an array-type field (singly or multiply dimensioned) and no subscript is specified in the function call, then all non-null values in the array are added to the listbox. This feature enables a listbox to be populated with a single call to the function.
An expression may be used in place of a field_id to add a single line to a listbox.
The line specifies the line number for the first value added. If more than one line is added, they are numbered consecutively. The original line at line and all subsequent lines are renumbered higher.
If line is 0, or is higher than the existing number of lines, the lines are appended to the current list.
If line is greater than (the current number of lines + 1), it is reduced to that number. The new line(s) are appended to the existing lines with no intervening blanks.
The only way to include a blank line as a valid listbox value is by assigning it individually, i.e. it cannot be a value in an array-type field_id. Such fields are ignored. Note also that the value must be supplied as an expression, e.g.:
listbox_add(ListBox, "", 1)
and not as a field_id. If a field_id is used the line will not be added, and nor will higher-numbered lines. This is a bug.
If the listbox is LIST_BUTTON or LIST_EDIT, and the list is currently empty, then the first line added is automatically selected. If the list is not empty, the current selection is not changed.
A convenient time to populate a listbox is during the EV_CREATE event of the listbox or of its parent window.
The function returns zero if the lines were added, or a non-zero value if the lines could not be added due to insufficient memory.
EXAMPLE
This example adds 20 lines to the listbox “List1”. The omission of a subscript from the array field “tmp.LineText” from the listbox_add function call causes all non-null values to be added.
!temp LineText,,a20[20]
!temp Line,,u1
tmp.Line = 1
while (tmp.Line <= 20) {
tmp.LineText[tmp.Line] = "This is line " + tostr(tmp.Line)
tmp.Line = tmp.Line + 1
}
listbox_add(List1, tmp.LineText, 0)
RELATED TOPICS |