displayCollection

displayCollection(c:          Collection;     (Table)
                  update:     Boolean;
                  showHow:    Integer;
                  startObj:   Object);

displayCollection(c:          Collection;     (ComboBox, ListBox)
                  update:     Boolean;
                  showHow:    Integer;
                  startObj:   Object;
                  extraEntry: String);

The displayCollection method enables a collection to be attached to the current sheet of a Table control, to the list portion of a ComboBox control, or to a ListBox control.

The displayCollection method parameters are listed in the following table.

Parameter	Description
c	Specifies the attached collection and can be any type of object collection. The scrolling and positioning of non-object collections cannot be handled, and calling displayCollection with such collections is rejected. (The topRow property is set to the first non-fixed row when using attached collections.)
update	If true, changes to the collection are reflected in the control. (This parameter does not apply to transient objects.)
showHow	Specifies an effective bit mask, which defines whether the collection is accessed forward or reversed or whether the user can scroll prior to the start object. (If the start object is null, this option has no effect.)
startObj	Specifies the object in the collection from which to start. If this parameter is not specified (that is, it is null), it starts at the beginning (or end) of the collection.
extraEntry	For ComboBox and ListBox controls only, determines whether the displayed list includes an extra entry.

When the displayCollection method is called, the number of rows in that sheet or list is set to the number of fixed rows defined for that sheet or list. Each collection entry adds a non-fixed row to the sheet or list, unless the displayRow event method indicates that an entry is to be ignored. The definition of the fixed rows of the sheet or list remains untouched.

When this method is called, the sheet or list contains the number of rows required to fully fill the visible portion of the table or list. (The actual number could be slightly more, to cater for the scroll bar being present.) As the entries are scrolled, the entries no longer visible are removed from the table or list and additional entries are obtained from the collection, as required. The initial entries in the table or list are displayed automatically when the displayCollection method is called, causing the table or list to access any collection entries required to fill the display size.

When the selected item is scrolled out of view, it is deselected. This deselection behavior can be avoided for list boxes and combo boxes by using the listCollection method instead of displayCollection.

You can drag the scroll bar thumb of ListBox and Table controls when a collection is attached to the list or table using the displayCollection method and the collection is an Array, Dictionary, or Set. The Collection class indexNear method determines the approximate position of a displayed object and the Iterator class startNearIndex method positions the displayed entries.

Implementing this feature has the following side effects.

If the bcontinue parameter returns false, the list size is adjusted and remembered. However, users can drag the list past that entry without the displayRow event being called for that entry, and as a result, JADE is unaware that the display size was to be limited. The bcontinue parameter therefore cannot be relied on to limit the display up to the required point.
The thumb track reflects the relative position in the collection from the start point (forwards or backwards, as required), regardless of whether entries have been left out of the display.
The use of the startNearIndex method is a shortcut method of approximating the required position through the collection based on the estimated size of segments of the collections (for example, Btree segments). However, if the collection population is distorted, the estimation may result in strange behavior, where dragging the thumb could result in the same position being shown or even going the wrong way through the collection.

For both ListBox and Table controls, Ctrl+Home positions the display to the first entry in the collection list and Ctrl+End displays the last entry in the collection list.

Use the getCollection method to return the collection attached to the control or the clear method to detach a collection from a control and clear the contents of the control.

The entries in the table or list can be accessed from logic, but the content of a table or list is treated as though it is the complete set of data. Access to rows that are not displayed is therefore not available. 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 ListBox class listCollection method handles a virtual collection, but only in the forward direction.

As the table holds only the displayed entries, no sorting can be performed. Any defined sort columns are ignored.

The displayCollection method and the related displayRow method should not be used in a Web-enabled JADE forms application because they provide a small virtual window over the underlying collection of potentially thousands of objects. The HTML generated contains only the entries required to fill the virtual window and (unlike a GUI application) does not provide a scroll bar to access additional entries.

For a Web-enabled JADE forms application, use the addItem method to populate the ComboBox, ListBox, or Table control with collection entries to be displayed.

When the table is at the bottom of the collection and there are no more rows to display, pressing the Page Down key selects the last row in the table. Similarly, the Page Up key selects the first row in the table when at the top of the collection. When paging down, the last entry is displayed on the next page only if the row is not fully displayed in the table.

