An Introduction to GDI

To paint the client area of your window, you use Windows' Graphics Device Interface (GDI) functions. Windows provides several GDI functions for writing text strings to the client area of the window. We've already encountered the DrawText function in the last chapter, but the most commonly used text output function is undoubtedly TextOut. This function has the following format:

 TextOut (hdc, x, y, psText, iLength) ; 

TextOut writes a character string to the client area of the window. The psText argument is a pointer to the character string, and iLength is the length of the string in characters. The x and y arguments define the starting position of the character string in the client area. (More details soon on how these work.) The hdc argument is a "handle to a device context," and it is an important part of GDI. Virtually every GDI function requires this handle as the first argument to the function.

The Device Context

A handle, you'll recall, is simply a number that Windows uses for internal reference to an object. You obtain the handle from Windows and then use the handle in other functions. The device context handle is your window's passport to the GDI functions. With that device context handle you are free to paint your client area and make it as beautiful or as ugly as you like.

The device context (also called simply the "DC") is really just a data structure maintained internally by GDI. A device context is associated with a particular display device, such as a video display or a printer. For a video display, a device context is usually associated with a particular window on the display.

Some of the values in the device context are graphics "attributes." These attributes define some particulars of how GDI drawing functions work. With TextOut, for instance, the attributes of the device context determine the color of the text, the color of the text background, how the x-coordinate and y-coordinate in the TextOut function are mapped to the client area of the window, and what font Windows uses when displaying the text.

When a program needs to paint, it must first obtain a handle to a device context. When you obtain this handle, Windows fills the internal device context structure with default attribute values. As you'll see in later chapters, you can change these defaults by calling various GDI functions. Other GDI functions let you obtain the current values of these attributes. Then, of course, there are still other GDI functions that let you actually paint the client area of the window.

