TextOut: The Details

When you obtain the handle to the device context, Windows fills the device context structure with default values. As you'll see in later chapters, you can change these defaults with GDI functions. The GDI function we're interested in right now is TextOut:

TextOut (hdc, x, y, lpsString, nLength) ;

Let's examine this function in more detail.

The first parameter is the handle to the device context—either the hdc value returned from GetDC or the hdc value returned from BeginPaint during processing of a WM_PAINT message.

The attributes of the device context control the characteristics of this displayed text. For instance, one attribute of the device context specifies the text color. The default color is black. The default device context also defines a background color of white. When a program writes text to the display, Windows uses this background color to fill in the space surrounding the characters.

This text background color is not the same background you set when defining the window class. The background in the window class is a brush—which is a pattern that may or may not be a pure color—that Windows uses to erase the client area. It is not part of the device context structure. When defining the window class structure, most Windows applications use WHITE_BRUSH so that the background color in the default device context is the same color as the brush Windows uses to erase the background of the client area.

The lpsString parameter is a long pointer to a character string, and nLength is the length of the string. The string should not contain any ASCII control characters such as carriage returns, linefeeds, tabs, or backspaces. Windows displays these control characters as solid blocks. TextOut does not recognize a 0 as denoting the end of the string and requires the nLength parameter for the length.

The x and y values in TextOut define the starting point of the character string within the client area. The x value is the horizontal position; the y value is the vertical position. The upper left corner of the first character in the string is positioned at x and y. In the default device context, the origin (the point where x and y both equal 0) is the upper left corner of the client area. If you use 0 values for x and y in TextOut, the character string starts flush against the upper left corner of the client area.

GDI coordinates are ”logical coordinates.“ Windows has a variety of ”mapping modes“ that govern how the logical coordinates specified in GDI functions are translated to the physical pixel coordinates of the display. The mapping mode is defined in the device context. The default mapping mode is called MM_TEXT (using the WINDOWS.H identifier). Under the MM_TEXT mapping mode, logical units are the same as physical units, which are pixels. Values of x increase as you move to the right in the client area and values of y increase as you move down in the client area. (See Figure 2-2 on the following page.) The MM_TEXT coordinate system is identical to the coordinate system that Windows uses to define the invalid rectangle in the PAINTSTRUCT structure. Very convenient. (This is not the case with other mapping modes, however.)

The device context also defines a clipping region. As you've seen, the default clipping region is the entire client area for a device context handle obtained from GetDC and the invalid rectangle for the device context handle obtained from BeginPaint. Windows will not display any part of the character string that lies outside the clipping rectangle. If a character is partly within the clipping rectangle, Windows displays only the portion of the character inside the rectangle. Writing outside the client area of your window isn't easy to do, so don't worry about doing it inadvertently.