Use the ComboBox, ListBox, or Table class constants listed in the following table in the showHow parameter to control access to a table or list collection.

Class Constant	Integer Value	Description
DisplayCollection_Forward	0	Display the collection forwards
DisplayCollection_Reversed	1	Display the collection reversed
DisplayCollection_NoPrior	0	No access to collection entries prior to start object
DisplayCollection_Prior	2	Allow access to entries prior to start object

To specify multiple collection access options, combine the options by adding them, as shown in the following code fragment.

table1.displayCollection(myColl, true, DisplayCollection_Forward +
                         DisplayCollection_Prior, startObj);

As a combo box is scrolled, entries that are not visible are removed from the list. If the currently selected item is removed, the listIndex property is set to -1 and the combo box text is cleared. The findObject method searches only the entries that are currently loaded when the displayCollection method is called.

If the value of the extraEntry parameter for a ComboBox or ListBox control is null (""), the parameter is ignored and the displayed list consists only of collection entries. If the extraEntry parameter contains a non-null string, the displayed list includes an extra entry, using the specified string.

The entry is treated as though it is the first entry in the collection (or the last entry, when the collection is displayed in reverse order). The exception to this is when a start object (specified in the startObj parameter) is requested and the showHow parameter value does not include DisplayCollection_Prior. In this case, the extra entry is treated as though it is the starting object, followed by the real starting object in the list. The extra object has a null row object associated with it in the list box and can be recognized by using that null row object (for example, if list.itemObject[list.listIndex] = null then ...).

The code fragment in the following example shows the use of the extraEntry parameter.

listbox1.displayCollection(custlist, true, 0, null, "<Default>");

If the object is already displayed in a ComboBox or ListBox list, the listIndex property value is set to the existing list entry. If the object is not in the displayed list, the current list is discarded. The iterator position within the collection is then adjusted so that the rebuilt display list includes the requested object. The listIndex property is then set to the list entry of the requested object. If the object cannot be found within the collection, an exception is raised.

If a collection is attached to a combo box or list box by using the listCollection method and the object is not in the displayed list, additional entries from the collection are added until that entry is included.

In addition, when the displayCollection method of the ComboBox or ListBox class is called with the extraEntry parameter set to a string value and the listObject property is set to null, the value of the listIndex property is set to the extraEntry list entry value (which is always 1). If that entry is not in the list that is currently displayed, the current list is discarded, restarted from the beginning of the collection entries, and includes the extra entry.

Setting the listIndex property to -1 remains unchanged; that is, no entry is selected.

When a collection is associated with a sheet of a control, the following restrictions apply.

The addItem, addItemAt, removeItem, Table::resort, Table::moveRow, and Table::deleteRow methods are not available.

As the scrolling of the control relies on the object associated with each row, the scrolling principle would break down with the use of these methods. In addition, the number of rows cannot be changed (although the number of fixed rows can be).
The clear, displayCollection, and Table::deleteSheet methods cannot be called for a sheet or list from the displayRow event method for that sheet or list.
The itemObject property for a row is set to the collection object for that row. This value cannot be changed.

If prior access to the start object is allowed and there are insufficient entries in the collection after the start object to fill the control, prior entries are inserted at the top of the control (that is, the requested start object may not be the first entry in the control).

The processing of the displayCollection method functions as follows.

Logic attaches the collection to the control by using the displayCollection method, as shown in the method in the following example that associates a collection with a table called ListProducts.
```
load() updating;
vars
    company : Company;
begin
    company := Company.firstInstance;
    tableProducts.displayCollection(company.allProducts, true, 0, null);
end;
```
Any existing displayCollection for that control is discarded.
The number of rows for that control is set to the number of fixed rows for a Table control or to zero (0) for a ComboBox or ListBox control.
If a starting object is specified in the startObj parameter, the collection entries are extracted, starting with the specified entry.
The displayRow event method is called for each entry in the collection, as required, and only the number of entries that are need to fill the table or list are accessed.
When the control is scrolled, non-visible entries are discarded and additional entries are obtained by using the displayRow event method.
This process continued until the end of the collection is reached or the displayRow event method indicates that the entries in the collection beyond this point are to be ignored.