Event XbpMenuBar():measureItem Foundation

Used by the system to determine the dimensions of an owner-drawn menu item.

Syntax
:measureItem := {| nItem, aDims, self | ... }
:measureItem( nItem, aDims ) --> self
xbeP_MeasureItem (1048648)
Parameters
<nItem>
Parameter <nItem> specifies the index/ordinal number of the menu item whose dimensions are to be measured.
<aDims> := {nWidth, nHeight}
<aInfo> is an array containing the menu item's dimensions.
Return

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

Description

The xbeP_MeasureItem event is generated by the Xbase++ runtime system to determine the dimensions of a menu item which is displayed using the owner-drawing feature. Owner-drawn menu items can be of variable height. Before a menu item gets displayed for the first time, the system sends a xbeP_MeasureItem event to determine the menu 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>.

The owner-drawing feature for a menu item is controlled by the XBPMENUBAR_MIA_OWNERDRAW attribute, which must be specified when the item is added to the menu bar object. Processing of the xbeP_MeasureItem event can be done within the :measureItem() method, or within the code block in the :measureItem instance variable. The method :measureItem() is executed followed by the code block in :measureItem.

The :measureItem() callback method in the XbpMenubar 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 XbpMenubar 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 XbpMenubar object. That 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 menu, performing lengthy operations during the processing of a xbeP_MeasureItem event is discouraged. Otherwise, responsitivity 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 all thread-local settings to be at their 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 XbpMenubar object.

Feedback

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.