1.6.12 Drawing Gray Text

An application can draw gray text by calling the SetTextColor function to set the current text color to 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. However, an application can intercept or modify each step of this process 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. First, GrayString sets text color to black. It then creates a bitmap and 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 the text is 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.

If an additional brush is combined with text, it is defined for the hbr parameter of GrayString. The brush is combined with the text as the text is copied to the client area by the BitBlt function. The additional brush is intended to be used to give the text a desired color, because the bitmap used to draw the text is a monochrome bitmap.

If an application-supplied function replaces TextOut, it is defined for the gsprc parameter of GrayString. When gsprc is not NULL, GrayString automatically calls the application-supplied function instead of the TextOut function and passes it a handle of the display context for the memory bitmap and 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 a nonzero value.

GrayString suppresses graying if it receives a cch parameter equal to –1 and the application-supplied function returns zero. This provides a way to combine custom patterns with the text without interference from the gray brush.