CDC::GrayString

Syntax

BOOL GrayString( CBrush* pBrush, BOOL ( FAR PASCAL EXPORT* lpfnOutput )( HDC, DWORD, int ), DWORD lpData, int nCount, int x, int y, int nWidth, int nHeight );

Parameters

pBrush

Identifies the brush to be used for dimming (graying).

lpfnOutput

Specifies the procedure-instance address of the application-supplied callback function that will draw the string. For more information, see the description of the Windows OutputProc callback function below.

If this parameter is NULL, the system uses the Windows TextOut function to draw the string, and lpData is assumed to be a long pointer to the character string to be output.

lpData

Specifies a far pointer to data to be passed to the output function. If lpfnOutput is NULL, lpData must be a long pointer to the string to be output.

nCount

Specifies the number of characters to be output. If this parameter is 0, GrayString calculates the length of the string (assuming that lpData is a pointer to the string). If nCount is -1 and the function pointed to by lpfnOutput returns 0, the image is shown but not dimmed.

x

Specifies the logical x-coordinate of the starting position of the rectangle that encloses the string.

y

Specifies the logical y-coordinate of the starting position of the rectangle that encloses the string.

nWidth

Specifies the width (in logical units) of the rectangle that encloses the string. If nWidth is 0, GrayString calculates the width of the area, assuming lpData is a pointer to the string.

nHeight

Specifies the height (in logical units) of the rectangle that encloses the string. If nHeight is 0, GrayString calculates the height of the area, assuming lpData is a pointer to the string.

Remarks

Draws dimmed (gray) text at the given location by writing the text in a memory bitmap, dimming the bitmap, and then copying the bitmap to the display. The function dims the text regardless of the selected brush and background. The GrayString member function uses the currently selected font.

If lpFnOutput is NULL, GDI uses the Windows TextOut function, and lpData is assumed to be a far pointer to the character to be output. If the characters to be output cannot be handled by TextOut (for example, the string is stored as a bitmap), the application must supply its own output function.

Also note that all callback functions must trap Foundation exceptions before returning to Windows, since exceptions cannot be thrown across callback boundaries. For more information about exceptions, see Chapter 12 in the Class Libraries User's Guide.

The callback function passed to GrayString must use the Pascal calling convention, must be exported with __export, and must be declared FAR.