Graphics Functions

Graphics Functions (GDI+)

The Graphics functions provide methods for drawing lines, curves, figures, images, and text. A Graphics object stores attributes of the display device and attributes of the items to be drawn.

Return Values

If the function succeeds, it returns Ok, which is an element of the Status enumeration.

If the function fails, it returns one of the other elements of the Status enumeration.

GdipIsClipEmpty

Description

Determines whether the clipping region of this Graphics object is empty.

Syntax

GpStatus WINGDIPAPI GdipIsClipEmpty(

GpGraphics *graphics,

BOOL *result

);

PowerBASIC Syntax

DECLARE FUNCTION GdipIsClipEmpty ( _

BYVAL graphics AS DWORD, _

BYREF result AS LONG _

) AS LONG

Parameters

graphics

[in] Pointer to the Graphics object.

result

[out] Pointer to a variable that receives a boolean value that determines whether the clipping region of this Graphics object is empty (TRUE) or not (FALSE).

Remarks

If the clipping region of a Graphics object is empty, there is no area left in which to draw. Consequently, nothing will be drawn when the clipping region is empty.

GdipIsVisibleClipEmpty

Description

Determines whether the visible clipping region of this Graphics object is empty. The visible clipping region is the intersection of the clipping region of this Graphics object and the clipping region of the window.

Syntax

GpStatus WINGDIPAPI GdipIsVisibleClipEmpty(

GpGraphics *graphics,

BOOL *result

);

PowerBASIC Syntax

DECLARE FUNCTION GdipIsVisibleClipEmpty ( _

BYVAL graphics AS DWORD, _

BYREF result AS LONG _

) AS LONG

Parameters

graphics

[in] Pointer to the Graphics object.

result

[out] Pointer to a variable that receives a boolean value that determines whether the visible clipping region of this Graphics object is empty (TRUE) or not (FALSE).

Remarks

If the clipping region of a Graphics object is empty, there is no area left in which to draw. Consequently, nothing will be drawn when the clipping region is empty.

GdipIsVisiblePoint

Description

Determines whether the specified point is inside the visible clipping region of this Graphics object. The visible clipping region is the intersection of the clipping region of this Graphics object and the clipping region of the window.

Syntax

GpStatus WINGDIPAPI GdipIsVisiblePoint(

    GpGraphics *graphics,

    REAL x,

    REAL y,

    BOOL *result

);

PowerBASIC Syntax

DECLARE FUNCTION GdipIsVisiblePoint ( _

    BYVAL graphics AS DWORD, _

    BYVAL x AS SINGLE, _

    BYVAL y AS SINGLE, _

    BYREF result AS LONG _

) AS LONG

arameters

graphics

[in] Pointer to the Graphics object.

[in] Simple precision value that specifies the x-coordinate of the point to test.

[in] Simple precision value that specifies the y-coordinate of the point to test.

result

[out] Pointer to a variable that receives a boolean value that determines whether the specified point is inside the visible clipping region of this Graphics object (TRUE) or not (FALSE).

GdipIsVisiblePointI

Description

Determines whether the specified point is inside the visible clipping region of this Graphics object. The visible clipping region is the intersection of the clipping region of this Graphics object and the clipping region of the window.

Syntax

GpStatus WINGDIPAPI GdipIsVisiblePointI(

    GpGraphics *graphics,

    INT x,

    INT y,

    BOOL *result

);

PowerBASIC Syntax

DECLARE FUNCTION GdipIsVisiblePointI ( _

    BYVAL graphics AS DWORD, _

    BYVAL x AS LONG, _

    BYVAL y AS LONG, _

    BYREF result AS LONG _

) AS LONG

Parameters

graphics

[in] Pointer to the Graphics object.

[in] Long integer value that specifies the x-coordinate of the point to test.

[in] Long integer value that specifies the y-coordinate of the point to test.

result

[out] Pointer to a variable that receives a boolean value that determines whether the specified point is inside the visible clipping region of this Graphics object (TRUE) or not (FALSE).