After a program has finished painting its client area, it should release the device context handle. When a program releases the handle, the handle is no longer valid and must not be used. The program should obtain the handle and release the handle during the processing of a single message. Except for a device context created with a call to CreateDC (a function I won't discuss in this chapter), you should not keep a device context handle around from one message to another.

Windows applications generally use two methods for getting a device context handle in preparation for painting the screen.

Getting a Device Context Handle: Method One

You use this method when you process WM_PAINT messages. Two functions are involved: BeginPaint and EndPaint. These two functions require the handle to the window, which is passed to the window procedure as an argument, and the address of a structure variable of type PAINTSTRUCT, which is defined in the WINUSER.H header file. Windows programmers usually name this structure variable ps and define it within the window procedure like so:

 PAINTSTRUCT ps ; 

While processing a WM_PAINT message, the window procedure first calls BeginPaint. The BeginPaint function generally causes the background of the invalid region to be erased in preparation for painting. The function also fills in the fields of the ps structure. The value returned from BeginPaint is the device context handle. This is commonly saved in a variable named hdc. You define this variable in your window procedure like so:

 HDC hdc ; 

The HDC data type is defined as a 32-bit unsigned integer. The program may then use GDI functions, such as TextOut, that require the handle to the device context. A call to EndPaint releases the device context handle.

Typically, processing of the WM_PAINT message looks like this:

 case WM_PAINT:      hdc = BeginPaint (hwnd, &ps) ;           [use GDI functions]      EndPaint (hwnd, &ps) ;      return 0 ; 

The window procedure must call BeginPaint and EndPaint as a pair while processing the WM_PAINT message. If a window procedure does not process WM_PAINT messages, it must pass the WM_PAINT message to DefWindowProc, which is the default window procedure located in Windows. DefWindowProc processes WM_PAINT messages with the following code:

 case WM_PAINT:      BeginPaint (hwnd, &ps) ;      EndPaint (hwnd, &ps) ;      return 0 ; 

The sequence of BeginPaint and EndPaint calls with nothing in between validates the previously invalid region.

But don't do this:

 case WM_PAINT:      return 0 ;   // WRONG !!! 

Windows places a WM_PAINT message in the message queue because part of the client area is invalid. Unless you call BeginPaint and EndPaint (or ValidateRect), Windows will not validate that area. Instead, Windows will send you another WM_PAINT message, and another, and another, and another….

The Paint Information Structure

Earlier I mentioned a "paint information structure" that Windows maintains for each window. That's what PAINTSTRUCT is. The structure is defined as follows:

 typedef struct tagPAINTSTRUCT {      HDC       hdc ;      BOOL      fErase ;      RECT      rcPaint ;      BOOL      fRestore ;      BOOL      fIncUpdate ;      BYTE      rgbReserved[32] ; } PAINTSTRUCT ; 

Windows fills in the fields of this structure when your program calls BeginPaint. Your program can use only the first three fields. The others are used internally by Windows. The hdc field is the handle to the device context. In a redundancy typical of Windows, the value returned from BeginPaint is also this device context handle. In most cases, fErase will be flagged FALSE (0), meaning that Windows has already erased the background of the invalid rectangle. This happens earlier in the BeginPaint function. (If you want to do some customized background erasing in your window procedure, you can process the WM_ERASEBKGND message.) Windows erases the background using the brush specified in the hbrBackground field of the WNDCLASS structure that you use when registering the window class during WinMain initialization. Many Windows programs specify a white brush for the window background. This is indicated when the program sets up the fields of the window class structure with a statement like this:

 wndclass.hbrBackground = (HBRUSH) GetStockObject (WHITE_BRUSH) ; 

However, if your program invalidates a rectangle of the client area by calling InvalidateRect, the last argument of the function specifies whether you want the background erased. If this argument is FALSE (that is, 0), Windows will not erase the background and the fErase field of the PAINTSTRUCT structure will be TRUE (nonzero) after you call BeginPaint.

The rcPaint field of the PAINTSTRUCT structure is a structure of type RECT. As you learned in Chapter 3, the RECT structure defines a rectangle with four fields named left, top, right, and bottom. The rcPaint field in the PAINTSTRUCT structure defines the boundaries of the invalid rectangle, as shown in Figure 4-1. The values are in units of pixels relative to the upper left corner of the client area. The invalid rectangle is the area that you should repaint.

Figure 4-1. The boundaries of the invalid rectangle.

The rcPaint rectangle in PAINTSTRUCT is not only the invalid rectangle; it is also a "clipping" rectangle. This means that Windows restricts painting to within the clipping rectangle. More precisely, if the invalid region is not rectangular, Windows restricts painting to within that region.

To paint outside the update rectangle while processing WM_PAINT messages, you can make this call:

 InvalidateRect (hwnd, NULL, TRUE) ; 

before calling BeginPaint. This invalidates the entire client area and causes BeginPaint to erase the background. A FALSE value in the last argument will not erase the background. Whatever was there will stay.

It is usually most convenient for a Windows program to simply repaint the entire client area whenever it receives a WM_PAINT message, regardless of the rcPaint structure. For example, if part of the display output in the client area includes a circle but only part of the circle falls within the invalid rectangle, it makes little sense to draw only the invalid part of the circle. Draw the whole circle. When you use the device context handle returned from BeginPaint, Windows will not paint outside the rcPaint rectangle anyway.

In the HELLOWIN program in Chapter 2, we didn't care about invalid rectangles when processing the WM_PAINT message. If the area where the text was displayed happened to be within the invalid rectangle, DrawText restored it. If not, then at some point during processing of the DrawText call Windows determined it didn't need to write anything on the display. But this determination takes time. A programmer concerned about performance and speed (and that includes all of us, I hope) will want to use the invalid rectangle during processing of the WM_PAINT message to avoid unnecessary GDI calls. This is particularly important if painting requires accessing disk files such as bitmaps.

Getting a Device Context Handle: Method Two

Although it is best to structure your program so that you can update the entire client area during the WM_PAINT message, you may also find it useful to paint part of the client area while processing messages other than WM_PAINT. Or you may need a device context handle for other purposes, such as obtaining information about the device context.

To get a handle to the device context of the client area of the window, you call GetDC to obtain the handle and ReleaseDC after you're done with it:

 hdc = GetDC (hwnd) ; [use GDI functions] ReleaseDC (hwnd, hdc) ; 

Like BeginPaint and EndPaint, the GetDC and ReleaseDC functions should be called in pairs. When you call GetDC while processing a message, you should call ReleaseDC before you exit the window procedure. Do not call GetDC in one message and ReleaseDC in another.

Unlike the device context handle returned from BeginPaint, the device context handle returned from GetDC has a clipping rectangle equal to the entire client area. You can paint on any part of the client area, not merely on the invalid rectangle (if indeed there is an invalid rectangle). Unlike BeginPaint, GetDC does not validate any invalid regions. If you need to validate the entire client area, you can call

 ValidateRect (hwnd, NULL) ; 

Generally, you'll use the GetDC and ReleaseDC calls in response to keyboard messages (such as in a word processing program) or mouse messages (such as in a drawing program). This allows the program to draw on the client area in prompt reaction to the user's keyboard or mouse input without deliberately invalidating part of the client area to generate WM_PAINT messages. However, even if you paint during messages other than WM_PAINT, your program must still accumulate enough information to be able to update the display whenever you do receive a WM_PAINT message.

A function similar to GetDC is GetWindowDC. While GetDC returns a device context handle for writing on the client area of the window, GetWindowDC returns a device context handle that lets you write on the entire window. For example, your program can use the device context handle returned from GetWindowDC to write on the window's title bar. However, your program would also have to process WM_NCPAINT ("nonclient paint") messages as well.

TextOut: The Details

TextOut is the most common GDI function for displaying text. Its syntax is

 TextOut (hdc, x, y, psText, iLength) ; 

Let's examine this function in more detail.

The first argument 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 (we discover with some degree of comfort) is black. The default device context also defines a text background color, and this is white. When a program writes text to the display, Windows uses this background color to fill in the rectangular space surrounding each character, called the "character box."

The 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 default text 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 psText argument is a pointer to a character string, and iLength is the number of characters in the string. If psText points to a Unicode character string, then the number of bytes in the string is double the iLength value. The string should not contain any ASCII control characters such as carriage returns, linefeeds, tabs, or backspaces. Windows displays these control characters as boxes or solid blocks. TextOut does not recognize a zero byte (or for Unicode, a zero short integer) as denoting the end of a string. The function uses the iLength argument to determine the string's length.

The x and y arguments to 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 is positioned at the coordinate point (x, y). In the default device context, the origin (that is, the point where x and y both equal 0) is the upper left corner of the client area. If you use zero values for x and y in TextOut, the character string starts flush against the upper left corner of the client area.

When you read the documentation of a GDI drawing function such as TextOut, you'll find that the coordinates passed to the function are usually documented as "logical coordinates." What this means exactly we'll examine in more detail in Chapter 5. For now, be aware that Windows has a variety of "mapping modes" that govern how the logical coordinates specified in GDI drawing 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 identifier defined in the WINGDI.H header file). Under the MM_TEXT mapping mode, logical units are the same as physical units, which are pixels, relative to the upper left corner of the client area. 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 4-2.) The MM_TEXT coordinate system is identical to the coordinate system that Windows uses to define the invalid rectangle in the PAINTSTRUCT structure. (Things are not quite as convenient with the other mapping modes, however.)

