Download Dialog Box Templates-Windows Programming-Lecture Notes and more Study notes Windows Programming in PDF only on Docsity!
20.1 Dialog Box Templates
A dialog box template is binary data that describes the dialog box, defining its height, width, style, and the controls it contains. To create a dialog box, the system either loads a dialog box template from the resources in the application's executable file or uses the template passed to it in global memory by the application. In either case, the application must supply a template when creating a dialog box.
A developer creates template resources by using a resource compiler or a dialog box editor. A resource compiler converts a text description into a binary resource, and a dialog box editor saves an interactively constructed dialog box as a binary resource.
To create a dialog box without using template resources, you must create a template in memory and pass it to the CreateDialogIndirectParam or DialogBoxIndirectParam function, or to the CreateDialogIndirect or DialogBoxIndirect macro.
A dialog box template in memory consists of a header that describes the dialog box, followed by one or more additional blocks of data that describe each of the controls in the dialog box. The template can use either the standard format or the extended format. In a standard template, the header is a DLGTEMPLATE structure followed by additional variable-length arrays; and the data for each control consists of a DLGITEMTEMPLATE structure followed by additional variable-length arrays. In an extended dialog box template, the header uses the DLGTEMPLATEEX format and the control definitions use the DLGITEMTEMPLATEEX format.
You can create a memory template by allocating a global memory object and filling it with the standard or extended header and control definitions. A memory template is identical in form and content to a template resource. Many applications that use memory templates first use the LoadResource function to load a template resource into memory, and then modify the loaded resource to create a new memory template.
20.1.1 Dialog Box Templates Styles
Every dialog box template specifies a combination of style values that define the appearance and features of the dialog box. The style values can be window styles, such as WS_POPUP and WS_SYSMENU, and dialog box styles, such as DS_MODALFRAME. The number and type of styles for a template depends on the type and purpose of the dialog box.
The system passes all window styles specified in the template to the CreateWindowEx function when creating the dialog box. The system may pass one or more extended styles depending on the specified dialog box styles. For example, when the template specifies DS_MODALFRAME, the system uses WS_EX_DLGMODALFRAME when creating the dialog box.
Most dialog boxes are pop-up windows that have a window menu and a title bar. Therefore, the typical template specifies the WS_POPUP, WS_SYSMENU, and WS_CAPTION styles. The template also specifies a border style: WS_BORDER for modeless dialog boxes and DS_MODALFRAME for modal dialog boxes. A template may specify a window type other than pop-up (such as WS_OVERLAPPED) if it creates a customized window instead of a dialog box.
The system always displays a modal dialog box regardless of whether the WS_VISIBLE style is specified. When the template for a modeless dialog box specifies the WS_VISIBLE style, the system automatically displays the dialog box when it is created. Otherwise, the application is responsible for displaying the dialog box by using the ShowWindow function.
The following table lists the dialog box styles that you can specify when you create a dialog box. You can use these styles in calls to the CreateWindow and CreateWindowEx functions, in the style member of the DLGTEMPLATE and DLGTEMPLATEEX structures, and in the statement of a dialog box definition in a resource file.
Value Meaning
DS_3DLOOK
Gives the dialog box a nonbold font, and draws three- dimensional borders around control windows in the dialog box.
The DS_3DLOOK style is required only by applications compiled for Windows NT 3.51. The system automatically applies the three-dimensional look to dialog boxes created by applications compiled for Windows 95/98/Me and later versions of Windows NT.
DS_ABSALIGN
Indicates that the coordinates of the dialog box are screen coordinates. If this style is not specified, the coordinates are client coordinates.
DS_CENTER
Centers the dialog box in the working area of the monitor that contains the owner window. If no owner window is specified, the dialog box is centered in the working area of a monitor determined by the system. The working area is the area not obscured by the taskbar or any application bars.
DS_CENTERMOUSE Centers the dialog box on the mouse cursor.
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, which should call the function using the HELP_WM_HELP command. The help application displays a pop-up window that typically contains help for the control.
the user regardless of whether the owner window is the foreground window.
DS_SHELLFONT
Indicates that the dialog box should use the system font. The typeface member of the extended dialog box template must be set to MS Shell Dialog. Otherwise, this style has no effect. It is also recommended that you use the DIALOGEX Resource, rather than the DIALOG Resource.
The system selects a font using the font data specified in the pointsize , weight , and italic members. The system passes a handle to the font to the dialog box and to each control by sending them the WM_SETFONT message. For descriptions of the format of this font data, see DLGTEMPLATEEX.
If neither DS_SHELLFONT nor DS_SETFONT is specified, the extended dialog box template does not include the font data.
DS_SYSMODAL
This style is obsolete and is included for compatibility with 16- bit versions of Windows. If you specify this style, the system creates the dialog box with the WS_EX_TOPMOST style. This style does not prevent the user from accessing other windows on the desktop.
Do not combine this style with the DS_CONTROL style.
20.1.2 Dialog Box Measurements
Every dialog box template contains measurements that specify the position, width, and height of the dialog box and the controls it contains. These measurements are device independent, so an application can use a single template to create the same dialog box for all types of display devices. This ensures that a dialog box will have the same proportions and appearance on all screens despite differing resolutions and aspect ratios between screens.
The measurements in a dialog box template are specified in dialog template units. To convert measurements from dialog template units to screen units (pixels), use the MapDialogRect function, which takes into account the font used by the dialog box and correctly converts a rectangle from dialog template units into pixels. For dialog boxes that use the system font, you can use the GetDialogBaseUnits function to perform the conversion calculations yourself, although using MapDialogRect is simpler.
The template must specify the initial coordinates of the upper left corner of the dialog box. Usually the coordinates are relative to the upper left corner of the owner window's client area. When the template specifies the DS_ABSALIGN style or the dialog box has
no owner, the position is relative to the upper left corner of the screen. The system sets this initial position when creating the dialog box, but permits an application to adjust the position before displaying the dialog box. For example, an application can retrieve the dimensions of the owner window, calculate a new position that centers the dialog box in the owner window, and then set the position by using the SetWindowPos function.
The template should specify a dialog box width and height that does not exceed the width and height of the screen and ensures that all controls are within the client area of the dialog box. Although the system permits a dialog box to be any size, creating one that is too small or too large can prevent the user from providing input, defeating the purpose of the dialog box. Many applications use more than one dialog box when there are a large number of controls. In such cases, the initial dialog box usually contains one or more buttons that the user can choose to display the next dialog box.
20.1.3 Dialog Box Controls
The template specifies the position, width, height, style, identifier, and window class for each control in the dialog box. The system creates each control by passing this data to the CreateWindowEx function. Controls are created in the order they are specified in the template. The template should specify the appropriate number, type, and order of controls to ensure that the user can enter the input needed to complete the task associated with the dialog box.
For each control, the template specifies style values that define the appearance and operation of the control. Every control is a child window and therefore must have the WS_CHILD style. To ensure that the control is visible when the dialog box is displayed, each control must also have the WS_VISIBLE style. Other commonly used window styles are WS_BORDER for controls that have optional borders, WS_DISABLED for controls that should be disabled when the dialog box is initially created, and WS_TABSTOP and WS_GROUP for controls that can be accessed using the keyboard. The WS_TABSTOP and WS_GROUP styles are used in conjunction with the dialog keyboard interface described later in this topic.
The template may also specify control styles specific to the control's window class. For example, a template that specifies a button control must give a button control style such as BS_PUSHBUTTON or BS_CHECKBOX. The system passes the control styles to the control window procedure through the WM_CREATE message, allowing the procedure to adapt the appearance and operation of the control.
The system converts the position coordinates and the width and height measurements from dialog base units to pixels, before passing these to CreateWindowEx. When the system creates a control, it specifies the dialog box as the parent window. This means the system always interprets the position coordinates of the control as client coordinates, relative to the upper left corner of the dialog box's client area.
20.1.5 Dialog Box Fonts
The system uses the average character width of the dialog box font to calculate the position and dimensions of the dialog box. By default, the system draws all text in a dialog box using the SYSTEM_FONT font.
To specify a font for a dialog box other than the default, you must create the dialog box using a dialog box template. In a template resource, use the FONT Statement. In a dialog box template, set the DS_SETFONT or DS_SHELLFONT style and specify a point size and a typeface name. Even if a dialog box template specifies a font in this manner, the system always uses the system font for the dialog box title and dialog box menus.
When the dialog box has the DS_SETFONT or DS_SHELLFONT style, the system sends a WM_SETFONT message to the dialog box procedure and to each control as it creates the control. The dialog box procedure is responsible for saving the font handle passed with the WM_SETFONT message and selecting the handle into the display device context whenever it writes text to the window. Predefined controls do this by default.
The system font can vary between different versions of Windows. To have your application use the system font no matter which system it is running on, use DS_SHELLFONT with the typeface MS Shell Dlg, and use the DIALOGEX Resource instead of the DIALOG Resource. The system maps this typeface such that your dialog box will use the Tahoma font on Windows 2000/Windows XP, and the MS Sans Serif font on earlier systems.
Note that DS_SHELLFONT has no effect if the typeface is not MS Shell Dlg.
20.1.6 Templates in Memory
A dialog box template in memory consists of a header that describes the dialog box, followed by one or more additional blocks of data that describe each of the controls in the dialog box. The template can use either the standard format or the extended format. In a standard template, the header is a DLGTEMPLATE structure followed by additional variable-length arrays. The data for each control consists of a DLGITEMTEMPLATE structure followed by additional variable-length arrays. In an extended dialog box template, the header uses the DLGTEMPLATEEX format and the control definitions use the DLGITEMTEMPLATEEX format.
To distinguish between a standard template and an extended template, check the first 16- bits of a dialog box template. In an extended template, the first WORD is 0xFFFF; any other value indicates a standard template.
If you create a dialog template in memory, you must ensure that the each of the DLGITEMTEMPLATE or DLGITEMTEMPLATEEX control definitions is aligned on DWORD boundaries. In addition, any creation data that follows a control definition
must be aligned on a DWORD boundary. All of the other variable-length arrays in a dialog box template must be aligned on WORD boundaries.
Template Header
In both the standard and extended templates for dialog boxes, the header includes the following general information:
- The location and dimensions of the dialog box
- The window and dialog box styles for the dialog box
- The number of controls in the dialog box. This value determines the number of DLGITEMTEMPLATE or DLGITEMTEMPLATEEX control definitions in the template.
- An optional menu resource for the dialog box. The template can indicate that the dialog box does not have a menu, or it can specify an ordinal value or null- terminated Unicode string that identifies a menu resource in an executable file.
- The window class of the dialog box. This can be either the predefined dialog box class, or an ordinal value or null-terminated Unicode string that identifies a registered window class.
- A null-terminated Unicode string that specifies the title for the dialog box window. If the string is empty, the title bar of the dialog box is blank. If the dialog box does not have the WS_CAPTION style, the system sets the title to the specified string but does not display it.
- If the dialog box has the DS_SETFONT style, the header specifies the point size and typeface name of the font to use for the text in the client area and controls of the dialog box.
In an extended template, the DLGTEMPLATEEX header also specifies the following additional information:
- The help context identifier of the dialog box window when the system sends a WM_HELP message.
- If the dialog box has the DS_SETFONT or DS_SHELLFONT style, the header specifies the font weight and indicates whether the font is italic.
Control Definitions
Following the template header is one or more control definitions that describe the controls of the dialog box. In both the standard and extended templates, the dialog box header has a member that indicates the number of control definitions in the template. In a standard template, each control definition consists of a DLGITEMTEMPLATE structure followed by additional variable-length arrays. In an extended template, the control definitions use the DLGITEMTEMPLATEEX format.
In both the standard and extended templates, the control definition includes the following information:
of the dialog box and the controls it contains. The developer can create this template as a resource to be loaded from the application's executable file, or created in memory while the application runs. The dialog box procedure is an application-defined callback function that the system calls when it has input for the dialog box or tasks for the dialog box to carry out. Although a dialog box procedure is similar to a window procedure, it does not have the same responsibilities.
An application typically creates a dialog box by using either the DialogBox or CreateDialog function. DialogBox creates a modal dialog box; CreateDialog creates a modeless dialog box. These two functions load a dialog box template from the application's executable file and create a pop-up window that matches the template's specifications. There are other functions that create a dialog box by using templates in memory; they pass additional information to the dialog box procedure as the dialog box is created.
Dialog boxes usually belong to a predefined, exclusive window class. The system uses this window class and its corresponding window procedure for both modal and modeless dialog boxes. When the function is called, it creates the window for the dialog box as well as the windows for the controls in the dialog box, and then sends selected messages to the dialog box procedure. While the dialog box is visible, the predefined window procedure manages all messages, processing some messages and passing others to the dialog box procedure so that the procedure can carry out tasks. Applications do not have direct access to the predefined window class or window procedure, but they can use the dialog box template and dialog box procedure to modify the style and behavior of a dialog box.
20.3 Dialog Box Owner window
Most dialog boxes have an owner window (or more simply, an owner). When creating the dialog box, the application sets the owner by specifying the owner's window handle. The system uses the owner to determine the position of the dialog box in the Z order so that the dialog box is always positioned above its owner. Also, the system can send messages to the window procedure of the owner, notifying it of events in the dialog box.
The system automatically hides or destroys the dialog box whenever its owner is hidden or destroyed. This means the dialog box procedure requires no special processing to detect changes to the state of the owner window.
Because the typical dialog box is used in conjunction with a menu item, the owner window is usually the window containing the menu. Although it is possible to create a dialog box that has no owner, it is not recommended. For example, when a modal dialog box has no owner, the system does not disable any of the application's other windows and allows the user to continue to carry out work in the other windows, defeating the purpose of the modal dialog box.
When a modeless dialog box has no owner, the system neither hides nor destroys the dialog box when other windows in the application are hidden or destroyed. Although this does not defeat the purpose of the modeless dialog box, it requires that the application carry out special processing to ensure the dialog box is hidden and destroyed at appropriate times.
20.4 Creating Modal Dialog
The DialogBoxParam function creates a modal dialog box from a dialog box template resource. Before displaying the dialog box, the function passes an application-defined value to the dialog box procedure as the lParam parameter of the WM_INITDIALOG message. An application can use this value to initialize dialog box controls.
INT_PTR DialogBoxParam(
HINSTANCE hInstance , //handle to the istance LPCTSTR lpTemplateName , //name of the template/ HWND hWndParent , //parent handle if any/ DLGPROC lpDialogFunc , //dialog function procedure/ LPARAM _dwInitParam /initialize parameters*/_ );
hInstance: Handle to the module whose executable file contains the dialog box template.
lpTemplateName: Specifies the dialog box template. This parameter is either the pointer to a null-terminated character string that specifies the name of the dialog box template or an integer value that specifies the resource identifier of the dialog box template. If the parameter specifies a resource identifier, its high-order word must be zero and its low- order word must contain the identifier. You can use the MAKEINTRESOURCE macro to create this value.
hWndParent: Handle to the window that owns the dialog box.
lpDialogFunc: Pointer to the dialog box procedure. For more information about the dialog box procedure, see DialogProc.
dwInitParam: Specifies the value to pass to the dialog box in the lParam parameter of the WM_INITDIALOG message.
Return Value: If the function succeeds, the return value is the value of the nResult parameter specified in the call to the EndDialog function used to terminate the dialog box.
If the function fails because the hWndParent parameter is invalid, the return value is zero. The function returns zero in this case for compatibility with previous versions of
TRUE. Note that you must call SetWindowLong immediately before returning TRUE; doing so earlier may result in the DWL_MSGRESULT value being overwritten by a nested dialog box message.
You should use the dialog box procedure only if you use the dialog box class for the dialog box. This is the default class and is used when no explicit class is specified in the dialog box template. Although the dialog box procedure is similar to a window procedure, it must not call the DefWindowProc function to process unwanted messages. Unwanted messages are processed internally by the dialog box window procedure.
20.6 The WM_INITDIALOG Message
The WM_INITDIALOG message is sent to the dialog box procedure immediately before a dialog box is displayed. Dialog box procedures typically use this message to initialize controls and carry out any other initialization tasks that affect the appearance of the dialog box.
WM_INITDIALOG
WPARAM wParam
LPARAM lParam;
wParam Handle to the control to receive the default keyboard focus. The system assigns the default keyboard focus only if the dialog box procedure returns TRUE. lParam Specifies additional initialization data. This data is passed to the system as the lParam parameter in a call to the CreateDialogIndirectParam, CreateDialogParam, DialogBoxIndirectParam, or DialogBoxParam function used to create the dialog box. For property sheets, this parameter is a pointer to the PROPSHEETPAGE structure used to create the page. This parameter is zero if any other dialog box creation function is used.
Return Value:
The dialog box procedure should return TRUE to direct the system to set the keyboard focus to the control specified by wParam. Otherwise, it should return FALSE to prevent the system from setting the default keyboard focus.
The dialog box procedure should return the value directly. The DWL_MSGRESULT value set by the SetWindowLong function is ignored.
The control to receive the default keyboard focus is always the first control in the dialog box that is visible, not disabled, and that has the WS_TABSTOP style. When the dialog box procedure returns TRUE, the system checks the control to ensure that the procedure
has not disabled it. If it has been disabled, the system sets the keyboard focus to the next control that is visible, not disabled, and has the WS_TABSTOP.
An application can return FALSE only if it has set the keyboard focus to one of the controls of the dialog box.
20.7 Using Dialog Procedure
BOOL CALLBACK AboutAuthorDialog(HWND hDlg, UINT message, WPARAM wParam, LPARAM lParam) { switch(message) { case WM_INITDIALOG: return TRUE; case WM_COMMAND: switch(LOWORD(wParam)) { case IDOK: case IDCANCEL: EndDialog(hDlg, 0); return TRUE; } break; } return FALSE; }
20.8 Screen Shot of About Modal Dialog
hWnd: Handle to the window or control whose text is to be changed. lpString: Pointer to a null-terminated string to be used as the new title or control text.
Return Value:
If the function succeeds, the return value is nonzero.
If the target window is owned by the current process, SetWindowText causes a WM_SETTEXT message to be sent to the specified window or control. If the control is a list box control created with the WS_CAPTION style, however, SetWindowText sets the text for the control, not for the list box entries.
To set the text of a control in another process, send the WM_SETTEXT message directly instead of calling SetWindowText.
The SetWindowText function does not expand tab characters (ASCII code 0x09). Tab characters are displayed as vertical bar (|) characters.
20.9.3 Retrieve the identifier of the specified control
The GetDlgCtrlID function retrieves the identifier of the specified control.
int GetDlgCtrlID(
HWND hwndCtl /handle to the control whose id is required/ ); hwndCtl: Handle to the control.
Return Value
If the function succeeds, the return value is the identifier of the control.
GetDlgCtrlID accepts child window handles as well as handles of controls in dialog boxes. An application sets the identifier for a child window when it creates the window by assigning the identifier value to the hmenu parameter when calling the CreateWindow or CreateWindowEx function.
Although GetDlgCtrlID may return a value if hwndCtl is a handle to a top-level window, top-level windows cannot have identifiers and such a return value is never valid.
20.9.4 Retrieve the text associated with the specified control in Dialog
The GetDlgItemText function retrieves the title or text associated with a control in a dialog box.
UINT GetDlgItemText(
HWND hDlg , /handle to the dialog/ int nIDDlgItem , /id of the control / LPTSTR lpString , /text data/ int nMaxCount /maximum limit of the text/ );
hDlg: Handle to the dialog box that contains the control.
nIDDlgItem: Specifies the identifier of the control whose title or text is to be retrieved.
lpString: Pointer to the buffer to receive the title or text.
nMaxCount: Specifies the maximum length, in TCHARs , of the string to be copied to the buffer pointed to by lpString. If the length of the string, including the NULL character, exceeds the limit, the string is truncated.
Return Value:
If the function succeeds, the return value specifies the number of TCHARs copied to the buffer, not including the terminating NULL character.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
If the string is as long as or longer than the buffer, the buffer will contain the truncated string with a terminating NULL character.
The GetDlgItemText function sends a WM_GETTEXT message to the control.
For the ANSI version of the function, the number of TCHARs is the number of bytes; for the Unicode version, it is the number of characters.
20.9.5 Sends a message to the specified control in a dialog box
The SendDlgItemMessage function sends a message to the specified control in a dialog box.
20.9.6 Setting or getting text associated with a window or control
WM_GETTEXT
wParam, // number of characters to copy lParam // text buffer
Get Text Message retrieve the text associated with the window. This text could be a caption text on any window or the text displayed in edit controls.
WM_SETTEXT wParam, // not used; must be zero lParam // window-text string (LPCTSTR)
Set Text set the text in window.
GetWindowText() function internally sends a WM_GETTEXT message to get the text. SetWindowText() function internally sends a WM_SETTEXT message to set the text.
20.9.7 Set or retrieve current selection in an edit control
Setting or getting the current selection in an edit control we use two message EM_SETSEL and EM_GETSEL.
EM_SETSEL or EM_GETSEL wParam, // starting position lParam // ending position
20.10 Creating Modeless Dialog
In our previous lecture, we have studied Modeless dialogs. Here we will create the modeless dialogs. Modeless dialogs are created with CreateDialog function. HWND CreateDialog(
HINSTANCE hInstance , /handle to the instance/ LPCTSTR lpTemplate , /template name/ HWND hWndParent , /handle to the parent/ DLGPROC lpDialogFunc /dialog function/ );
hInstance: Handle to the module whose executable file contains the dialog box template.
lpTemplate: Specifies the dialog box template. This parameter is either the pointer to a null-terminated character string that specifies the name of the dialog box template or an integer value that specifies the resource identifier of the dialog box template. If the
parameter specifies a resource identifier, its high-order word must be zero and its low- order word must contain the identifier. You can use the MAKEINTRESOURCE macro to create this value. hWndParent: Handle to the window that owns the dialog box.
lpDialogFunc: Pointer to the dialog box procedure.
Return Value:
If the function succeeds, the return value is the handle to the dialog box. If the function fails, the return value is NULL. To get extended error information, call GetLastError.
The CreateDialog function uses the CreateWindowEx function to create the dialog box. CreateDialog, then sends a WM_INITDIALOG message (and a WM_SETFONT message if the template specifies the DS_SETFONT or DS_SHELLFONT style) to the dialog box procedure. The function displays the dialog box if the template specifies the WS_VISIBLE style. Finally, CreateDialog returns the window handle to the dialog box.
After CreateDialog returns, the application displays the dialog box (if it is not already displayed) by using the ShowWindow function. The application destroys the dialog box by using the DestroyWindow function. To support keyboard navigation and other dialog box functionality, the message loop for the dialog box must call the IsDialogMessage function.
20.10.1 Showing Modeless Dialog
Modeless dialogs are initially hidden unless their property of visibility is not set.
For showing Dialog we can use ShowWindow function, which can show any window created in Windows.
BOOL ShowWindow(
HWND hWnd , /handle to the window/ int nCmdShow /show style/ );
hWnd: Handle to the window. nCmdShow: Specifies how the window is to be shown. This parameter is ignored the first time an application calls ShowWindow , if the program that launched the application provides a STARTUPINFO structure. Otherwise, the first time ShowWindow is called, the value should be the value obtained by the WinMain function in its nCmdShow parameter. In subsequent calls, this parameter can be one of the following values.
SW_HIDE: Hides the window and activates another window.
