GrayStringW function (winuser.h)

Article
02/09/2023

The GrayString function draws gray text at the specified location. The function draws the text by copying it into a memory bitmap, graying the bitmap, and then copying the bitmap to the screen. The function grays the text regardless of the selected brush and background. GrayString uses the font currently selected for the specified device context.

If thelpOutputFuncparameter is NULL, GDI uses the TextOut function, and thelpDataparameter 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.

Syntax

BOOL GrayStringW(
  [in] HDC            hDC,
  [in] HBRUSH         hBrush,
  [in] GRAYSTRINGPROC lpOutputFunc,
  [in] LPARAM         lpData,
  [in] int            nCount,
  [in] int            X,
  [in] int            Y,
  [in] int            nWidth,
  [in] int            nHeight
);

Parameters

[in] hDC

A handle to the device context.

[in] hBrush

A handle to the brush to be used for graying. If this parameter is NULL, the text is grayed with the same brush that was used to draw window text.

[in] lpOutputFunc

A pointer to the application-defined function that will draw the string, or, if TextOut is to be used to draw the string, it is a NULL pointer. For details, see the OutputProc callback function.

[in] lpData

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

[in] nCount

The number of characters to be output. If the nCount parameter is zero, GrayString calculates the length of the string (assuming lpData 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.

[in] X

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

[in] Y

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

[in] nWidth

The width, in device units, of the rectangle that encloses the string. If this parameter is zero, GrayString calculates the width of the area, assuming lpData is a pointer to the string.

[in] nHeight

The height, in device units, of the rectangle that encloses the string. If this parameter is zero, GrayString calculates the height of the area, assuming lpData is a pointer to the string.

Return value

If the string is drawn, the return value is nonzero.

If either the TextOut function or the application-defined output function returned zero, or there was insufficient memory to create a memory bitmap for graying, the return value is zero.

Remarks

Without calling GrayString, an application can draw grayed strings on devices that support a solid gray color. 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 function 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.

Note

The winuser.h header defines GrayString as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.

Requirements

Requirement	Value
Minimum supported client	Windows 2000 Professional [desktop apps only]
Minimum supported server	Windows 2000 Server [desktop apps only]
Target Platform	Windows
Header	winuser.h (include Windows.h)
Library	User32.lib
DLL	User32.dll