Event XbpStatic():draw

Informs the application that an owner-drawn static object needs to be redrawn.

:draw := {| oPS, aInfo, self | ... }
:draw( oPS, aInfo ) --> self | lDefaultDraw
xbeP_Draw (1048655)

<oPS>

Parameter <oPS> contains a Micro Presentation Space object that must be used to draw the static object. It can be used with the GRA functions to define the static'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 static's bounding rectangle.

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

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

Prior to drawing a static's current state, an Xbase++ application is expected to examine the information passed in parameter <aInfo>. The elements in the array specify the object's current state and dimensions, as well as the operation which caused the redraw of the XbpStatic object. The elements of the <aInfo> array can be identified using symbolic constants defined in the file "xbp.ch".

Element	Constant	Description
nItem	XBP_DRAWINFO_ITEM	Not used with XbpStatic objects, should be ignored
nAction	XBP_DRAWINFO_ACTION	Action or operation which caused xbeP_Draw event
nState	XBP_DRAWINFO_STATE	Current state of the XbpStatic object
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_DRAWALL	The whole output area needs redrawing. The application should return the value .F. (false) after it has drawn the static. This action is used only with draw mode XBP_DRAW_OWNER.
XBP_DRAWACTION_DRAWFG	System is about to draw the caption or image of the static. The application should return .F. if a custom caption is drawn. Otherwise, the default caption or image is displayed. This action is used with draw mode XBP_DRAW_OWNERADVANCED.
XBP_DRAWACTION_DRAWBG	Background area of the static object is about to be erased. Return .F. (false) to prevent the system from clearing the background area. If a visual style is used, the style image corresponding to the current object state is drawn. Otherwise, the background color is used to erase the background. This action is used with draw mode XBP_DRAW_OWNERADVANCED.
	Some static types only consist of a caption element and do not require clearing of the background area. XBP_DRAWACTION_DRAWBG is not used with the static types XBPSTATIC_TYPE_xxxRECT, XBPSTATIC_TYPE_RAISEDBOX and XBPSTATIC_TYPE_RECESSEDBOX.

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

Constant	Description
XBP_DRAWSTATE_NORMAL	Object is in default state
XBP_DRAWSTATE_DISABLED	Object is currently disabled

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

The xbeP_Draw event is sent synchronously by the :handleEvent() method of an XbpStatic object. This implies that xbeP_Draw 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_Draw. 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 :draw() callback method and the :draw callback code block are executed on that thread. Therefore, during processing of an xbeP_Draw message, the application must assume that all thread-local settings will 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 static object is created. This ensures fast processing of xbeP_Draw events and prevents thread-dependencies.

Event XbpStatic():draw Foundation