Classes Class XbpBrowse() :customDrawCell

Event XbpBrowse():customDrawCell Foundation

A cell within an owner-drawn browse object needs to be redrawn.

Syntax 
:customDrawCell := {| oPS, aInfo, self | ... }
:customDrawCell( oPS, aInfo ) --> self | lDefaultDraw
xbeP_CustomDrawCell (1048649)
Parameters
<oPS>
Parameter <oPS> contains a Micro Presentation Space object that must be used to draw the browse cell. It can be used with the GRA functions to define the cell's imagery.
<aInfo> := {nRow, nAction, nState, aRect, oArea, oCol}
<aInfo> is an array with six elements with information about the operation that caused the redraw as well as about the cell's current selection state and bounding rectangle.
Return

This method returns the object executing the method. The XbpBrowse class also supports a logical value to be returned from method :customDrawCell(), or from a code block assigned to member :customDrawCell. Returning self or the value .T. (true) causes the object to perform default rendering. This depends on the drawing mode as well as on the current state of the browse object. See below for further information.

Description

The xbeP_CustomDrawCell event is generated whenever cells of an owner-drawn browse must be redrawn. During processing of this event, the method :customDrawCell() is executed automatically to issue a redraw of the cells by the Xbase++ application. If a code block is assigned to the :customDrawCell instance variable, that code block is also evaluated. Processing of the xbeP_CustomDrawCell event can be done within the :customDrawCell() method, or within the code block in :customDrawCell. The method is executed first, then the code block is evaluated. The owner-drawing feature is controlled via the :drawModeinstance variable of an XbpBrowse object.

Prior to drawing a cell of the browse, an Xbase++ application is expected to examine the information passed in parameter <aInfo>. The elements in the array specify the cell's current state and dimensions, as well as the operation which caused the redraw. 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
nRow XBP_DRAWINFO_ITEM Number of the row that contains the cell
nAction XBP_DRAWINFO_ACTION Action or operation which caused xbeP_CustomDrawCell event
nState XBP_DRAWINFO_STATE Current state of the cell
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
oArea XBP_DRAWINFO_AREA Column area (header, footer etc.) that contains the cell
oCol XBP_DRAWINFO_COLUMN XbpColumn object that contains the cell

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_SELCHANGE The highlight state of the cell is changed.
XBP_DRAWACTION_ERASEBG *) The system is about to erase the background prior to rendering the cells in a column. Default processing of this action draws the background of the whole column using the frame type selected via the XBP_PP_COL_xx_FRAMELAYOUT presentation parameter. If XBP_FRAME_NONE is selected, this action is not used. Erasing the background is required once during each column redraw operation. Member nRow has no meaning with this action (nRow = 0). The application must return .F. to prevent the system from performing default processing for this action.
XBP_DRAWACTION_DRAWBG *) System is about to draw the background of the cell. By default, the style image corresponding to the current cell state is drawn if a visual style is used. Otherwise, the system uses the cell background or hilight color to draw the background. The value .F. (false) must be returned by the application to prevent the system from performing these actions.
XBP_DRAWACTION_DRAWFRAME *) The system is about to draw a cell frame or highlight mark. The default processing of this action draws the cell frame set via the XBP_PP_COL_xx_CELLFRAMELAYOUT presentation parameter. For highlighted cells, the frame set via the XBP_PP_COL_DA_HILITEFRAMELAYOUT presentation parameter is used. This action is not requested if XBP_FRAME_NONE is specified for the respective setting. The application must return .F. to prevent the system from drawing the default frame.
XBP_DRAWACTION_DRAWFG System is about to draw the caption or image within the cell. The application must return .F. if a custom caption is drawn, eg. using the Graphics Engine.
  1. Generated in XBP_DRAW_OWNERADVANCED drawing mode only!

Note that the table above is in execution order. The drawing actions listed are requested by the system ordered from top to bottom.

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_NORMAL Column is in default state
XBP_DRAWSTATE_SELECTED Cell is currently selected
XBP_DRAWSTATE_DISABLED Column is currently disabled
XBP_DRAWSTATE_FOCUS Browser currently has input focus

The callback method in the XbpBrowse 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 XbpBrowse class itself (not a derived class), a code block must be assigned to the :customDrawCell callback slot.

The xbeP_CustomDrawCell event is sent synchronously through the :handleEvent() method of an XbpBrowse object. This implies that xbeP_CustomDrawCell 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_CustomDrawCell. 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 :customDrawCell() callback method and the :customDrawCell callback code block are executed on that thread. Therefore, during processing of an xbeP_CustomDrawCell 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 XbpBrowse object is created. This ensures fast processing of xbeP_CustomDrawCell 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.