Event XbpPushButton():draw

Informs the application that an owner-drawn pushbutton 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 pushbutton 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 pushbutton's current selection state and bounding rectangle.

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

The xbeP_Draw event is generated whenever an owner-drawn pushbutton 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 XbpPushbutton object.

Prior to drawing a pushbutton's current state, an Xbase++ application is expected to examine the information passed in the 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 XbpPushbutton 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	This element is not used with XbpPushbutton objects and can be ignored
nAction	XBP_DRAWINFO_ACTION	Action or operation which caused xbeP_Draw event
nState	XBP_DRAWINFO_STATE	Current state of the XbpPushbutton 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 object must be redrawn
XBP_DRAWACTION_SELCHANGE	The selected state of the object has changed
XBP_DRAWACTION_FOCUSCHANGE	The object has gained or lost input focus
XBP_DRAWACTION_DRAWBG *)	The system is about to draw the background of the push button. By default, the style image corresponding to the current button state is drawn whenever a visual style is assigned. Otherwise, a frame is drawn that represents the current button state. The value .F. (false) must be returned by the application to prevent the system from performing these actions.
XBP_DRAWACTION_DRAWFG *)	The system is about to draw the button foreground. The default processing for this action draws a focus rectangle inside the push button if the button currently has the input focus. If the application draws a custom caption in response to this action, care must be taken to prevent the focus rectangle from overwriting the caption. To do this, the caption should be placed in the center of the button area. If a focus indicator is drawn by the application as part of the the custom caption, the application should return .F. to prevent the system from performing default processing for this action.
Generated in XBP_DRAW_OWNERADVANCED drawing mode only!

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

Constant	Description
XBP_DRAWSTATE_SELECTED	Object is currently selected (pressed)
XBP_DRAWSTATE_DISABLED	Object is currently disabled
XBP_DRAWSTATE_FOCUS	Object currently has input focus
XBP_DRAWSTATE_DEFAULTITEM	Object is the default button of the form

The callback method in the XbpPushbutton 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 XbpPushbutton 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 XbpPushbutton 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 pushbutton object is created. This ensures fast processing of xbeP_Draw events and prevents thread-dependencies.

Event XbpPushButton():draw Foundation