The first job involved in adding a dialog box to a program is designing the dialog box template. This template can go directly in the resource script file, or it can be in a separate file that by convention uses the extension .DLG (for ”dialog“). If you put the template in a separate file, you include the line:
rcinclude filename.dlg
in the resource script file.
You can create the dialog box template by hand in a text editor, or you can use the DIALOG program included with the Windows Software Development Kit. Because the output from DIALOG is virtually unreadable, I'll be showing dialog box templates that look as if they were created by hand. A discussion of DIALOG concludes this chapter.
The dialog box template for ABOUT1 looks like this:
AboutBox DIALOG 20, 20, 160, 80
STYLE WS_POPUP | WS_DLGFRAME
{
CTEXT "About1" -1, 0, 12, 160, 8
ICON "About1" -1, 8, 8, 0, 0
CTEXT "About Box Demo Program" -1, 0, 36, 160, 8
CTEXT "(c) Charles Petzold, 1990" -1, 0, 48, 160, 8
DEFPUSHBUTTON "OK" IDOK, 64, 60, 32, 14, WS_GROUP
}
The first line gives the dialog box a name (in this case, AboutBox). As is the case for other resources, you can use a number instead. The name is followed by the keyword DIALOG and four numbers. The first two numbers are the x- and y-coordinates of the upper left corner of the dialog box, relative to the client area of its parent when the dialog box is invoked by the program. The second two numbers are the width and height of the dialog box.
These coordinates and sizes are not in units of pixels. They are instead based on a special coordinate system used only for dialog box templates. The numbers are based on the size of a system font character: x-coordinates and width are expressed in units of 1/4 of an average character width; y-coordinates and height are expressed in units of 1/8 of a character height. Thus for this particular dialog box, the upper left corner of the dialog box is 5 characters from the left of the main window's client area and 2-1/2 characters from the top. It is 40 characters wide and 10 characters high.
This coordinate system allows you to use coordinates and sizes that will retain the general dimensions and look of the dialog box regardless of the resolution of the video display. Because system font characters are often approximately twice as high as they are wide, the units on both the x- and y-axes are about the same.
The DIALOG statement can also include load options (PRELOAD and LOADONCALL) and memory options (FIXED, MOVEABLE, and DISCARDABLE) immediately following the word DIALOG. The defaults are LOADONCALL and MOVEABLE. The STYLE statement in the template is similar to the style field of a CreateWindow call. Using WS_POPUP and WS_DLGFRAME is normal for modal dialog boxes, but we'll explore some alternatives later on.
Within the left and right brackets, you define the child window controls that will appear in the dialog box. This dialog box uses three types of child window controls: CTEXT (centered text), ICON (an icon), and DEFPUSHBUTTON (a default push button). The format of these statements is:
control-type "text" nID, xPos, yPos, xWidth, yHeight, dwStyle
The dwStyle value at the end is optional; it specifies additional window styles using identifiers defined in WINDOWS.H.
These CTEXT, ICON, and DEFPUSHBUTTON identifiers are used only in dialog boxes. They are shorthand for a particular window class and window style. For example, CTEXT indicates that the class of the child window control is ”static“ and that the style is:
WS_CHILD | SS_CENTER | WS_VISIBLE | WS_GROUP
Although this is the first time we've encountered the WS_GROUP identifier, we used the WS_CHILD, SS_CENTER, and WS_VISIBLE window styles when creating static child window text controls in the COLORS1 program in Chapter 6.
For the icon, the text field is the name of the program's icon resource, which is also defined in the ABOUT1 resource script. For the push button, the text field is the text that appears inside the push button. This text is equivalent to the text specified as the second parameter to a CreateWindow call when you create a child window control in a program.
The nID field is a value that the child window uses to identify itself when sending messages (usually WM_COMMMAND messages) to its parent. The parent window of these child window controls is the dialog box window itself, which sends these messages to a window procedure in Windows. However, this window procedure also sends these messages to the dialog box procedure that you'll include in your program. The nID values are equivalent to the child window IDs used in the CreateWindow function when we created child windows in Chapter 6. Because the text and icon controls do not send messages back to the parent window, these values are set to -1. The nID value for the push button is IDOK, which is defined in WINDOWS.H as 1.
The next four numbers set the position of the child window control (relative to the upper left corner of the dialog box's client area) and the size. The position and size are expressed in units of 1/4 the average width and 1/8 the height of a system font character. The width and height values are ignored for the ICON statement.
The DEFPUSHBUTTON statement in the dialog box template includes the window style WS_GROUP in addition to the window style implied by the DEFPUSHBUTTON keyword. I'll have more to say about WS_GROUP (and the related WS_TABSTOP style) when discussing the second version of this program, ABOUT2, a bit later.