The evolution of dialog templates – 16-bit Classic Templates
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.
Light
Dark
0 comments