GrayString

This function draws gray text at the given location. The GrayString function draws gray text by writing the text in a memory bitmap, graying the bitmap, and then copying the bitmap to the display. The function grays the text regardless of the selected brush and background. GrayString uses the font currently selected for the device context specified by the hdc parameter.

If the lpOutputFunc parameter is NULL, GDI uses the TextOut function, and the lParam parameter is assumed to be a pointer to the character string 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.

Parameters

hdc

Identifies the device context.

hbr

Identifies the brush to be used for graying. If hbr is NULL, the text is grayed with the same brush used to draw window text.

lpOutputFunc

Is the procedure-instance address of the application-supplied function that will draw the string, or, if the TextOut function is to be used to draw the string, it is a NULL pointer. See the following Comments section for details.

lParam

Specifies a pointer to data to be passed to the output function. If the lpOutputFunc parameter is NULL, lParam must be a pointer to the string to be output.

nCount

Specifies the number of characters to be output. If the nCount parameter is zero, GrayString calculates the length of the string (assuming that lParam is a pointer to the string). If nCount is -1 and the function pointed to by lpOutputFunc returns FALSE, the image is shown but not grayed.

X

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

Y

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

nWidth

Specifies the width (in device units) of the rectangle that encloses the string. If the nWidth parameter is zero, GrayString calculates the width of the area, assuming lParam is a pointer to the string.

nHeight

Specifies the height (in device units) of the rectangle that encloses the string. If the nHeight parameter is zero, GrayString calculates the height of the area, assuming lParam is a pointer to the string.

Return Value

The return value specifies the outcome of the function. It is TRUE if the string is drawn. A return value of FALSE means that either the TextOut function or the application-supplied output function returned FALSE, or there was insufficient memory to create a memory bitmap for graying.

Comments

An application can draw grayed strings on devices that support a solid gray color, without calling the GrayString function. The system color COLOR_GRAYTEXT is the solid-gray system color used to draw disabled text. The application can call the GetSysColor function to retrieve the color value of COLOR_GRAYTEXT. If the color is other than zero (black), the application can call the SetTextColor to set the text color to the color value and then draw the string directly. If the retrieved color is black, the application must call GrayString to gray the text.

Callback Function

BOOL CALLBACK OutputFunc(hdc, lParam, nCount)
HDC hdc;
LPARAM lParam;
int nCount;

OutputFunc is a placeholder for the application-supplied callback function name.

Parameters

hdc

Identifies a memory device context with a bitmap of at least the width and height specified by the nWidth and nHeight parameters, respectively.

lParam

Points to the character string to be drawn.

nCount

Specifies the number of characters to be output.

Return Value

The return value must be TRUE to indicate success. Otherwise, it is FALSE.

Comments

This output function (OutputFunc) must draw an image relative to the coordinates (0,0) rather than (X,Y).

See Also

GetSysColor, SetTextColor, TextOut, DrawText, TabbedTextOut