Functions and Directives Functions and Directives

Function GraBackground() Foundation

Draw the background of an Xbase Part.

Syntax
GraBackground( <oPS>, [<aStart>], [<aEnd>], [<lErase>], [<nPart>] ) --> <lSuccess>
Parameters
<oPS>
The argument <oPS> specifies the presentation space to draw the background into. For this argument, a "Micro PS" must be requested from an Xbase Part using the method XbpWindow:lockPS(). After the call to GraBackground() completes, the Micro PS must be released with :unlockPS().
<aStart> := {<nX1>, <nY1>}
<aStart> is an array of two elements which determines the coordinates for the lower left corner of the output rectangle. The first element <nX1> designates the x coordinate and the second element <nY1> the y coordinate. If no start point is given, the coordinate {0,0} is assumed.
<aEnd> := {<nX2>, <nY2>}
<aEnd> is an array of two elements which contains the coordinates for the upper right corner of the output rectangle. If no coordinate is passed for <aEnd>, the end point of the output rectangle defaults to the width and height of the window associated with the Micro PS object.
<lErase>
A logical value can be assigned to <lErase>. If the value .T. (true) is passed for this parameter, GraBackground() may ask the parent object of the window associated with the Micro PS to erase parts of the output area. Erasing becomes necessary if the background image defined in a visual style contains transparent areas. The default value for parameter <lErase> is .T. (true).
<nPart>
A numeric value specifying the ID of the style part used for drawing the background. By default, the style part specified in the :stylePartinstance variable of the associated Xbase Part is used. If an invalid style part (-1) is assigned to parameter <nPart>, then GraBackground() ignores the visual style assigned to the associated Xbase Part.
Return

This function returns the value .T., if the background is erased successfully. Otherwise, .F. is returned.

Description

The function GraBackground() draws the background of an Xbase Part. If a visual style is assigned to the Xbase Part, GraBackground() uses the background image defined in the visual style to draw the background. The style image used is selected with respect to the current state of the Xbase Part, see XbpWindow:controlState for further information. For more information on style image selection, see the instance variables XbpWindow:styleClass and XbpWindow:stylePart. If an invalid style part is specified in parameter <nPart>, the function GraBackground() behaves as if no visual style is assigned to the Xbase Part.

If no visual style is assigned to the Xbase Part, or visual styles are disabled for the application, GraBackground() draws the background using the background color of the Xbase Part. If the background color assigned is transparent (XBPSYSCLR_TRANSPARENT), GraBackground() uses information from the parent of the associated Xbase Part to draw the output rectangle.

Visual styles have been introduced with Windows XP and are not available on older platforms.

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.