An application can draw gray text by calling the SetTextColor function to set the current text color to the COLOR_GRAYTEXT, the solid gray system color used to draw disabled text. However, if the current display driver does not support a solid gray color, this value is set to zero.
The GrayString function is a multiple-purpose function that gives applications another way to gray text or carry out other customized operations on text or bitmaps before drawing the result in a client area. To gray text, the function creates a memory bitmap, draws the string in the bitmap, and then grays the string by combining it with a gray brush. The GrayString function finally copies the gray text to the display. An application can intercept or modify each step of this process, however, to carry out custom effects, such as changing the gray brush to a patterned brush or drawing an icon instead of a string.
If GrayString is used to draw gray text only, GrayString uses the selected font of the given display context. GrayString sets text color to black. It creates a bitmap, and then uses the TextOut function to write a given string to the bitmap. It then uses the PatBlt function and a gray brush to gray the text, and uses the BitBlt function to copy the bitmap to the client area.
GrayString assumes that the display context for the client area has MM_TEXT mapping mode. Other mapping modes cause undesirable results.
GrayString lets an application modify this graying procedure in three ways: by defining an additional brush to be combined with the text before being displayed, by replacing the call to the TextOut function with a call to an application-supplied function, and by disabling the call to the PatBlt function.
The additional brush is defined as a parameter. This brush is combined with the text as the text is being copied to the client area by the BitBlt function. The additional brush is intended to be used to give the text a desired color, since the bitmap used to draw the text is a monochrome bitmap.
The application-supplied function is also defined as a parameter. If a non-NULL value is given for the function, GrayString automatically calls the application-supplied function instead of the TextOut function and passes it a handle to the display context for the memory bitmap as well as the long pointer and count passed to GrayString. The function can carry out any operation and interpret the long pointer and count in any way. For example, a negative count could be used to indicate that the long pointer points to an icon handle that signals the application-supplied function to draw the icon and let GrayString gray and display it. No matter what type of drawing the function carries out, GrayString assumes it is successful if the application-supplied function returns TRUE.
GrayString suppresses graying if it receives an ncount parameter equal to –1 and the application-supplied function returns FALSE. This is a way to combine custom patterns with the text without interference from the gray brush.