GdipIsVisibleRect

Description

Determines whether the specified point is inside the visible clipping region of this Graphics object. The visible clipping region is the intersection of the clipping region of this Graphics object and the clipping region of the window.

Syntax

GpStatus WINGDIPAPI GdipIsVisibleRect(

    GpGraphics *graphics,

    REAL x,

    REAL y,

    REAL width,

    REAL height,

    BOOL *result

);

PowerBASIC Syntax

DECLARE FUNCTION GdipIsVisibleRect ( _

    BYVAL graphics AS DWORD, _

    BYVAL x AS SINGLE, _

    BYVAL y AS SINGLE, _

    BYVAL nWidth AS SINGLE, _

    BYVAL nHeight AS SINGLE, _

    BYREF result AS LONG _

) AS LONG

Parameters

graphics

[in] Pointer to the Graphics object.

[in] Simple precision value that specifies the x-coordinate of the rectangle to test.

[in] Simple precision value that specifies the y-coordinate of the rectangle to test.

width

[in] Simple precision value that specifies the width of the rectangle to test.

height

[in] Simple precision value that specifies the height of the rectangle to test.

result

[out] Pointer to a variable that receives a boolean value that determines whether the specified rectangle intersects the visible clipping region of this Graphics object (TRUE) or not (FALSE).

GdipIsVisibleRectI

Description

Determines whether the specified point is inside the visible clipping region of this Graphics object. The visible clipping region is the intersection of the clipping region of this Graphics object and the clipping region of the window.

Syntax

GpStatus WINGDIPAPI GdipIsVisibleRectI(

    GpGraphics *graphics,

    INT x,

    INT y,

    INT width,

    INT height,

    BOOL *result

);

PowerBASIC Syntax

DECLARE FUNCTION GdipIsVisibleRectI ( _

    BYVAL graphics AS DWORD, _

    BYVAL x AS LONG, _

    BYVAL y AS LONG, _

    BYVAL nWidth AS LONG, _

    BYVAL nHeight AS LONG, _

    BYREF result AS LONG _

) AS LONG

Parameters

graphics

[in] Pointer to the Graphics object.

[in] Long integer value that specifies the x-coordinate of the rectangle to test.

[in] Long integer valuethat specifies the y-coordinate of the rectangle to test.

width

[in] Long integer valuethat specifies the width of the rectangle to test.

height

[in] Long integer valuethat specifies the height of the rectangle to test.

result

[out] Pointer to a variable that receives a boolean value that determines whether the specified rectangle intersects the visible clipping region of this Graphics object (TRUE) or not (FALSE).

GdipMultiplyWorldTransform

Description

Updates this Graphics object's world transformation matrix with the product of itself and another matrix.

Syntax

GpStatus WINGDIPAPI GdipMultiplyWorldTransform(

    GpGraphics *graphics,

    GDIPCONST GpMatrix *matrix,

    GpMatrixOrder order

);

PowerBASIC Syntax

DECLARE FUNCTION GdipMultiplyWorldTransform ( _

    BYVAL graphics AS DWORD, _

    BYVAL matrix AS DWORD, _

    BYVAL order AS LONG _

) AS LONG

Parameters

graphics

[in] Pointer to the Graphics object.

matrix

[in] Pointer to a matrix that will be multiplied by the world transformation matrix of this Graphics object.

order

[in] Element of the MatrixOrder enumeration that specifies the order of multiplication. MatrixOrderPrepend specifies that the passed matrix is on the left, and MatrixOrderAppend specifies that the passed matrix is on the right. The default value is MatrixOrderPrepend.

GdipPlayMetafileRecord

Description

Plays a metafile record.

Syntax

GpStatus WINGDIPAPI GdipPlayMetafileRecord(

    GDIPCONST GpMetafile * metafile,

    EmfPlusRecordType recordType,

    UINT flags,

    UINT dataSize,

    GDIPCONST BYTE * data

);

PowerBASIC Syntax

