Method XbpBitmap():draw()

Classes Class XbpBitmap() :draw()

Displays a bitmap.

:draw( [<oTargetPS>]  , ;
       <aTargetRect>  , ;
       [<aSourceRect>], ;
       [<nRasterOP>]  , ;
       [<nCompress>]  , ;
       [<nState>] )  --> lSuccess

The optional argument <oTargetPS> specifies a presentation space where the bitmap is output. If <oTargetPS> equals NIL, the bitmap is output in the current window. If the current window is an XbpCrt window, the default value for <oTargetPS> is the return value of SetAppWindow():presSpace(). In all other cases, <oTargetPS> is not optional. A presentation space is either created (XbpPresSpace():new()) or the MicroPS of an Xbase Part is requested using the method :lockPS().

<aTargetRect> := { <nX1>, <nY1> [,<nX2>, <nY2>] }

<aTargetRect> identifies the rectangular area in the presentation space <oTargetPS> where the bitmap is displayed. <nX1> and <nY1> specify the point for the lower left corner. <nX2> and <nY2> specify the upper right corner of the area. The coordinates <nX2> and <nY2> are optional. If they are not included, the output area is the same size as the area of <aSourceRect>.

<aSourceRect> := { <nX1>, <nY1>, <nX2>, <nY2> }

<aSourceRect> specifies a rectangular area of the bitmap that is displayed in the presentation space <oTargetPS>. <nX1> and <nY1> specify the lower left corner. <nX2> and <nY2>specify the upper right corner of the area. The coordinates must always be specified in pixels and are device dependent. The default value for <aSourceRect> is {0, 0, oBitmap:xSize, oBitmap:ySize} which is the entire bitmap.

Values for the optional parameter <nRasterOP> must be constants defined in GRA.CH that begin with GRA_BLT_ROP_*. These constants specify various raster operations that are performed when the raster image is copied for display. The default value is GRA_BLT_ROP_SRCCOPY and the raster image is copied unchanged to <oTargetPS>.

The parameter <nCompress> is significant only when the area in <aTargetRect> is smaller than <aSourceRect>. #define constants from GRA.CH beginning with GRA_BLT_BBO_* must be used for this value. These constants specify the mode for compression (reduction in size) of the raster image. When compression is performed, pixels are lost and <nCompress> specifies different modes to use in determining which pixels to discard. The default value is GRA_BLT_BBO_OR.

The optional parameter <nState> specifies the state in which the bitmap should be rendered in. Possible values for <nState> are listed below. Also see instance variable XbpWindow:ControlState.

Constant	Description
XBP_STATE_NORMAL *)	Normal state; bitmap is drawn as saved on disk
XBP_STATE_DISABLED	Bitmap is drawn shaded to signify disabled state
Default value

This method returns .T. (true) when the bitmap could be displayed, otherwise it returns .F. (false).

The :draw() method displays a raster image in the specified presentation space. The section of the image that is displayed can be set using the parameter <aSourceRect>. If <aTargetRect> is an array with only two elements, it specifies the position of the lower left corner of the bitmap. If it is an array containing four elements, the raster image is displayed in this area. If the size of the <aSourceRect> and <aTargetRect> areas are different, the bitmap is scaled.

The :draw() method accounts for a transparent color specified in the :transparentClr instance variable. If this contains a valid color, parts of the image that use this color are replaced with information from the underlying background. In addition, a blend operation with the background is performed, whenever member :transparency contains a value other than 0 (opaque).

If XBP_STATE_DISABLED is passed in parameter <nState>, the parameters <nRasterOp> and <nCompress> are ignored.

A transparent color specified in the :transparentClr instance variable is ignored if the presentation space passed in <oTargetPS>is connected to a printer or file device context. The same applies if a graphical segment is currently open in the PS.

Method XbpBitmap():draw() Foundation