Event XbpCombobox():drawItem Foundation

An item of a combobox object needs to be redrawn.

Syntax
:drawItem := {| oPS, aInfo, self | ... }
:drawItem( oPS, aInfo ) --> self
xbeP_DrawItem (1048649)
Parameters
<oPS>
Parameter <oPS> contains a Micro Presentation Space object that must be used to draw the list 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. It contains information about the item to be redrawn, the action which caused the redraw request, the combobox item's current selection state, and the bounding rectangle.
Return

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

Description

The xbeP_DrawItem event is generated whenever an item of an owner-drawn combobox must be redrawn. During processing of this event, the method :drawItem() is executed automatically to issue a redraw 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 is controlled via the :drawModeinstance variable of an XbpCombobox object.

Prior to drawing an item's current state, an Xbase++ application is expected to examine the information passed in the 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 combobox item. The columns of the <aInfo> array can be identified using symbolic constants defined in the file "xbp.ch".

Elements of the array in parameter <aInfo>
Element Constant Description
nItem XBP_DRAWINFO_ITEM Index of the item that must be redrawn
nAction XBP_DRAWINFO_ACTION Action or operation which caused xbeP_DrawItem event
nState XBP_DRAWINFO_STATE Current state of the item
aRect XBP_DRAWINFO_RECT Bounding rectangle for the drawing operation, a 4-element array of the form { nX1, nY1, nX2, nY2 } with the lower left and upper right corner points of the rectangle

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

Constants used with element nAction of <aInfo> array
Constant Description
XBP_DRAWACTION_DRAWALL The whole combobox must be redrawn
XBP_DRAWACTION_SELCHANGE The selected state of the item has changed
XBP_DRAWACTION_FOCUSCHANGE The combobox has gained or lost the input focus

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

Constants used with element nState of <aInfo> array
Constant Description
XBP_DRAWSTATE_SELECTED Item is currently selected
XBP_DRAWSTATE_DISABLED Item is currently disabled
XBP_DRAWSTATE_FOCUS Listbox currently has the input focus
XBP_DRAWSTATE_COMBOBOXEDIT The item to be drawn is the selected item of the combobox object. Drawing occurs in the edit field of the combobox.

The callback method implemented in the XbpCombobox 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 XbpCombobox 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 XbpCombobox 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 in that thread. Therefore, during processing of an xbeP_DrawItem message, the application must assume that all thread-local settings will contain default values. For example, 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 combobox object is created. This ensures fast processing of xbeP_DrawItem events and prevents thread-dependencies.

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.