DECLARE FUNCTION GdipPlayMetafileRecord ( _

    BYVAL metafile AS DWORD, _

    BYVAL recordType AS LONG, _

    BYVAL flags AS DWORD, _

    BYVAL dataSize AS DWORD, _

    BYREF pData AS ANY _

) AS LONG

Parameters

metafile

[in] Pointer to the Metafile object.

recordtype

[in] Element of the EmfPlusRecordType enumeration that specifies the type of metafile record to be played.

flags

[in] Set of flags that specify attributes of the record to be played.

datasize

[in] Long integer value that specifies the number of bytes contained in the record data.

data

[in] Pointer to an array of bytes that contains the record data.

GdipRecordMetafile

Description

Creates a Metafile object for recording.

Syntax

GpStatus WINGDIPAPI GdipRecordMetafile(

    HDC referenceHdc,

    EmfType type,

    GDIPCONST GpRectF * frameRect,

    MetafileFrameUnit frameUnit,

    GDIPCONST WCHAR * description,

    GpMetafile ** metafile

);

PowerBASIC Syntax

DECLARE FUNCTION GdipRecordMetafile ( _

    BYVAL referenceHdc AS DWORD, _

    BYVAL pType AS LONG, _

    BYREF frameRect AS RECTF, _

    BYVAL frameUnit AS LONG, _

    BYVAL description AS STRING, _

    BYREF metafile AS DWORD _

) AS LONG

Parameters

referenceHdc

[in] Windows handle to a device context that contains attributes of the display device that is used to record the metafile.

type

[in] Element of the EmfType enumeration that specifies the type of metafile that will be recorded. The default value is EmfTypeEmfPlusDual.

frameRect

[in] Reference to a rectangle that bounds the metafile display.

frameUnit

[in] Element of the MetafileFrameUnit enumeration that specifies the unit of measure for frameRect. The default value is MetafileFrameUnitGdi.

description

[in] Pointer to a wide-character string that specifies the descriptive name of the metafile. The default value is NULL.

metafile

[out] Pointer to a variable that receives a pointer to the new created Metafile object.

Remarks

When recording to a file, the file must be writable, and GDI+ must be able to obtain an exclusive lock on the file.

GdipRecordMetafileName

Description

Creates a Metafile object for recording.

Syntax

GpStatus WINGDIPAPI GdipRecordMetafileFileName(

    GDIPCONST WCHAR* fileName,

    HDC referenceHdc,

    EmfType type,

    GDIPCONST GpRectF * frameRect,

    MetafileFrameUnit frameUnit,

    GDIPCONST WCHAR * description,

   GpMetafile ** metafile

);

PowerBASIC Syntax

DECLARE FUNCTION GdipRecordMetafileFileName ( _

    BYVAL pFilename AS STRING _

    BYVAL referenceHdc AS DWORD _

    BYVAL pType AS LONG _

    BYREF frameRect AS RECTF _

    BYVAL frameUnit AS LONG _

    BYVAL description AS STRING _

    BYREF metafile AS DWORD _

) AS LONG

Parameters

filename

[in] Pointer to a wide-character string that specifies the name of the file in which the metafile will be saved.

referenceHdc

[in] Windows handle to a device context that contains attributes of a display device.

type

[in] Element of the EmfType enumeration that specifies the type of metafile that will be recorded. The default value is EmfTypeEmfPlusDual.

frameRect

[in] Reference to a rectangle that bounds the metafile display.

frameUnit

[in] Element of the MetafileFrameUnit enumeration that specifies the unit of measure for frameRect. The default value is MetafileFrameUnitGdi.

description

[in] Pointer to a wide-character string that specifies the descriptive name of the metafile. The default value is NULL.

metafile

[out] Pointer to a variable that receives a pointer to the new created Metafile object.

Remarks

When recording to a file, the file must be writable, and GDI+ must be able to obtain an exclusive lock on the file.

GdipRecordMetafileNameI

Description

Creates a Metafile object for recording.

Syntax

