Event XbpMenuBar():drawItem

Classes Class XbpMenuBar() :drawItem

Informs the application that an owner-drawn menubar item needs to be redrawn.

:drawItem := {| oPS, aInfo, self | ... }
:drawItem( oPS, aInfo ) --> self | lDefaultDraw
xbeP_DrawItem (1048649)

<oPS>

Parameter <oPS> contains a Micro Presentation Space object that must be used to draw the menu item specified in parameter <aInfo>. It can be used with the GRA functions to define the item's imagery.

<aInfo> := {nItem, nAction, nState, aRect}

<aInfo> is an array with four elements with information about the operation which caused the redraw as well as about the menu item's current selection state and bounding rectangle.

This method returns the object executing the method (self). The XbpMenuBar class also supports a logical value to be returned from method :drawItem(), or from a code block assigned to member :drawItem. This can be used to control the display of the arrow symbol next to an item opening a sub-menu. Returning .F. (false) prevents the system from displaying the arrow symbol. If the value .T. (true) or the XbpMenuBar object (self) is returned, the arrow symbol is shown.

The xbeP_DrawItem event is generated whenever an owner-drawn menu item must be redrawn. During processing of this event, the method :drawItem() is executed automatically to issue a redraw of the menu item by the Xbase++ application. If a code block is assigned to the :drawItem instance variable, that code block is also evaluated. Processing of the xbeP_DrawItem event can be done within the :drawItem() method, or within the code block in :drawItem. The method is executed first, then the code block is evaluated. 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.

Prior to drawing a menu item's current state, an Xbase++ application is expected to examine the information passed in parameter <aInfo>. The elements in the array specify the item's current state and dimensions, as well as the operation which caused the redraw of the menu item.

Element	Description
nItem	Index of the menu item that must be redrawn
nAction	Action or operation which caused xbeP_DrawItem event
nState	Current state of the menu item
aRect	Bounding rectangle for the drawing operation

Element nAction is a numerical value and can be a combination of the following values:

Constant	Description
XBP_DRAWACTION_DRAWALL	The whole menubar must be redrawn
XBP_DRAWACTION_SELCHANGE	The selected state of the item has changed

Element nState is a numerical value and can be a combination of the following values:

Constant	Description
XBP_DRAWSTATE_SELECTED	Item is currently selected
XBP_DRAWSTATE_DISABLED	Item is currently disabled
XBP_DRAWSTATE_DEFAULTITEM	Item is the default item of the menu
XBP_DRAWSTATE_GRAYED	Item is to be grayed
XBP_DRAWSTATE_CHECKED	Item is currently checked

The callback method implemented in the XbpMenubar class does not execute any code. Instead, the method is provided for overloading in user-defined subclasses. If owner-drawing is to be used with the XbpMenubar class itself (not a derived class), a code block must be assigned to the :drawItem callback slot.

The xbeP_DrawItem event is sent synchronously by the :handleEvent() method of an XbpMenubar object. This implies that xbeP_DrawItem events will not be retrieved by the AppEvent()function. The event is generated while the operating system redraws an application's user interface. Therefore, it is not advisable to perform lengthy operations during processing of xbeP_DrawItem. 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 :drawItem() callback method and the :drawItem callback code block are executed on that thread. Therefore, during processing of an xbeP_DrawItem message, the application must assume all thread-local settings to contain default values. For instance, a work area opened in an application thread may not be available. It is recommended to prepare all the data required for rendering before the menubar object is created. This ensures fast processing of xbeP_DrawItem events and prevents thread-dependencies.

Win2000, Debugging: On the Windows 2000 platform, the windows used to display owner-drawn menus are a shared resource. Hence, changes made by an application using owner-drawn menus may affect all running applications! If an Xbase++ application quits due to a runtime-error while processing an xbeP_DrawItem notification, the menus displayed by other applications (including Windows Explorer) may be displayed incorrectly afterwards. In this case, the machine usually has to be rebooted to correct the problem. However, this only occurs if transition effects are enabled for menus on Windows 2000 machines. When debugging your owner-drawing code on Windows 2000, it is therefore recommended to either disable menu effects, or to use a BEGIN/END SEQUENCE bracket to prevent run-time errors from terminating the application while rendering menus. To disable transition effects for menus, go to Control Panel and chose 'Display'. Disable the 'Use transition effects for menus and tooltips' check box on the 'Effects' tab.

Event XbpMenuBar():drawItem Foundation