BOOL GrayString(hDC,hBrush,lpOutputFunc,lpData,nCount,X,Y,nWidth,nHeight)
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 lpData parameter is assumed to be a long 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.
| Parameter | Type/Description |
| hDC | HDC Identifies the device context. | |
| hBrush | HBRUSH Identifies the brush to be used for graying. | |
| lpOutputFunc | FARPROC 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. | |
| lpData | DWORD Specifies a long pointer to data to be passed to the output function. If the lpOutputFunc parameter is NULL, lpData must be a long pointer to the string to be output. | |
| nCount | int Specifies the number of characters to be output. If the nCount parameter is zero, 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 lpOutputFunc returns zero, the image is shown but not grayed. | |
| X | int Specifies the logical x-coordinate of the starting position of the rectangle that encloses the string. | |
| Y | int Specifies the logical y-coordinate of the starting position of the rectangle that encloses the string. | |
| nWidth | int Specifies the width (in logical units) of the rectangle that encloses the string. If the nWidth parameter is zero, GrayString calculates the width of the area, assuming lpData is a pointer to the string. | |
| nHeight | int Specifies the height (in logical units) of the rectangle that encloses the string. If the nHeight parameter is zero, GrayString calculates the height of the area, assuming lpData is a pointer to the string. |
The return value specifies the outcome of the function. It is nonzero if the string is drawn. A return value of zero means that either the TextOut function or the application-supplied output function returned zero, or there was insufficient memory to create a memory bitmap for graying.
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.
The callback function must use the Pascal calling convention and must be declared FAR.
BOOL FAR PASCAL OutputFunc(hDC, lpData, nCount)
HDC hDC;
DWORD lpData;
int nCount;
OutputFunc is a placeholder for the application-supplied callback function name. The actual name must be exported by including it in an EXPORTS statement in the application's module-definition file.
| Parameter | Description |
| hDC | Identifies a memory device context with a bitmap of at least the width and height specified by the nWidth and nHeight parameters, respectively. | |
| lpData | Points to the character string to be drawn. | |
| nCount | Specifies the number of characters to be output. |
Return Value
The return value must be nonzero to indicate success. Otherwise, it is zero.
Comments
This output function (OutputFunc) must draw an image relative to the coordinates (0,0) rather than (X,Y). The address passed as the lpOutputFunc parameter must be created by using the MakeProcInstance function, and the output function name must be exported; it must be explicitly defined in an EXPORTS statement of the application's module-definition file.
The MM_TEXT mapping mode must be selected before using this function.