GpStatus WINGDIPAPI GdipRecordMetafileFileNameI(

    GDIPCONST WCHAR* fileName,

    HDC referenceHdc,

    EmfType type,

    GDIPCONST GpRect * frameRect,

    MetafileFrameUnit frameUnit,

    GDIPCONST WCHAR * description,

    GpMetafile ** metafile

);

PowerBASIC Syntax

DECLARE FUNCTION GdipRecordMetafileFileNameI ( _

    BYVAL pFilename AS STRING _

    BYVAL referenceHdc AS DWORD _

    BYVAL pType AS LONG _

    BYREF frameRect AS RECTL _

    BYVAL frameUnit AS LONG _

    BYVAL description AS STRING _

    BYREF metafile AS DWORD _

) AS LONG

Parameters

filename

[in] Pointer to a wide-character string that specifies the name of the file in which the metafile will be saved.

referenceHdc

[in] Windows handle to a device context that contains attributes of a display device.

type

[in] Element of the EmfType enumeration that specifies the type of metafile that will be recorded. The default value is EmfTypeEmfPlusDual.

frameRect

[in] Reference to a rectangle that bounds the metafile display.

frameUnit

[in] Element of the MetafileFrameUnit enumeration that specifies the unit of measure for frameRect. The default value is MetafileFrameUnitGdi.

description

[in] Pointer to a wide-character string that specifies the descriptive name of the metafile. The default value is NULL.

metafile

[out] Pointer to a variable that receives a pointer to the new created Metafile object.

Remarks

When recording to a file, the file must be writable, and GDI+ must be able to obtain an exclusive lock on the file.

GdpiRecordMetafileI

Description

Creates a Metafile object for recording.

Syntax

GpStatus WINGDIPAPI GdipRecordMetafileI(

    HDC referenceHdc,

    EmfType type,

    GDIPCONST GpRect * frameRect,

    MetafileFrameUnit frameUnit,

    GDIPCONST WCHAR * description,

    GpMetafile ** metafile

);

PowerBASIC Syntax

DECLARE FUNCTION GdipRecordMetafileI ( _

    BYVAL referenceHdc AS DWORD, _

    BYVAL pType AS LONG, _

    BYREF frameRect AS RECTL, _

    BYVAL frameUnit AS LONG, _

    BYVAL description AS STRING, _

    BYREF metafile AS DWORD _

) AS LONG

Parameters

referenceHdc

[in] Windows handle to a device context that contains attributes of the display device that is used to record the metafile.

type

[in] Element of the EmfType enumeration that specifies the type of metafile that will be recorded. The default value is EmfTypeEmfPlusDual.

frameRect

[in] Reference to a rectangle that bounds the metafile display.

frameUnit

[in] Element of the MetafileFrameUnit enumeration that specifies the unit of measure for frameRect. The default value is MetafileFrameUnitGdi.

description

[in] Pointer to a wide-character string that specifies the descriptive name of the metafile. The default value is NULL.

metafile

[out] Pointer to a variable that receives a pointer to the new created Metafile object.

Remarks

When recording to a file, the file must be writable, and GDI+ must be able to obtain an exclusive lock on the file.

GdipRecordMetafileStream

Description

Creates a Metafile object for recording to an IStream interface.

Syntax

GpStatus WINGDIPAPI GdipRecordMetafileStream(

    IStream * stream,

    HDC referenceHdc,

    EmfType type,

    GDIPCONST GpRectF * frameRect,

    MetafileFrameUnit frameUnit,

    GDIPCONST WCHAR * description,

    GpMetafile ** metafile

);

PowerBASIC Syntax

DECLARE FUNCTION GdipRecordMetafileStream ( _

    BYVAL pStream AS DWORD, _

    BYVAL referenceHdc AS DWORD, _

    BYVAL pType AS LONG, _

    BYREF frameRect AS RECTF, _

    BYVAL frameUnit AS LONG, _

    BYVAL description AS STRING, _

    BYREF metafile AS DWORD _

) AS LONG

Parameters

stream

[in] Pointer to a COM IStream interface that points to a stream of data in a file. When the commands are recorded, they will be saved to this stream.

