listCollection

The listCollection method of the ListBox and ComboBox classes (provided by the RootSchema) enables list box or combo box controls to have a collection attached to them. Logic attaches the collection to the list box or combo box by using the listCollection method. If you use this method to attach a collection to a list box or combo box, little is required to load entries into the list.

If the list box is not sorted, an entry is retrieved from the collection only when it is to be displayed or accessed by logic. Only a few entries from the collection are therefore initially accessed, instead of the entire contents of the collection (though if the list box is sorted, every element in the collection must be accessed). However, as you scroll through the collection, list box entries are not discarded, which means that for large collections, the list box can contain an unacceptably large number of entries. For this reason, listCollection should be used only for small collections that will never contain too many items.

When you call listCollection, you specify true or false for an update parameter. If the update parameter in the listCollection method is true:

• Deleting the collection results in the list box or combo box being cleared and the collection is no longer associated with the list box or combo box.

• Any changes to the collection cause the contents of the list box or combo box to be discarded and the collection is rebuilt to the current display point (the current entry is reselected if it still exists).

If the update parameter is set to false, the list box or combo box is not updated and can contain out‑of‑date information.

The view schema makes use of listCollection in several of its forms (for example, the zInitialize method of FormCommissionRate and FormLocationsList). By setting the update parameter to true, the individual controls handle synchronization of the data they are displaying.