In the history of Windows, there have been four versions of dialog templates. And despite the changes, you'll see that they're basically all the same.

First, there was the classic Windows 1.0 dialog template. It starts like this:

DWORD dwStyle; // dialog style
BYTE  cItems;  // number of controls in this dialog
WORD  x;       // x-coordinate
WORD  y;       // y-coordinate
WORD  cx;      // width
WORD  cy;      // height

Notice that this is where the 255-controls-per-dialog limit comes from on 16-bit Windows, since the field that records the number of controls on the dialog is only a byte.

After this header come a series of strings. All strings in the 16-bit dialog template permit a null-terminated ANSI string. For example, if you wanted to store the string "Hello", you would write out the six bytes

48 65 6C 6C 6F 00  ; "Hello"

(As a special case of this: If you write out a single 00 byte, then that represents a null string. Handy when you don't actually want to store a string but the dialog format requires you to store one.)

Sometimes you are allowed to specify a 16-bit ordinal value instead of a string. In that case, you write out the byte 0xFF followed by the ordinal. For example, if you wanted to specify the ordinal 42, you would write out the three bytes

FF 2A 00           ; FF followed by WORD (little-endian)

Okay, back to the dialog template. After the header, there are three strings:

  • The menu name, which can be a string or an ordinal. This is typically null, indicating that you don't want a menu. If non-null, then the menu will be loaded via LoadMenu using the specified string or resource from the instance handle passed to the dialog creation function via the HINSTANCE parameter.
  • The class, which must be a string (no ordinals allowed). This is typically also null, indicating that you want the default dialog class. We have seen earlier how you can override the default dialog class to get special behavior. If non-null, the class will be also be looked up relative to the instance handle passed to the dialog creation function via the HINSTANCE parameter.
  • The dialog title, which must be a string (no ordinals allowed).

If the DS_SETFONT style is set, then what follows next is a WORD indicating the point size and a string specifying the font name. Otherwise, there is no font information.

That's the end of the header section. Next come a series of dialog item templates, one for each control.

Each item template begins the same way:

WORD  x;       // x-coordinate (DLUs)
WORD  y;       // y-coordinate (DLUs)
WORD  cx;      // width (DLUs)
WORD  cy;      // height (DLUs)
WORD  wID;     // control ID
DWORD dwStyle; // window style

Recall that the dialog coordinates are recorded in dialog units (DLUs). Four x-DLUs and eight y-DLUs equals one "average" character.

After the fixed start of the item template comes the class name, either as a null-terminated ANSI string or (and this is particularly weird) as single byte in the range 0x80 through 0xFF which encodes one of the "standard" window classes:

  • 0x80 = "button"
  • 0x81 = "edit"
  • 0x82 = "static"
  • 0x83 = "listbox"
  • 0x84 = "scrollbar"
  • 0x85 = "combobox"

(Note that this encoding means that the first character of a window class name cannot be an extended character if you want to use it in a dialog template!)

After the class name comes the control text, either as a null-terminated string or as an ordinal. If you use an ordinal, then the lpszName member of the CREATESTRUCT is a pointer to the three-byte ordinal sequence (0xFF followed by the ordinal); otherwise it's a pointer to the string. The only control I know of that knows what to do with the ordinal is the static control if you put it into one of the image modes (SS_ICON or SS_BITMAP), in which case the ordinal is a resource identifier for the image that the static displays.

After the control text comes up to 256 bytes of "extra data" in the form of a byte count, followed by the actual data. If there is no "extra data", then use a byte count of zero.

When the dialog manager creates a control, it passes a pointer to the "extra" data as the final LPVOID parameter to the CreateWindowEx function. (As far as I can tell, there is no way to tell the resource compiler to insert this extra data. It's one of those lurking features that nobody has taken advantage of yet.)

Okay, that's all great and theoretical. But sometimes you just need to see it in front of you to understand it. So let's take apart an actual 16-bit dialog resource. I took this one from COMMCTRL.DLL; it's the search/replace dialog.

0000  C0 00 C8 80 0B 24 00 2C-00 E6 00 5E 00 00 00 52  .....$.,...^...R
0010  65 70 6C 61 63 65 00 08-00 48 65 6C 76 00 04 00  eplace...Helv...
0020  09 00 30 00 08 00 FF FF-00 00 00 50 82 46 69 26  ..0........P.Fi&
0030  6E 64 20 57 68 61 74 3A-00 00 36 00 07 00 72 00  nd What:..6...r.
0040  0C 00 80 04 80 00 83 50-81 00 00 04 00 1A 00 30  .......P.......0
0050  00 08 00 FF FF 00 00 00-50 82 52 65 26 70 6C 61  ........P.Re&pla
0060  63 65 20 57 69 74 68 3A-00 00 36 00 18 00 72 00  ce With:..6...r.
0070  0C 00 81 04 80 00 83 50-81 00 00 05 00 2E 00 68  .......P.......h
0080  00 0C 00 10 04 03 00 03-50 80 4D 61 74 63 68 20  ........P.Match
0090  26 57 68 6F 6C 65 20 57-6F 72 64 20 4F 6E 6C 79  &Whole Word Only
00A0  00 00 05 00 3E 00 3B 00-0C 00 11 04 03 00 01 50  ....>.;........P
00B0  80 4D 61 74 63 68 20 26-43 61 73 65 00 00 AE 00  .Match &Case....
00C0  04 00 32 00 0E 00 01 00-01 00 03 50 80 26 46 69  ..2........P.&Fi
00D0  6E 64 20 4E 65 78 74 00-00 AE 00 15 00 32 00 0E  nd Next......2..
00E0  00 00 04 00 00 03 50 80-26 52 65 70 6C 61 63 65  ......P.&Replace
00F0  00 00 AE 00 26 00 32 00-0E 00 01 04 00 00 03 50  ....&.2........P
0100  80 52 65 70 6C 61 63 65-20 26 41 6C 6C 00 00 AE  .Replace &All...
0110  00 37 00 32 00 0E 00 02-00 00 00 03 50 80 43 61  .7.2........P.Ca
0120  6E 63 65 6C 00 00 AE 00-4B 00 32 00 0E 00 0E 04  ncel....K.2.....
0130  00 00 03 50 80 26 48 65-6C 70 00 00              ...P.&Help..

Let's start with the header.

0000  C0 00 C8 80  // dwStyle
0004  0B           // cItems
0005  24 00 2C 00  // x, y
0009  E6 00 5E 00  // cx, cy

In other words, the header says

dwStyle = 0x80C800C0 = WS_POPUP | WS_CAPTION | WS_SYSMENU | DS_SETFONT | DS_MODALFRAME
cItems = 0x0B = 11
x = 0x0024 = 36
y = 0x002C = 44
cx = 0x00E6 = 230
cy = 0x005E = 94

After the header come the menu name, class name, and dialog title:

000D  00            // no menu
000E  00            // default dialog class
000F  52 65 70 6C 61 63 65 00 // "Replace"

Now, since the DS_SETFONT bit is set in the style, the next section describes the font to be used by the dialog:

0017  08 00         // wSize = 8
0019  48 65 6C 76 00 // "Helv"

Aha, this dialog box uses 8pt Helv.

Next come the eleven dialog item templates.

001E  04 00 09 00   // x, y
0022  30 00 08 00   // cx, cy
0026  FF FF         // wID
0028  00 00 00 50   // dwStyle

So this dialog item template says

x = 0x0004 = 4
y = 0x0009 = 9
cx = 0x0030 = 48
cy = 0x0008 = 8
wID = 0xFFFF = -1
dwStyle = 0x50000000 = WS_CHILD | WS_VISIBLE | SS_LEFT

How did I know that the style value 0x0000 should be interpreted as SS_LEFT and not, say, BS_PUSHBUTTON? Because the window class tells me that what I have is a static control.

002C  82            // "static"

After the class name comes the control text.

002D  46 69 26 6E 64 20 57 68 61 74 3A 00 // "Fi&nd What:"

And finally (for this dialog item template), we specify that we have no extra data:

0039  00            // no extra data

Now we repeat the above exercise for the other ten controls. I'll just summarize here:

// Second control
003A  36 00 07 00   // x, y
003E  72 00 0C 00   // cx, cy
0042  80 04         // wID
0044  80 00 83 50   // dwStyle
0048  81            // "edit"
0049  00            // ""
004A  00            // no extra data

// Third control
004B  04 00 1A 00   // x, y
004F  30 00 08 00   // cx, cy
0053  FF FF         // wID
0055  00 00 00 50   // dwStyle
0059  82            // "static"
005A  52 65 26 70 6C 61 63 65 20 57 69 74 68 3A 00
                    // "Re&place With:"
0069  00            // no extra data

// Fourth control
006A  36 00 18 00   // x, y
006E  72 00 0C 00   // cx, cy
0072  81 04         // wID
0074  80 00 83 50   // dwStyle
0078  81            // "edit"
0079  00            // ""
007A  00            // no extra data

// Fifth control
007B  05 00 2E 00   // x, y
007F  68 00 0C 00   // cx, cy
0083  10 04         // wID
0085  03 00 03 50   // dwStyle
0089  80            // "button"
008A  4D 61 74 63 68 20 26 57 68 6F 6C 65 20 57
      6F 72 64 20 4F 6E 6C 79 00
                    // "Match &Whole Word Only"
00A1  00            // no extra data

// Sixth control
00A2  05 00 3E 00   // x, y
00A6  3B 00 0C 00   // cx, cy
00AA  11 04         // wID
00AC  03 00 01 50   // dwStyle
00B0  80            // "button"
00B1  4D 61 74 63 68 20 26 43 61 73 65 00
                    // "Match &Case"
00BD  00            // no extra data

// Seventh control
00BE  AE 00 04 00   // x, y
00C2  32 00 0E 00   // cx, cy
00C6  01 00         // wID
00C8  01 00 03 50   // dwStyle
00CC  80            // "button"
00CD  26 46 69 6E 64 20 4E 65 78 74 00
                    // "&Find Next"
00D8  00            // no extra data

// Eighth control
00D9  AE 00 15 00   // x, y
00DD  32 00 0E 00   // cx, cy
00E1  00 04         // wID
00E3  00 00 03 50   // dwStyle
00E7  80            // "button"
00E8  26 52 65 70 6C 61 63 65 00
                    // "&Replace"
00F1  00            // no extra data

// Ninth control
00F2  AE 00 26 00   // x, y
00F6  32 00 0E 00   // cx, cy
00FA  01 04         // wID
00FC  00 00 03 50   // dwStyle
0100  80            // "button"
0101  52 65 70 6C 61 63 65 20 26 41 6C 6C 00
                    // "Replace &All"
010E  00            // no extra data

// Tenth control
010F  AE 00 37 00   // x, y
0113  32 00 0E 00   // cx, cy
0117  02 00         // wID
0119  00 00 03 50   // dwStyle
011D  80            // "button"
011E  43 61 6E 63 65 6C 00
                    // "Cancel"
0125  00            // no extra data

// Eleventh control
0126  AE 00 4B 00   // x, y
012A  32 00 0E 00   // cx, cy
012E  0E 04         // wID
0130  00 00 03 50   // dwStyle
0134  80            // "button"
0135  26 48 65 6C 70 00
                    // "&Help"
013B  00            // no extra data

And that's the dialog template. We can now reconstruct the resource compiler source code from this template:

DIALOG 36, 44, 230, 94
STYLE WS_POPUP | WS_CAPTION | WS_SYSMENU | DS_MODALFRAME | NOT WS_VISIBLE
CAPTION "Replace"
FONT 8, "Helv"
BEGIN
    CONTROL "Fi&nd What:", -1, "static", SS_LEFT,
            4, 9, 48, 8

    CONTROL "", 0x0480, "edit",
            WS_BORDER | WS_GROUP | WS_TABSTOP | ES_AUTOHSCROLL,
            54, 7, 114, 12

    CONTROL "Re&place With:", -1, "static", SS_LEFT,
            4, 26, 48, 8

    CONTROL "", 0x0481, "edit",
            WS_BORDER | WS_GROUP | WS_TABSTOP | ES_AUTOHSCROLL,
            54, 24, 114, 12

    CONTROL "Match &Whole Word Only", 0x0410, "button",
            WS_GROUP | WS_TABSTOP | BS_AUTOCHECKBOX,
            5, 46, 104, 12

    CONTROL "Match &Case", 0x0411, "button",
            WS_TABSTOP | BS_AUTOCHECKBOX,
            5, 62, 59, 12

    CONTROL "&Find Next", IDOK, "button",
            WS_GROUP | WS_TABSTOP | BS_DEFPUSHBUTTON,
            174, 4, 50, 14

    CONTROL "&Replace", 0x0400, "button",
            WS_GROUP | WS_TABSTOP | BS_PUSHBUTTON,
            174, 21, 50, 14

    CONTROL "Replace &All", 0x0401, "button",
            WS_GROUP | WS_TABSTOP | BS_PUSHBUTTON,
            174, 38, 50, 14

    CONTROL "Cancel", IDCANCEL, "button",
            WS_GROUP | WS_TABSTOP | BS_PUSHBUTTON,
            174, 55, 50, 14

    CONTROL "Cancel", 0x040E, "button",
            WS_GROUP | WS_TABSTOP | BS_PUSHBUTTON,
            174, 75, 50, 14
END

Notice that we didn't explicitly say "DS_SETFONT" in the dialog's STYLE directive since that is implied by the "FONT" directive. And since WS_VISIBLE is on by default, we didn't have to say it; rather we had to explicitly refute it in the places it wasn't wanted.

Now if you take a look in your SDK header files, you'll find dlgs.h and findtext.dlg which pretty much match up with the template above, giving names to the magic values like 0x0400 and positioning the controls in the same place as above. You'll find some minor differences, though, since the header files in the SDK are for the 32-bit Find/Replace dialog and the one above is the 16-bit Find/Replace dialog, but you'll see that it still matches up pretty well.

Next time: The 32-bit DIALOG template.