Adding Records to a Paged List Box

A record is added to a paged list box in the same way that a record is added to a standard list box: by assigning the record to the ITEM-TO-ADD property. Most of the time, you will add records to the end of the list box (exception: you will need to add to the top of the list when responding to scroll-up requests from the user). You can, however, add records anywhere in the list, by using the INSERTION-INDEX property. Remember that paged list boxes are always unsorted, so you must add records in a fashion that preserves the sort-order of the full set of records.

An important and unusual feature of the paged list box is that it never contains more items than are needed to display one page (that is, they contain only what is shown on the screen). Whenever you add a record that would cause the list to grow larger than one page, the list box automatically deletes a record. If you add a record to the beginning of the list, the last record in the list is deleted (causing the box to appear to scroll upward). Inserting an item into any other position in the list causes the first record to be deleted (causing the box to appear to scroll downward if you are adding to the end). This automatic deletion is a coding convenience that frees you from having to worry about the list box growing larger than a complete page of data.

The following example adds one item to the end of the current list's contents:

modify list-1, item-to-add = keyword-word

Alternatively, this example shows how to add an item to the top of the list:

modify list-1, insertion-index = 1, 
   item-to-add = keyword-word

Remember that control properties are set in the order specified in the statement. In the preceding example, the INSERTION-INDEX phrase must appear before the ITEM-TO-ADD phrase in order to get the intended result.