listCollection

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.

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.

  1. 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;

  2. 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.

  3. 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.

  4. 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.

  5. 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.