Event XbpMultiCellGroup():customDrawCell

Classes Class XbpMultiCellGroup() :customDrawCell

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

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

<oPS>

Parameter <oPS> contains a Micro Presentation Space object that must be used to draw the cell. It can be used with the GRA functions to define the cell's imagery.

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

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

This method returns the object executing the method. The XbpMultiCellGroup 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 XbpMultiCellGroup object. See below for further information.

The xbeP_CustomDrawCell event is generated whenever cells of an owner-drawn XbpMultiCellGroup object 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 XbpMultiCellGroup object.

Prior to drawing a cell of the XbpMultiCellGroup object, 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".

Element	Constant	Description
aRowCol	XBP_DRAWINFO_ITEM	Array with number of row and column 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

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

Constant	Description
XBP_DRAWACTION_SELCHANGE	The highlight state of a cell is changed.
XBP_DRAWACTION_DRAWBG *)	The system is about to draw the background of a 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 frame type according to the display style selected in the instance variable :style. The default processing of this action uses the following scheme to draw the cell frames:
	If a column frame is defined by the style selected in member :style, the frame is drawn around each column in the cell group object. The row number in member aRowCol of the aInfo array has no meaning in this case and is always 0 (aRowCol = {0,<nCol>}).
	If a cell frame is defined by the style selected in member :style, the frame is drawn around each row in the cell group object. The column number in member aRowCol of the aInfo array has no meaning in this case and is always 0 (aRowCol = {<nRow>,0}.
	For highlighted cells, the highlight frame defined by the style is drawn around each cell in the cell group object. Member aRowCol of the aInfo array specifies the row and column number of the cell to be framed (aRowCol = {<nRow>,<nCol>}).
	Action XBP_DRAWACTION_DRAWFRAME is not requested for frame elements which are not used by the style selected. For example, selecting the style XBP_STYLE_SYSTEMDEFAULT in member :style causes cells to not use a cell frame. Consequently, the action XBP_DRAWACTION_DRAWFRAME is not requested when cells must be redrawn. The value .F. must be returned to prevent the system from performing default processing for this action.
XBP_DRAWACTION_DRAWFG	The 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.
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:

Constant	Description
XBP_DRAWSTATE_NORMAL	Cell is in default state
XBP_DRAWSTATE_SELECTED	Cell is currently selected
XBP_DRAWSTATE_DISABLED	XbpMultiCellGroup object is currently disabled
XBP_DRAWSTATE_FOCUS	XbpMultiCellGroup object currently has input focus

The callback method in the XbpMultiCellGroup 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 XbpMultiCellGroup class itself (not a derived class), a code block must be assigned to the :customDrawCellcallback slot. Note that XbpQuickBrowse objects install a code block in the :customDrawCell callback slot of their heading a data areas. This code block is used to forward cell redraw requests to the XbpQuickBrowse object. Applications generally process the xbeP_CustomDrawCell on the browser instead of the XbpMultiCellGroup object-level. See methods XbpQuickBrowse:create() and XbpQuickBrowse:customDrawCell() for further information.

The xbeP_CustomDrawCell event is sent synchronously by the :handleEvent() method of an XbpMultiCellGroup 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 XbpMultiCellGroup object is created. This ensures fast processing of xbeP_CustomDrawCell events and prevents thread-dependencies.

Event XbpMultiCellGroup():customDrawCell Foundation