displayEntry(control: control-name input;
obj: Any;
lstIndex: Integer): String;
The displayEntry event occurs when a ComboBox or ListBox control is attached to a collection object and the text to be displayed for an entry in the collection is required.
When a collection is attached to a combo box or list box control by the listCollection method, an entry in the collection is accessed only when that entry is to be displayed in the list box for the control, or when logic accesses the object from the control (for example, accessing the itemBackColor property of the control).
You therefore do not need to write logic to fill the control, and only that portion of the control viewed or referred to needs to be accessed. For example, if the user views only the first 15 entries of the collection, the remaining entries (which may be hundreds or even thousands) are never accessed and substantial overheads are potentially saved. These processes can be done from standard logic, but where possible, this technique can save both logic and processing overheads.
To get the text to be displayed in the list box for each entry, the displayEntry event is called, which must return a string that is placed in the list box. If the displayEntry event is not implemented, a string informing the user that the event was not handled is placed in the list box instead.
If the displayEntry event returns an empty string, that entry is ignored and is not included in the list box. (The listCount method return value is adjusted when the displayEntry event method returns a null string.)
The object to be displayed is passed as a parameter (it must be cast to the required type for actual access). This would normally be a member of the
The text to be displayed is returned as a string. The position at which the entry is placed in the list box is also passed so that colors, levels, and so on can also be set.
If the sorted property of the combo box or list box is set to true, the entire contents of the collection is accessed during the listCollection call, with calls to the displayEntry event for each object. The lstIndex parameter is always valid and can be used to set properties of the item that is being added, even when the list is sorted (for example, itemBackColor). For sorted lists, an empty entry is added, which is sorted into its correct position after the displayEntry event returns.
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 has already returned a string and the number of entries in the collection that are yet to be accessed).
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. The method in the following example shows the use of the displayEntry event method.
list1_displayEntry(listbox: ListBox;
obj: Any;
lstIndex: Integer): String updating;
begin
return obj.Customer.surname & " " & obj.Customer.firstnames;
end;