referenceHdc

[in] Windows handle to a device context that contains attributes of the display device that is used to record the metafile.

type

[in] Element of the EmfType enumeration that specifies the type of metafile that will be recorded. The default value is EmfTypeEmfPlusDual.

frameRect

[in] Reference to a rectangle that bounds the metafile display.

frameUnit

[in] Element of the MetafileFrameUnit enumeration that specifies the unit of measure for frameRect. The default value is MetafileFrameUnitGdi.

description

[in] Pointer to a wide-character string that specifies the descriptive name of the metafile. The default value is NULL.

metafile

[out] Pointer to a variable that receives a pointer to the new created Metafile object.

Remarks

When recording to a file, the file must be writable, and GDI+ must be able to obtain an exclusive lock on the file.

GdipRecordMetafileStreamI

Description

Creates a Metafile object for recording to an IStream interface.

Syntax

GpStatus WINGDIPAPI GdipRecordMetafileStreamI(

    IStream * stream,

    HDC referenceHdc,

    EmfType type,

    GDIPCONST GpRect * frameRect,

    MetafileFrameUnit frameUnit,

    GDIPCONST WCHAR * description,

    GpMetafile ** metafile

);

PowerBASIC Syntax

DECLARE FUNCTION GdipRecordMetafileStreamI ( _

    BYVAL pStream AS DWORD, _

    BYVAL referenceHdc AS DWORD, _

    BYVAL pType AS LONG, _

    BYREF frameRect AS RECTL, _

    BYVAL frameUnit AS LONG, _

    BYVAL description AS STRING, _

    BYREF metafile AS DWORD _

) AS LONG

Parameters

stream

[in] Pointer to a COM IStream interface that points to a stream of data in a file. When the commands are recorded, they will be saved to this stream.

referenceHdc

[in] Windows handle to a device context that contains attributes of the display device that is used to record the metafile.

type

[in] Element of the EmfType enumeration that specifies the type of metafile that will be recorded. The default value is EmfTypeEmfPlusDual.

frameRect

[in] Reference to a rectangle that bounds the metafile display.

frameUnit

[in] Element of the MetafileFrameUnit enumeration that specifies the unit of measure for frameRect. The default value is MetafileFrameUnitGdi.

description

[in] Pointer to a wide-character string that specifies the descriptive name of the metafile. The default value is NULL.

metafile

[out] Pointer to a variable that receives a pointer to the new created Metafile object.

Remarks

When recording to a file, the file must be writable, and GDI+ must be able to obtain an exclusive lock on the file.

GdipReleaseDC

Description

Releases a device context handle obtained by a previous call to the GdipGetDC function.

Syntax

GpStatus WINGDIPAPI GdipReleaseDC(

GpGraphics* graphics,

HDC hdc

);

PowerBASIC Syntax

DECLARE FUNCTION GdipReleaseDC ( _

BYVAL graphics AS DWORD, _

BYVAL hDC AS DWORD _

) AS LONG

Parameters

graphics

[in] Pointer to the Graphics object.

hdc

[in] Handle to a device context obtained by a previous call to the GdipGetDC function.

GdipResetClip

Description

Sets the clipping region of this Graphics object to an infinite region.

Syntax

GpStatus WINGDIPAPI GdipResetClip(

GpGraphics *graphics

);

PowerBASIC Syntax

DECLARE FUNCTION GdipResetClip ( _

BYVAL graphics AS DWORD _

) AS LONG

Parameters

graphics

[in] Pointer to the Graphics object.

Remarks

If the clipping region of a Graphics object is infinite, then items drawn by that Graphics object will not be clipped.

GdipResetPageTransform

Description

Resets the page transform matrix to identity.

Syntax

GpStatus WINGDIPAPI GdipResetPageTransform(

GpGraphics *graphics

);

PowerBASIC Syntax

DECLARE FUNCTION GdipResetPageTransform ( _

BYVAL graphics AS DWORD _

) AS LONG

Parameters

