listCollection(c: Collection; update: Boolean; showHow: Integer);
The listCollection method of the ListBox and ComboBox class enables list box or combo box controls to have a collection attached to them. If you use this method to attach a collection to a ListBox or ComboBox control, little is required to load the entries into the list. Use the displayCollection method to automatically attach only as many entries as required to fill the list of the control. The differences between the listCollection method and the displayCollection method are as follows.
The listCollection method retains all entries added to the list or combo box when the user scrolls the view.
For the listCollection method, the number of entries in the list (returned by listCount) is logically the size of the attached collection minus discarded entries. For the displayCollection method, the listCount method returns only the number of entries that are displayed.
The displayCollection method enables you to specify a starting object.
Entries in the collection are retrieved only when the entry is to be displayed or it is accessed by logic; for example, only 15 entries from the collection may initially be accessed instead of the entire contents of the collection (which may be hundreds, or even thousands). You must therefore ensure that this collection remains valid for the lifetime of the control for which you called the listCollection method.
The ListBox class listCollection method handles a virtual collection, but only in the forward direction. (Attempting to call the displayCollection method in a ListBox or Table control with a virtual collection is rejected and an exception is raised.)
The listCollection method is not available in tables on forms in Web-enabled applications, as the HTML framework cannot predict the final size of the table and adjust the HTML page accordingly. If you want to ensure that all possible entries in the table are displayed on a Web page, use some other "virtual window" for the Web generation, or populate the table with all entries from the underlying collection if you know the number of rows will not cause excessive page size.
The parameters passed in the listCollection method are listed in the following table.
Parameter | Description |
---|---|
c | Specifies the attached collection and can be any type of collection |
update | If true, changes to the collection are to be reflected in the list box (not available for transient objects) |
showHow | If 0, displays the collection in collection order, and if 1, displays the collection in reverse collection order |
The ListBox class listCollection method handles a virtual collection, but only in the forward direction. (Attempting to call the displayCollection method in a ListBox or Table control with a virtual collection (for example, myClass.instances) is rejected and an exception is raised. Virtual collections do not implement the methods required by the displayCollection method).
The attachment of a collection to a list box or combo box functions as follows.
Logic attaches the collection to the list box or combo box, by using the listCollection method, as shown in the following example that associates a collection with a list box called listProducts.
load() updating; vars company : Company; begin company := Company.firstInstance; listProducts.listCollection(company.allProducts, true, 0); end;
The collection is displayed in order (or reverse order) of the entries in the collection, unless the value of the sorted property for the list box is set to true.
To specify the text to be displayed for each entry in the collection, the displayEntry event for the list box or combo box is called, as shown in the method in the following example.
listProducts_displayEntry(listbox: ListBox input; obj: Any; lstIndex: Integer): String updating; vars prod : Product; begin prod := obj.Product; return " " & prod.code & " " & prod.name & " "; end;
The displayEntry event uses the parameters listed in the following table.
Parameter | Description |
---|---|
control-type | Passes the type of control; that is, ListBox or ComboBox. |
obj | Passes the object to be displayed (it must be cast to the required type for actual access). |
lstIndex | Passes the position at which the entry is placed in the list box or combo box, so that colors, levels, and so on can also be set. The text to be displayed is returned as a string. (It is the responsibility of the JADE developer to pass the text back.) |
If the displayEntry event returns an empty string, that entry is ignored and is not included in the list box and no further items in the collection are displayed. When the listCollection method is used to associate a collection with a list box or combo box, the itemObject property contains a reference to the object displayed in each entry of the list box or combo box.
When an exception is raised by the displayEntry or displayRow event method, the size of the collection is treated as being one less than the number of entries already processed.
No further attempts are made to access the additional entries from the collection until a new displayCollection or listCollection method is executed against the control.
If the value of the sorted property is true, the entire contents of the collection are accessed during the listCollection method call, with calls to the displayEntry event for each collection object.
If the update parameter is set to 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 may contain out-dated information.
The value of the update parameter must be false for transient collections, as JADE does not issue system notifications for the addition, change, or deletion of a transient collection.
The following conditions apply to a list box or combo box with an attached collection.
The addItem and removeItem methods are not available.
The itemObject property returns the collection member for each entry. In this case, the itemObject property is read-only.
The getCollection method returns the collection attached to the combo box, list box, or current sheet of the table.
The clear method clears the list box or combo box and detaches the collection from the list box or combo box.
The list box or combo box has a
When the listCollection method is used with the listCount method, the value returned by the listCount method is the logical number of entries in the list box or combo box (that is, it returns a total of the number of entries for which the displayEntry event method has already returned a string and the number of entries in the collection that are yet to be accessed).
Setting the topIndex property causes the list box to be filled with entries up to that point when using the listCollection method and the topIndex property value is greater than the entries that are obtained so far.