windows_programming_notes.nbk: Home | Index | Next Page: DM_GETDEFID | Previous Page: DLGITEMTEMPLATE

 DLGTEMPLATE

The DLGTEMPLATE structure defines the dimensions and style of a dialog box. This structure, always the first in a standard template for a dialog box, also specifies the number of controls in the dialog box and therefore specifies the number of subsequent DLGITEMTEMPLATE structures in the template.

Syntax

    typedef struct {
        DWORD style;
        DWORD dwExtendedStyle;
        WORD  cdit;
        short x;
        short y;
        short cx;
        short cy;
    } DLGTEMPLATE, *LPDLGTEMPLATE;

Members

• style
  Specifies the style of the dialog box. This member can be a combination of window style values (such as WS_CAPTION and WS_SYSMENU) and dialog box style values (such as DS_CENTER). For a list of window styles, see CreateWindow. For a list of dialog box styles, see Dialog Box Templates. If the style member includes the DS_SETFONT style, the header of the dialog box template contains additional data specifying the font to use for text in the client area and controls of the dialog box. The font data begins on the WORD boundary that follows the title array. The font data specifies a 16-bit point size value and a Unicode font name string. If possible, the system creates a font according to the specified values. Then the system sends a WM_SETFONT message to the dialog box and to each control to provide a handle to the font. If DS_SETFONT is not specified, the dialog box template does not include the font data. Windows 2000/XP: The DS_SHELLFONT style is not supported in the DLGTEMPLATE header.
• dwExtendedStyle
  Specifies extended styles for a window. This member is not used to create dialog boxes, but applications that use dialog box templates can use it to create other types of windows.
• cdit
  Specifies the number of items in the dialog box.
• x
  Specifies the x-coordinate, in dialog box units, of the upper-left corner of the dialog box.
• y
  Specifies the y-coordinate, in dialog box units, of the upper-left corner of the dialog box.
• cx
  Specifies the width, in dialog box units, of the dialog box.
• cy
  Specifies the height, in dialog box units, of the dialog box.

Remarks

In a standard template for a dialog box, the DLGTEMPLATE structure is always immediately followed by three variable-length arrays that specify the menu, class, and title for the dialog box. When the DS_SETFONT style is specified, these arrays are also followed by a 16-bit value specifying point size and another variable-length array specifying a typeface name. Each array consists of one or more 16-bit elements. The menu, class, title, and font arrays must be aligned on WORD boundaries.

Immediately following the DLGTEMPLATE structure is a menu array that identifies a menu resource for the dialog box. If the first element of this array is 0x0000, the dialog box has no menu and the array has no other elements. If the first element is 0xFFFF, the array has one additional element that specifies the ordinal value of a menu resource in an executable file. If the first element has any other value, the system treats the array as a null-terminated Unicode string that specifies the name of a menu resource in an executable file.

Following the menu array is a class array that identifies the window class of the control. If the first element of the array is 0x0000, the system uses the predefined dialog box class for the dialog box and the array has no other elements. If the first element is 0xFFFF, the array has one additional element that specifies the ordinal value of a predefined system window class. If the first element has any other value, the system treats the array as a null-terminated Unicode string that specifies the name of a registered window class.

Following the class array is a title array that specifies a null-terminated Unicode string that contains the title of the dialog box. If the first element of this array is 0x0000, the dialog box has no title and the array has no other elements.

The 16-bit point size value and the typeface array follow the title array, but only if the style member specifies the DS_SETFONT style. The point size value specifies the point size of the font to use for the text in the dialog box and its controls. The typeface array is a null-terminated Unicode string specifying the name of the typeface for the font. When these values are specified, the system creates a font having the specified size and typeface (if possible) and sends a WM_SETFONT message to the dialog box procedure and the control window procedures as it creates the dialog box and controls.

Following the DLGTEMPLATE header in a standard dialog box template are one or more DLGITEMTEMPLATE structures that define the dimensions and style of the controls in the dialog box. The cdit member specifies the number of DLGITEMTEMPLATE structures in the template. These DLGITEMTEMPLATE structures must be aligned on DWORD boundaries.

If you specify character strings in the menu, class, title, or typeface arrays, you must use Unicode strings. To create code that works on both Microsoft Windows 95/98/Me and Windows NT/2000/XP, use the MultiByteToWideChar function to generate these Unicode strings.

The x, y, cx, and cy members specify values in dialog box units. You can convert these values to screen units (pixels) by using the MapDialogRect function.

Structure Information

• Header Declared in Winuser.h, include Windows.h
• Minimum operating systems Windows 95, Windows NT 3.1

windows_programming_notes.nbk: Home | Index | Next Page: DM_GETDEFID | Previous Page: DLGITEMTEMPLATE

Notebook exported on Monday, 7 July 2008, 18:56:50 PM Eastern Daylight Time