DLGTEMPLATE

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

typedef struct { // dltt 
DWORD style; 
DWORD dwExtendedStyle; 
WORD cdit; 
short x; 
short y; 
short cx; 
short cy; 
} DLGTEMPLATE; 

Members

• style
  Specifies the style of the dialog box. It can be a combination of window style values (such as WS_CAPTION and WS_SYSMENU) and one or more of the following dialog box style values:

  Value	Description
  DS_ABSALIGN	Indicates that the coordinates of the dialog box are screen coordinates. If this style is not specified, the system assumes they are client coordinates.
  DS_CENTER	Centers the dialog box in the working area; that is, the area not obscured by the tray
  DS_CENTERMOUSE	Centers the mouse cursor in the dialog box
  DS_CONTEXTHELP	Includes a question mark in the title bar of the dialog box. When the user clicks the question mark, the cursor changes to a question mark with a pointer. If the user then clicks a control in the dialog box, the control receives a WM_HELP message. The control should pass the message to the dialog box procedure. The help application displays a pop-up window that typically contains help for the control. Note that DS_CONTEXTHELP is only a placeholder. When the dialog box is created, the system checks for DS_CONTEXTHELP and, if it is there, adds WS_EX_CONTEXTHELP to the extended style of the dialog box. WS_EX_CONTEXTHELP cannot be used with the WS_MAXIMIZEBOX or WS_MINIMIZEBOX styles.
  DS_LOCALEDIT	Applies to 16-bit applications only. This style directs edit controls in the dialog box to allocate memory from the application data segment. Otherwise, edit controls allocate storage from a global memory object.
  DS_MODALFRAME	Creates a dialog box with a modal dialog-box frame that can be combined with a title bar and window menu by specifying the WS_CAPTION and WS_SYSMENU styles.
  DS_NOFAILCREATE	Creates the dialog box even if errors occur—for example, if a child window cannot be created or if the system cannot create a special data segment for an edit control.
  DS_NOIDLEMSG	Suppresses WM_ENTERIDLE messages that the system would otherwise send to the owner of the dialog box while the dialog box is displayed.
  DS_SETFONT	Indicates that 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. It 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 passes the handle of the font to the dialog box and to each control by sending them the WM_SETFONT message. If this style is not specified, the dialog box template does not include the font data. You cannot set the font inside dialog boxes in Windows CE versions 1.0 and 1.01, but you can in Windows CE versions 2.0 and later.
  DS_SETFOREGROUND	Causes the system to use the SetForegroundWindow function to bring the dialog box to the foreground.

• 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

To get default positioning, use the DS_CENTER style.

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 given, 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 given, the system creates a font having the given 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 Windows 95/98 and Windows NT, 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.

The following dwStyle flags are not supported for dialog boxes:

Requirements

Note   This API is part of the complete Windows CE OS package as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM) and some devices may not support this API.

See Also

CreateDialog, CreateDialogIndirect, CreateDialogIndirectParam, DialogBox, DialogBoxIndirect, DialogBoxIndirectParam, MapDialogRect, MultiByteToWideChar, SetForegroundWindow, WM_SETFONT, DLGITEMTEMPLATE

 Last updated on Tuesday, July 13, 2004

© 1992-2000 Microsoft Corporation. All rights reserved.