graphics

[in] Pointer to the Graphics object.

GdipResetWorldTransform

Description

Sets the world transformation matrix of this Graphics object to the identity matrix.

Syntax

GpStatus WINGDIPAPI GdipResetWorldTransform(

GpGraphics *graphics

);

PowerBASIC Syntax

DECLARE FUNCTION GdipResetWorldTransform ( _

BYVAL graphics AS DWORD _

) AS LONG

Parameters

graphics

[in] Pointer to the Graphics object.

Remarks

The identity matrix represents a transformation that does nothing. If the world transformation matrix of a Graphics object is the identity matrix, then no world transformation is applied to items drawn by that Graphics object.

GdipRestoreGraphics

Description

Sets the state of this Graphics object to the state stored by a previous call to the Save method of this Graphics object.

Syntax

GpStatus WINGDIPAPI GdipRestoreGraphics(

GpGraphics *graphics,

GraphicsState state

);

PowerBASIC Syntax

DECLARE FUNCTION GdipRestoreGraphics ( _

BYVAL graphics AS DWORD, _

BYVAL pState AS DWORD _

) AS LONG

Parameters

graphics

[in] Pointer to the Graphics object.

state

[in] 32-bit value (returned by a previous call to the GdipSaveGraphics function) that identifies a block of saved state.

Remarks

When you call the GdipSaveGraphics function, an information block that holds the state of the Graphics object is put on a stack. The GdipSaveGraphics function returns a value that identifies that information block. When you pass the identifying value to the GdipRestoreGraphics method, the information block is removed from the stack and is used to restore the Graphics object to the state it was in at the time of the GdipSaveGraphics call. Note that the identifier returned by a given call to the GdipSaveGraphics function can be passed only once to the GdipRestoreGraphics function.

Calls to the GdipSaveGraphics function can be nested; that is, you can call the GdipSaveGraphics function several times before you call the GdipRestoreGraphics function. Each time you call the GdipSaveGraphics function, an information block is put on the stack, and you receive an identifier for the information block. When you pass one of those identifiers to the GdipRestoreGraphics function, the Graphics object is returned to the state it was in at the time of the GdipSaveGraphics call that returned that particular identifier. The information block placed on the stack by that GdipSaveGraphics call is removed from the stack, and all information blocks placed on that stack after that GdipSaveGraphics call are also removed.

Calls to the GdipBeginContainer function place information blocks on the same stack as calls to the GdipSaveGraphics function. Just as a GdipRestoreGraphics call is paired with a GdipSaveGraphics call, an GdipEndContainer call is paired with a GdipBeginContainer call.

Caution When you call GdipRestoreGraphics, all information blocks placed on the stack (by GdipRestoreGraphics or by GdipBeginContainer) after the corresponding call to GdipSaveGraphics are removed from the stack. Likewise, When you call GdipEndContainer, all information blocks placed on the stack (by GdipSaveGraphics or by GdipBeginContainer ) after the corresponding call to GdipBeginContainer are removed from the stack.

GdipRotateWorldTransform

Description

Updates the world transformation matrix of this Graphics object with the product of itself and a rotation matrix.

Syntax

GpStatus WINGDIPAPI GdipRotateWorldTransform(

    GpGraphics *graphics,

    REAL angle,

    GpMatrixOrder order

);

PowerBASIC Syntax

DECLARE FUNCTION GdipRotateWorldTransform ( _

    BYVAL graphics AS DWORD, _

    BYVAL angle AS SINGLE, _

    BYVAL order AS LONG _

) AS LONG

Parameters

graphics

[in] Pointer to the Graphics object.

angle

[in] Simple precision value that specifies the angle, in degrees, of rotation.

order

[in] Element of the MatrixOrder enumeration that specifies the order of multiplication. MatrixOrderPrepend specifies that the rotation matrix is on the left, and MatrixOrderAppend specifies that the rotation matrix is on the right. The default value is MatrixOrderPrepend.

Page last updated on Monday, 11 December 2006 11:11:42 +0100