Event XbpListBox():measureItem

Compute dimensions of an owner-drawn listbox item.

:measureItem := {| nItem, aDims, self | ... }
:measureItem( nItem, aDims ) --> self
xbeP_MeasureItem (1048648)

<nItem>

Parameter <nItem> specifies the index/ordinal number of the listbox item whose dimensions are to be measured.

<aDims> := {nWidth, nHeight}

<aDims> is an array containing the item's dimensions. The array elements contain the width and height of the listbox item.

This method returns the object executing the method (self).

The xbeP_MeasureItem event is generated by the Xbase++ runtime system to determine the item dimensions in an owner-drawn listbox. Depending on the draw mode selected, owner-drawn listbox items may be of variable height. Before an item gets displayed for the first time, the system sends a xbeP_MeasureItem event to determine the item's dimensions, which must be computed by the application. Upon reception of the event, the item width and height must be stored into the respective array elements in parameter <aDims>.

This owner-drawing feature is controlled via the :drawMode instance variable. If the XBP_DRAW_OWNER draw mode is active, all items within the listbox have the same height. xbeP_MeasureItem is sent only once in this case. If the draw mode is XBP_DRAW_OWNERADVANCED, however, listbox items may be of different height. In this case the system sends an xbeP_MeasureItem event for each item in the listbox. Processing of the xbeP_MeasureItem event can be done within the :measureItem() method, or within a code block in instance variable :measureItem. The method :measureItem() is executed followed by the code block in :measureItem.

The :measureItem() callback method in the XbpListbox class does not execute any code, but is provided for user defined subclasses that redefine this method instead of using the callback code block. If owner-drawing is to be used with the XbpListbox class itself (not a derived class), a code block must be assigned to the :measureItem callback slot.

The xbeP_MeasureItem event is sent synchronously via the :handleEvent() method of an XbpListbox object. This means that xbeP_MeasureItem events will not be retrieved by the AppEvent()function. Because the event is usually generated while items are being added to a listbox, performing lengthy operations during the processing of an xbeP_MeasureItem event is discouraged. Otherwise, responsiveness of the application's user interface may be slow.

In Xbase++, Xbase Parts are created and maintained by a special system thread called the UI thread. Both the :measureItem() callback method and the :measureItem callback code block are executed on that thread. Therefore, during processing of an xbeP_MeasureItem message, the application must assume that all thread-local settings will contain default values. A work area opened previously may not be available, for example. To prevent thread-dependencies and to allow for a speedy processing of a xbeP_MeasureItem event, it is recommended for the application to prepare data required for computing item dimensions before items are added to the XbpListbox object.

The height of a listbox item cannot exceed 255 pixels under Windows.

If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.

Event XbpListBox():measureItem Foundation