Figure 4-2. The x-coordinate and y-coordinate in the MM_TEXT mapping mode.

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 region for the device context handle obtained from BeginPaint. When you call TextOut, Windows will not display any part of the character string that lies outside the clipping region. If a character is partly within the clipping region, Windows displays only the portion of the character inside the region. Writing outside the client area of your window isn't easy to do, so don't worry about doing it inadvertently.

The System Font

The device context also defines the font that Windows uses when you call TextOut to display text. The default is a font called the "system font" or (using the identifier in the WINGDI.H header file) SYSTEM_FONT. The system font is the font that Windows uses by default for text strings in title bars, menus, and dialog boxes.

In the early days of Windows, the system font was a fixed-pitch font, which means that all the characters had the same width, much like a typewriter. However, beginning with Windows 3.0, the system font became a variable-pitch font, which means that different characters have different widths. A "W" is wider than an "i", for example. It has been well established by studies in reading that text printed with variable-pitch fonts is more readable than fixed-pitch font texts. It seems to have something to do with the letters being closer together, allowing the eyes and mind to more clearly see entire words rather than individual letters. As you might imagine, the change from fixed-pitch fonts to variable-pitch fonts broke a lot of early Windows code and required that programmers learn some new techniques for working with text.

The system font is a "raster font," which means that the characters are defined as blocks of pixels. (In Chapter 17, we'll work with TrueType fonts, which are defined by scaleable outlines.) To a certain extent, the size of the characters in the system font is based on the size of the video display. The system font is designed to allow at least 25 lines of 80-character text to fit on the screen.

The Size of a Character

To display multiple lines of text by using the TextOut function, you need to know the dimensions of characters in the font. You can space successive lines of text based on the height of the characters, and you can space columns of text across the client area based on the average width of the characters.

What is the height and average width of characters in the system font? Well, I'm not going to tell you. Or rather, I can't tell you. Or rather, I could tell you, but I might be wrong. The problem is that it all depends on the pixel size of the video display. Windows requires a minimum display size of 640 by 480, but many users prefer 800 by 600 or 1024 by 768. In addition, for these larger display sizes, Windows allows the user to select different sized system fonts.

Just as a program can determine information about the sizes (or "metrics") of user interface items by calling the GetSystemMetrics function, a program can determine font sizes by calling GetTextMetrics. GetTextMetrics requires a handle to a device context because it returns information about the font currently selected in the device context. Windows copies the various values of text metrics into a structure of type TEXTMETRIC defined in WINGDI.H. The TEXTMETRIC structure has 20 fields, but we're interested in only the first seven:

 typedef struct tagTEXTMETRIC {      LONG tmHeight ;       LONG tmAscent ;       LONG tmDescent ;        LONG tmInternalLeading ;       LONG tmExternalLeading ;       LONG tmAveCharWidth ;       LONG tmMaxCharWidth ;            [other structure fields] } TEXTMETRIC, * PTEXTMETRIC ; 

The values of these fields are in units that depend on the mapping mode currently selected for the device context. In the default device context, this mapping mode is MM_TEXT, so the dimensions are in units of pixels.

To use the GetTextMetrics function, you first need to define a structure variable, commonly called tm:

 TEXTMETRIC tm ; 

When you need to determine the text metrics, you get a handle to a device context and call GetTextMetrics:

 hdc = GetDC (hwnd) ; GetTextMetrics (hdc, &tm) ; ReleaseDC (hwnd, hdc) ; 

You can then examine the values in the text metric structure and probably save a few of them for future use.

Text Metrics: The Details

The TEXTMETRIC structure provides various types of information about the font currently selected in the device context. However, the vertical size of a font is defined by only five fields of the structure, four of which are shown in Figure 4-3.

Figure 4-3. Four values defining vertical character sizes in a font.

The most important value is tmHeight, which is the sum of tmAscent and tmDescent. These two values represent the maximum vertical extents of characters in the font above and below the baseline. The term "leading" refers to space that a printer inserts between lines of text. In the TEXTMETRIC structure, internal leading is included in tmAscent (and thus in tmHeight) and is often the space in which accent marks appear. The tmInternalLeading field could be set to 0, in which case accented letters are made a little shorter so that the accent marks fit within the ascent of the character.

The TEXTMETRIC structure also includes a field named tmExternalLeading, which is not included in the tmHeight value. This is an amount of space that the designer of the font suggests be added between successive rows of displayed text. You can accept or reject the font designer's suggestion for including external leading when spacing lines of text. In the system fonts that I've encountered recently, tmExternalLeading has been zero, which is why I didn't include it in Figure 4-3. (Despite my vow not to tell you the dimensions of a system font, Figure 4-3 is accurate for the system font that Windows uses by default for a 640 by 480 display.)

The TEXTMETRIC structure contains two fields that describe character widths: the tmAveCharWidth field is a weighted average of lowercase characters, and tmMaxCharWidth is the width of the widest character in the font. For a fixed-pitch font, these values are the same. (For the font illustrated in Figure 4-3, these values are 7 and 14, respectively.)

The sample programs in this chapter will require another character width—the average width of uppercase letters. You can calculate this fairly accurately as 150% of tmAveCharWidth.

It's important to realize that the dimensions of a system font are dependent on the pixel size of the video display on which Windows runs and, in some cases, on the system font size the user has selected. Windows provides a device-independent graphics interface, but you have to help. Don't write your Windows programs so that they guess at character dimensions. Don't hard-code any values. Use the GetTextMetrics function to obtain this information.

Formatting Text

Because the dimensions of the system font do not change during a Windows session, you need to call GetTextMetrics only once when your program executes. A good place to make this call is while processing the WM_CREATE message in the window procedure. The WM_CREATE message is the first message the window procedure receives. Windows calls your window procedure with a WM_CREATE message when you call CreateWindow in WinMain.

Suppose you're writing a Windows program that displays several lines of text running down the client area. You'll want to obtain values for the character width and height. Within the window procedure you can define two variables to save the average character width (cxChar) and the total character height (cyChar):

 static int cxChar, cyChar ; 

The prefix c added to the variables names stands for "count," and in this case means a count of (or number of) pixels. In combination with x or y, the prefix refers to a width or height. These variables are defined as static because they must be valid when the window procedure processes other messages, such as WM_PAINT. Or you can define the variables globally outside of any function.

Here's the WM_CREATE code to obtain the width and height of characters in the system font:

 case WM_CREATE:      hdc = GetDC (hwnd) ;      GetTextMetrics (hdc, &tm) ;      cxChar = tm.tmAveCharWidth ;      cyChar = tm.tmHeight + tm.tmExternalLeading ;      ReleaseDC (hwnd, hdc) ;      return 0 ; 

Notice that I've included the tmExternalLeading field in the calculation of cyChar. Even though this field is 0 in the system fonts I've seen lately, it should be included if it's ever nonzero because it makes for more readable line spacing. Each successive line of text is displayed cyChar pixels further down the window.

You'll often find it necessary to display formatted numbers as well as simple character strings. As I discussed in Chapter 2, you can't use the traditional tool for this job (the beloved printf function), but you can use sprintf and the Windows version of sprintf, wsprintf. These functions work just like printf except that they put the formatted string into a character string. You can then use TextOut to write the string to the display. Very conveniently, the value returned from sprintf and wsprintf is the length of the string. You can pass that value to TextOut as the iLength argument. This code shows a typical wsprintf and TextOut combination:

 int   iLength ; TCHAR szBuffer [40] ; [ other program lines ] iLength = wsprintf (szBuffer, TEXT ("The sum of %i and %i is %i"),                     iA, iB, iA + iB) ; TextOut (hdc, x, y, szBuffer, iLength) ; 

For something as simple as this, you could dispense with the iLength definition and combine the two statements into one:

 TextOut (hdc, x, y, szBuffer,          wsprintf (szBuffer, TEXT ("The sum of %i and %i is %i"),                    iA, iB, iA + iB)) ;  

It ain't pretty, but it works.

Putting It All Together

Now we seem to have everything we need to write a simple program that displays multiple lines of text on the screen. We know how to get a handle to a device context during the WM_PAINT message, how to use the TextOut function, and how to space text based on the size of a single character. The only thing left for us to do is to display something interesting.

In the previous chapter, we took a little peek at the interesting information available from the Windows GetSystemMetrics function. The function returns information about the size of various graphical items in Windows, such as icons, cursors, title bars, and scroll bars. These sizes vary with the display adapter and driver. GetSystemMetrics is an important function for achieving device-independent graphical output in your program.

The function requires a single argument called an "index." The index is one of 75 integer identifiers defined in the Windows header files. (The number of identifiers has increased with each release of Windows; the programmer's documentation in Windows 1.0 listed only 26 of them.) GetSystemMetrics returns an integer, usually the size of the item specified in the argument.

Let's write a program that displays some of the information available from the GetSystemMetrics calls in a simple one-line-per-item format. Working with this information is easier if we create a header file that defines an array of structures containing both the Windows header-file identifiers for the GetSystemMetrics index and the text we want to display for each value returned from the call. This header file is called SYSMETS.H and is shown in Figure 4-4.

Figure 4-4. The SYSMETS.H file.

SYSMETS.H

 /*-----------------------------------------------    SYSMETS.H -- System metrics display structure   -----------------------------------------------*/ #define NUMLINES ((int) (sizeof sysmetrics / sizeof sysmetrics [0])) struct {      int     iIndex ;      TCHAR * szLabel ;      TCHAR * szDesc ; } sysmetrics [] = {      SM_CXSCREEN,             TEXT ("SM_CXSCREEN"),                                             TEXT ("Screen width in pixels"),      SM_CYSCREEN,             TEXT ("SM_CYSCREEN"),                                             TEXT ("Screen height in pixels"),      SM_CXVSCROLL,            TEXT ("SM_CXVSCROLL"),                                            TEXT ("Vertical scroll width"),      SM_CYHSCROLL,            TEXT ("SM_CYHSCROLL"),                                            TEXT ("Horizontal scroll height"),      SM_CYCAPTION,            TEXT ("SM_CYCAPTION"),                                            TEXT ("Caption bar height"),      SM_CXBORDER,             TEXT ("SM_CXBORDER"),                                             TEXT ("Window border width"),      SM_CYBORDER,             TEXT ("SM_CYBORDER"),                                             TEXT ("Window border height"),      SM_CXFIXEDFRAME,         TEXT ("SM_CXFIXEDFRAME"),                                         TEXT ("Dialog window frame width"),      SM_CYFIXEDFRAME,         TEXT ("SM_CYFIXEDFRAME"),                                         TEXT ("Dialog window frame height"),      SM_CYVTHUMB,             TEXT ("SM_CYVTHUMB"),                                             TEXT ("Vertical scroll thumb height"),      SM_CXHTHUMB,             TEXT ("SM_CXHTHUMB"),                                             TEXT ("Horizontal scroll thumb width"),      SM_CXICON,               TEXT ("SM_CXICON"),                                               TEXT ("Icon width"),      SM_CYICON,               TEXT ("SM_CYICON"),                                               TEXT ("Icon height"),      SM_CXCURSOR,             TEXT ("SM_CXCURSOR"),                                             TEXT ("Cursor width"),      SM_CYCURSOR,             TEXT ("SM_CYCURSOR"),                                             TEXT ("Cursor height"),      SM_CYMENU,               TEXT ("SM_CYMENU"),                                               TEXT ("Menu bar height"),      SM_CXFULLSCREEN,         TEXT ("SM_CXFULLSCREEN"),                                         TEXT ("Full screen client area width"),      SM_CYFULLSCREEN,         TEXT ("SM_CYFULLSCREEN"),                                         TEXT ("Full screen client area height"),      SM_CYKANJIWINDOW,        TEXT ("SM_CYKANJIWINDOW"),                                        TEXT ("Kanji window height"),      SM_MOUSEPRESENT,         TEXT ("SM_MOUSEPRESENT"),                                         TEXT ("Mouse present flag"),      SM_CYVSCROLL,            TEXT ("SM_CYVSCROLL"),                                            TEXT ("Vertical scroll arrow height"),      SM_CXHSCROLL,            TEXT ("SM_CXHSCROLL"),                                            TEXT ("Horizontal scroll arrow width"),      SM_DEBUG,                TEXT ("SM_DEBUG"),                                                TEXT ("Debug version flag"),      SM_SWAPBUTTON,           TEXT ("SM_SWAPBUTTON"),                                           TEXT ("Mouse buttons swapped flag"),      SM_CXMIN,                TEXT ("SM_CXMIN"),                                                TEXT ("Minimum window width"),      SM_CYMIN,                TEXT ("SM_CYMIN"),                                                TEXT ("Minimum window height"),      SM_CXSIZE,               TEXT ("SM_CXSIZE"),                                               TEXT ("Min/Max/Close button width"),      SM_CYSIZE,               TEXT ("SM_CYSIZE"),                                               TEXT ("Min/Max/Close button height"),      SM_CXSIZEFRAME,          TEXT ("SM_CXSIZEFRAME"),                                          TEXT ("Window sizing frame width"),      SM_CYSIZEFRAME,          TEXT ("SM_CYSIZEFRAME"),                                          TEXT ("Window sizing frame height"),      SM_CXMINTRACK,           TEXT ("SM_CXMINTRACK"),                                           TEXT ("Minimum window tracking width"),      SM_CYMINTRACK,           TEXT ("SM_CYMINTRACK"),                                           TEXT ("Minimum window tracking height"),      SM_CXDOUBLECLK,          TEXT ("SM_CXDOUBLECLK"),                                          TEXT ("Double click x tolerance"),      SM_CYDOUBLECLK,          TEXT ("SM_CYDOUBLECLK"),                                          TEXT ("Double click y tolerance"),      SM_CXICONSPACING,        TEXT ("SM_CXICONSPACING"),                                        TEXT ("Horizontal icon spacing"),      SM_CYICONSPACING,        TEXT ("SM_CYICONSPACING"),                                        TEXT ("Vertical icon spacing"),      SM_MENUDROPALIGNMENT,    TEXT ("SM_MENUDROPALIGNMENT"),                                    TEXT ("Left or right menu drop"),      SM_PENWINDOWS,           TEXT ("SM_PENWINDOWS"),                                           TEXT ("Pen extensions installed"),      SM_DBCSENABLED,          TEXT ("SM_DBCSENABLED"),                                          TEXT ("Double-Byte Char Set enabled"),      SM_CMOUSEBUTTONS,        TEXT ("SM_CMOUSEBUTTONS"),                                        TEXT ("Number of mouse buttons"),      SM_SECURE,               TEXT ("SM_SECURE"),                                               TEXT ("Security present flag"),      SM_CXEDGE,               TEXT ("SM_CXEDGE"),                                               TEXT ("3-D border width"),      SM_CYEDGE,               TEXT ("SM_CYEDGE"),                                               TEXT ("3-D border height"),      SM_CXMINSPACING,         TEXT ("SM_CXMINSPACING"),                                         TEXT ("Minimized window spacing width"),      SM_CYMINSPACING,         TEXT ("SM_CYMINSPACING"),                                         TEXT ("Minimized window spacing height"),      SM_CXSMICON,             TEXT ("SM_CXSMICON"),                                             TEXT ("Small icon width"),      SM_CYSMICON,             TEXT ("SM_CYSMICON"),                                             TEXT ("Small icon height"),      SM_CYSMCAPTION,          TEXT ("SM_CYSMCAPTION"),                                          TEXT ("Small caption height"),      SM_CXSMSIZE,             TEXT ("SM_CXSMSIZE"),                                             TEXT ("Small caption button width"),      SM_CYSMSIZE,             TEXT ("SM_CYSMSIZE"),                                             TEXT ("Small caption button height"),      SM_CXMENUSIZE,           TEXT ("SM_CXMENUSIZE"),                                           TEXT ("Menu bar button width"),      SM_CYMENUSIZE,           TEXT ("SM_CYMENUSIZE"),                                           TEXT ("Menu bar button height"),      SM_ARRANGE,              TEXT ("SM_ARRANGE"),                                              TEXT ("How minimized windows arranged"),      SM_CXMINIMIZED,          TEXT ("SM_CXMINIMIZED"),                                          TEXT ("Minimized window width"),      SM_CYMINIMIZED,          TEXT ("SM_CYMINIMIZED"),                                          TEXT ("Minimized window height"),      SM_CXMAXTRACK,           TEXT ("SM_CXMAXTRACK"),                                           TEXT ("Maximum draggable width"),      SM_CYMAXTRACK,           TEXT ("SM_CYMAXTRACK"),                                           TEXT ("Maximum draggable height"),      SM_CXMAXIMIZED,          TEXT ("SM_CXMAXIMIZED"),                                          TEXT ("Width of maximized window"),      SM_CYMAXIMIZED,          TEXT ("SM_CYMAXIMIZED"),                                          TEXT ("Height of maximized window"),      SM_NETWORK,              TEXT ("SM_NETWORK"),                                              TEXT ("Network present flag"),      SM_CLEANBOOT,            TEXT ("SM_CLEANBOOT"),                                            TEXT ("How system was booted"),      SM_CXDRAG,               TEXT ("SM_CXDRAG"),                                               TEXT ("Avoid drag x tolerance"),      SM_CYDRAG,               TEXT ("SM_CYDRAG"),                                               TEXT ("Avoid drag y tolerance"),      SM_SHOWSOUNDS,           TEXT ("SM_SHOWSOUNDS"),                                           TEXT ("Present sounds visually"),      SM_CXMENUCHECK,          TEXT ("SM_CXMENUCHECK"),                                          TEXT ("Menu check-mark width"),      SM_CYMENUCHECK,          TEXT ("SM_CYMENUCHECK"),                                          TEXT ("Menu check-mark height"),      SM_SLOWMACHINE,          TEXT ("SM_SLOWMACHINE"),                                          TEXT ("Slow processor flag"),      SM_MIDEASTENABLED,       TEXT ("SM_MIDEASTENABLED"),                                       TEXT ("Hebrew and Arabic enabled flag"),      SM_MOUSEWHEELPRESENT,    TEXT ("SM_MOUSEWHEELPRESENT"),                                    TEXT ("Mouse wheel present flag"),      SM_XVIRTUALSCREEN,       TEXT ("SM_XVIRTUALSCREEN"),                                       TEXT ("Virtual screen x origin"),      SM_YVIRTUALSCREEN,       TEXT ("SM_YVIRTUALSCREEN"),                                       TEXT ("Virtual screen y origin"),      SM_CXVIRTUALSCREEN,      TEXT ("SM_CXVIRTUALSCREEN"),                                      TEXT ("Virtual screen width"),      SM_CYVIRTUALSCREEN,      TEXT ("SM_CYVIRTUALSCREEN"),                                      TEXT ("Virtual screen height"),      SM_CMONITORS,            TEXT ("SM_CMONITORS"),                                            TEXT ("Number of monitors"),      SM_SAMEDISPLAYFORMAT,    TEXT ("SM_SAMEDISPLAYFORMAT"),                                    TEXT ("Same color format flag") } ; 

The program that displays this information is called SYSMETS1. The SYSMETS1.C source code file is shown in Figure 4-5. Most of the code should look familiar by now. The code in WinMain is virtually identical to that in HELLOWIN, and much of the code in WndProc has already been discussed.

Figure 4-5. SYSMETS1.C.

SYSMETS1.C

 /*----------------------------------------------------    SYSMETS1.C -- System Metrics Display Program No. 1                  (c) Charles Petzold, 1998   ----------------------------------------------------*/ #include <windows.h> #include "sysmets.h" LRESULT CALLBACK WndProc (HWND, UINT, WPARAM, LPARAM) ; int WINAPI WinMain (HINSTANCE hInstance, HINSTANCE hPrevInstance,                     PSTR szCmdLine, int iCmdShow) {      static TCHAR szAppName[] = TEXT ("SysMets1") ;      HWND         hwnd ;      MSG          msg ;      WNDCLASS     wndclass ;      wndclass.style         = CS_HREDRAW | CS_VREDRAW ;      wndclass.lpfnWndProc   = WndProc ;      wndclass.cbClsExtra    = 0 ;      wndclass.cbWndExtra    = 0 ;      wndclass.hInstance     = hInstance ;      wndclass.hIcon         = LoadIcon (NULL, IDI_APPLICATION) ;      wndclass.hCursor       = LoadCursor (NULL, IDC_ARROW) ;      wndclass.hbrBackground = (HBRUSH) GetStockObject (WHITE_BRUSH) ;      wndclass.lpszMenuName  = NULL ;      wndclass.lpszClassName = szAppName ;      if (!RegisterClass (&wndclass))        {           MessageBox (NULL, TEXT ("This program requires Windows NT!"),                        szAppName, MB_ICONERROR) ;           return 0 ;      }      hwnd = CreateWindow (szAppName, TEXT ("Get System Metrics No. 1"),                           WS_OVERLAPPEDWINDOW,                           CW_USEDEFAULT, CW_USEDEFAULT,                           CW_USEDEFAULT, CW_USEDEFAULT,                           NULL, NULL, hInstance, NULL) ;      ShowWindow (hwnd, iCmdShow) ;      UpdateWindow (hwnd) ;      while (GetMessage (&msg, NULL, 0, 0))           {           TranslateMessage (&msg) ;           DispatchMessage (&msg) ;           }      return msg.wParam ;      } LRESULT CALLBACK WndProc (HWND hwnd, UINT message, WPARAM wParam, LPARAM lParam) {      static int  cxChar, cxCaps, cyChar ;      HDC         hdc ;      int         i ;      PAINTSTRUCT ps ;      TCHAR       szBuffer [10] ;      TEXTMETRIC  tm ;      switch (message)      {      case WM_CREATE:           hdc = GetDC (hwnd) ;           GetTextMetrics (hdc, &tm) ;           cxChar = tm.tmAveCharWidth ;           cxCaps = (tm.tmPitchAndFamily & 1 ? 3 : 2) * cxChar / 2 ;           cyChar = tm.tmHeight + tm.tmExternalLeading ;           ReleaseDC (hwnd, hdc) ;           return 0 ;      case WM_PAINT :           hdc = BeginPaint (hwnd, &ps) ;           for (i = 0 ; i < NUMLINES ; i++)           {                TextOut (hdc, 0, cyChar * i,                                               sysmetrics[i].szLabel,                         lstrlen (sysmetrics[i].szLabel)) ;                TextOut (hdc, 22 * cxCaps, cyChar * i,                               sysmetrics[i].szDesc,                         lstrlen (sysmetrics[i].szDesc)) ;                SetTextAlign (hdc, TA_RIGHT | TA_TOP) ;                TextOut (hdc, 22 * cxCaps + 40 * cxChar, cyChar * i, szBuffer,                         wsprintf (szBuffer, TEXT ("%5d"),                                   GetSystemMetrics (sysmetrics[i].iIndex))) ;                SetTextAlign (hdc, TA_LEFT | TA_TOP) ;           }           EndPaint (hwnd, &ps) ;           return 0 ;      case WM_DESTROY :           PostQuitMessage (0) ;           return 0 ;      }      return DefWindowProc (hwnd, message, wParam, lParam) ; } 

Figure 4-6 shows SYSMETS1 running on a standard VGA. As you can see from the first two lines in the program's client area, the screen width is 640 pixels and the screen height is 480 pixels. These two values, as well as many of the other values shown by the program, may be different for different types of video displays.

Figure 4-6. The SYSMETS1 display.

The SYSMETS1.C Window Procedure

The WndProc window procedure in the SYSMETS1.C program processes three messages: WM_CREATE, WM_PAINT, and WM_DESTROY. The WM_DESTROY message is processed in the same way as the HELLOWIN program in Chapter 3.

The WM_CREATE message is the first message the window procedure receives. Windows generates the message when the CreateWindow function creates the window. During the WM_CREATE message, SYSMETS1 obtains a device context for the window by calling GetDC and gets the text metrics for the default system font by calling GetTextMetrics. SYSMETS1 saves the average character width in cxChar and the total height of the characters (including external leading) in cyChar.

SYSMETS1 also saves an average width of uppercase letters in the static variable cxCaps. For a fixed-pitch font, cxCaps would equal cxChar. For a variable-width font, cxCaps is set to 150 percent of cxChar. The low bit of the tmPitchAndFamily field in the TEXTMETRIC structure is 1 for a variable-width font and 0 for a fixed-pitch font. SYSMETS1 uses this bit to calculate cxCaps from cxChar:

 cxCaps = (tm.tmPitchAndFamily & 1 ? 3 : 2) * cxChar / 2 ; 

SYSMETS1 does all window painting during the WM_PAINT message. As normal, the window procedure first obtains a handle to the device context by calling BeginPaint. A for statement loops through all the lines of the sysmetrics structure defined in SYSMETS.H. The three columns of text are displayed with three TextOut function calls. In each case, the third argument to TextOut (that is, the y starting position) is set to

 cyChar * i 

This argument indicates the pixel position of the top of the character string relative to the top of the client area.

The first TextOut statement displays the uppercase identifiers in the first of the three columns. The second argument to TextOut is 0 to begin the text at the left edge of the client area. The text is obtained from the szLabel field of the sysmetrics structure. I use the Windows function lstrlen to calculate the length of the string, which is required as the last argument to TextOut.

The second TextOut statement displays the description of the system metrics value. These descriptions are stored in the szDesc field of the sysmetrics structure. In this case, the second argument to TextOut is set to

 22 * cxCaps 

The longest uppercase identifier displayed in the first column is 20 characters, so the second column must begin at least 20 × cxCaps to the right of the beginning of the first column of text. I use 22 to add a little extra space between the columns.

The third TextOut statement displays the numeric values obtained from the GetSystemMetrics function. The variable-width font makes formatting a column of right-justified numbers a little tricky. Fortunately, in all variable-width fonts used today, the digits from 0 through 9 all have the same width. Otherwise, displaying columns of numbers would be monstrous. However, the width of the digits is greater than the width of a space. Numbers can be one or more digits wide, so different numbers can begin at different horizontal positions.

Wouldn't it be easier if we could display a column of right-justified numbers by specifying the horizontal pixel position where the number ends rather than begins? This is what the SetTextAlign function lets us do (among other things). After SYSMETS1 calls

 SetTextAlign (hdc, TA_RIGHT | TA_TOP) ; 

Windows will interpret the coordinates passed to subsequent TextOut functions as specifying the top-right corner of the text string rather than the top-left corner.

The TextOut function to display the column of numbers has its second argument set to

 22 * cxCaps + 40 * cxChar 

The 40 × cxChar value accommodates the width of the second column and the width of the third column. Following the TextOut function, another call to SetTextAlign sets things back to normal for the next time through the loop.

Not Enough Room

One nasty little problem exists with the SYSMETS1 program: Unless you have a gigantic, big-screen, high-resolution video adapter, you can't see many of the lines in the system metrics lists. If you make the window narrower, you can't even see the values.

SYSMETS1 is not aware of this problem. Otherwise we might have included a message box that said, "Sorry!" It's not aware of the problem because the program doesn't even know how large its client area is. It begins displaying the text at the top of the window and relies on Windows to clip everything that drifts beyond the bottom of the client area.

Clearly, this is not desirable. Our first job in solving this problem is to determine how much of the program's output can actually fit within the client area.

The Size of the Client Area

If you experiment with existing Windows applications, you'll find that window sizes can vary widely. If a window is maximized, the client area occupies nearly the entire video display. The dimensions of a maximized client area are, in fact, available from the GetSystemMetrics call by using arguments of SM_CXFULLSCREEN and SM_CYFULLSCREEN (assuming that the window has only a title bar and no menu). The minimum size of a window can be quite small—sometimes almost nonexistent—virtually eliminating the client area.

In the last chapter, we used the GetClientRect function for determining the dimensions of the client area. There's nothing really wrong with this function, but it's a bit inefficient to call it every time you need to use this information. A much better method for determining the size of a window's client is to process the WM_SIZE message within your window procedure. Windows sends a WM_SIZE message to a window procedure whenever the size of the window changes. The lParam variable passed to the window procedure contains the width of the client area in the low word and the height in the high word. To save these dimensions, you'll want to define two static variables in your window procedure:

 static int cxClient, cyClient ; 

Like cxChar and cyChar, these variables are defined as static because they are set while processing one message and used while processing another message. You handle the WM_SIZE method like so:

 case WM_SIZE:     cxClient = LOWORD (lParam) ;     cyClient = HIWORD (lParam) ;     return 0 ; 

You'll see code like this in virtually every Windows program. LOWORD and HIWORD are macros that are defined in the Windows header file WINDEF.H. If you're curious, the definitions of these macros look like this:

 #define LOWORD(l) ((WORD)(l)) #define HIWORD(l) ((WORD)(((DWORD)(l) >> 16) & 0xFFFF)) 

The two macros return WORD values—that is, 16-bit unsigned short integers that range from 0 through 0xFFFF. Typically you'll store these values in 32-bit signed integers. That doesn't involve any conversion problems and makes the values easier to use in any calculations you may later need.

In many Windows programs, a WM_SIZE message will eventually be followed by a WM_PAINT message. How do we know this? Because when we define the window class we specify the class style as

 CS_HREDRAW | CS_VREDRAW 

This class style tells Windows to force a repaint if either the horizontal or vertical size changes.

You can calculate the number of full lines of text displayable within the client area with the formula:

 cyClient / cyChar 

This can be 0 if the height of the client area is too small to display a full character. Similarly, the approximate number of lowercase characters you can display horizontally within the client area is equal to

 cxClient / cxChar 

If you determine cxChar and cyChar during the WM_CREATE message, don't worry about dividing by 0 in these calculations. Your window procedure receives a WM_CREATE message when WinMain calls CreateWindow. The first WM_SIZE message comes a little later, when WinMain calls ShowWindow, at which point cxChar and cyChar have already been assigned positive nonzero values.

Knowing the size of the window's client area is the first step in providing a way for the user to move the text within the client area if the client area is not large enough to hold everything. If you're familiar with other Windows-based applications that have similar requirements, you probably know what we need: this is a job for those wonderful inventions known as scroll bars.