Event XbpTabPage():draw

Informs the application that an owner-drawn tab page 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 tab page object. It can be used with the GRA functions to define the button'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 tab page's current selection state and bounding rectangle.

This method returns the object executing the method (self). The XbpTabPage class also supports a logical value to be returned from method :draw(), or from a code block assigned to 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 tab page object. See below for further information.

The xbeP_Draw event is generated whenever an owner-drawn tab page 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 is executed first, then the code block is evaluated. The owner-drawing feature is controlled via the :drawModeinstance variable of an XbpTabPage object.

Prior to drawing a tab page'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 XbpTabPage object. The columns 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 XbpTabPage objects, should be ignored
nAction	XBP_DRAWINFO_ACTION	Action or operation which caused xbeP_Draw event
nState	XBP_DRAWINFO_STATE	Current state of the XbpTabPage 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_DRAWFG	System is about to draw the caption or image within the header (tab) element. The application should return .F. if a custom caption is drawn, eg. using the Graphics Engine. Otherwise, the caption may be overwritten by TabPage object
XBP_DRAWACTION_DRAWBG *)	Area under header (tab) or body element is about to be drawn. Return the value .F. 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. In addition, a frame is drawn around the object.
Generated in XBP_DRAWOWNERADVANCED drawing mode only!

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_SELECTED	Object is currently maximized
XBP_DRAWSTATE_DISABLED	Object is currently disabled
XBP_DRAWSTATE_FOCUS	Object currently has input focus
XBP_DRAWSTATE_HEADER	This notification is for drawing the header (tab) element of the tab page object

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

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

Event XbpTabPage():draw Foundation