Download Dialog Box Templates and Common Dialogs in Windows and more Study notes Computer Engineering and Programming in PDF only on Docsity!
- Chapter
- 20.1 DIALOG BOX TEMPLATES
- 20.1.1 DIALOG BOX TEMPLATES S TYLES
- 20.1.2 DIALOG BOX M EASUREMENTS
- 20.1.3 DIALOG BOX CONTROLS
- 20.1.4 DIALOG BOX WINDOW M ENU
- 20.1.5 DIALOG BOX F ONTS
- 20.1.6 TEMPLATES IN M EMORY
- Template Header
- Control Definitions
- 20.2 WHEN TO USE A DIALOG BOX
- 20.3 DIALOG BOX OWNER WINDOW
- 20.4 CREATING M ODAL DIALOG
- 20.5 DIALOG P ROCEDURE
- 20.6 THE WM_INITDIALOG M ESSAGE
- 20.7 USING DIALOG P ROCEDURE
- 20.8 S CREEN S HOT OF ABOUT M ODAL DIALOG
- 20.9 DIALOG BOX M ESSAGES AND FUNCTIONS
- 20.9.1 RETRIEVE HANDLE OF THE CONTROL
- 20.9.2 S ET W INDOW TEXT
- 20.9.3 RETRIEVE THE IDENTIFIER OF THE SPECIFIED CONTROL
- 20.9.4 RETRIEVE THE TEXT ASSOCIATED WITH THE SPECIFIED CONTROL IN DIALOG
- 20.9.5 S ENDS A MESSAGE TO THE SPECIFIED CONTROL IN A DIALOG BOX
- 20.9.6 S ETTING OR GETTING TEXT ASSOCIATED WITH A WINDOW OR CONTROL
- 20.9.7 S ET OR RETRIEVE CURRENT SELECTION IN AN EDIT CONTROL
- 20.10 CREATING M ODELESS DIALOG
- 20.10.1 S HOWING MODELESS DIALOG
- 20.10.2 P ROCESSING DIALOG M ESSAGES
- 20.10.3 M ESSAGE L OOP TO DISPATCH MESSAGES TO A MODELESS DIALOG
- 20.11 WINDOWS C OMMON DIALOGS
- 20.11.1 OPEN F ILE DIALOG
- 20.11.2 CHOOSE F ONT DIALOG
- 20.11.3 CHOOSE COLOR DIALOG
- 20.11.4 P RINT DIALOG
- S UMMARY
- EXERCISES
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.
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_CONTROL
Creates a dialog box that works well as a child window of another dialog box, much like a page in a property sheet. This style allows the user to tab among the control windows of a child dialog box, use its accelerator keys, and so on.
DS_FIXEDSYS
Causes the dialog box to use the SYSTEM_FIXED_FONT instead of the default SYSTEM_FONT. This is a monospace font compatible with the System font in 16-bit versions of Windows earlier than 3.0.
DS_LOCALEDIT
Applies to 16-bit applications only. This style directs edit controls in the dialog box to allocate memory from the application's 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
Windows 95/98/Me: 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 (either standard or extended) contains additional data specifying the font to use for text in the client area and controls of the dialog box. If possible, the system selects a font according to the specified font data. 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 DLGTEMPLATE and DLGTEMPLATEEX.
If neither DS_SETFONT nor DS_SHELLFONT is specified, the dialog box template does not include the font data.
DS_SETFOREGROUND
Causes the system to use the SetForegroundWindow function to bring the dialog box to the foreground. This style is useful for modal dialog boxes that require immediate attention from
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
The template specifies the window class for each control. Typical dialog box contains controls belonging to the predefined control window classes such as the button and edit control window classes. In this case, the template specifies window classes by supplying the corresponding predefined atom values for the classes. When a dialog box contains a control belonging to a custom control window class, the template gives the name of that registered window class or the atom value currently associated with the name.
Each control in a dialog box must have a unique identifier to distinguish it from other controls. Controls send information to the dialog box procedure through WM_COMMAND messages, so the control identifiers are essential for the procedure to determine which control sent a specified message. The only exception to this rule is control identifiers for static controls. Static controls do not require unique identifiers because they send no WM_COMMAND messages.
To permit the user to close the dialog box, the template should specify at least one push button and give it the control identifier IDCANCEL. To permit the user to choose between completing or canceling the task associated with the dialog box, the template should specify two push buttons, labeled OK and Cancel , with control identifiers of IDOK and IDCANCEL, respectively.
A template also specifies optional text and creation data for a control. The text typically provides labels for button controls or specifies the initial content of a static text control. The creation data is one or more bytes of data that the system passes to the control window procedure when creating the control. Creation data is useful for controls that require more information about their initial content or style than is specified by other data. For example, an application can use creation data to set the initial setting and range for a scroll bar control.
20.1.4 Dialog Box Window Menu
The system gives a dialog box a window menu when the template specifies the WS_SYSMENU style. To prevent inappropriate input, the system automatically disables all items in the menu except Move and Close. The user can click Move to move the dialog box. When the user clicks Close , the system sends a WM_COMMAND message to the dialog box procedure with the wParam parameter set to IDCANCEL. This is identical to the message sent by the Cancel button when the user clicks it. The recommended action for this message is to close the dialog box and cancel the requested task.
Although other menus in dialog boxes are not recommended, a dialog box template can specify a menu by supplying the identifier or the name of a menu resource. In this case, the system loads the resource and creates the menu for the dialog box. Applications typically use menu identifiers or names in templates when using the templates to create custom windows rather than dialog boxes.
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
- The location and dimensions of the control.
- The window and control styles for the control.
- The control identifier.
- The window class of the control. This can be either the ordinal value of a predefined system class or a null-terminated Unicode string that specifies the name of a registered window class.
- A null-terminated Unicode string that specifies the initial text of the control, or an ordinal value that identifies a resource, such as an icon, in an executable file.
- An optional variable-length block of creation data. When the system creates the control, it passes a pointer to this data in the lParam parameter of the WM_CREATE message that it sends to the control.
In an extended template, the control definition also specifies a help context identifier for the control when the system sends a WM_HELP message.
20.2 When to Use a DialogBox
Most applications use dialog boxes to prompt for additional information for menu items that require user input. Using a dialog box is the only recommended way for an application to retrieve the input. For example, a typical Open menu item requires the name of a file to open, so an application should use a dialog box to prompt the user for the name. In such cases, the application creates the dialog box when the user clicks the menu item and destroys the dialog box immediately after the user supplies the information.
Many applications also use dialog boxes to display information or options while the user works in another window. For example, word processing applications often use a dialog box with a text-search option. While the application searches for the text, the dialog box remains on the screen. The user can then return to the dialog box and search for the same word again; or the user can change the entry in the dialog box and search for a new word. Applications that use dialog boxes in this way typically create one when the user clicks the menu item and continue to display it for as long as the application runs or until the user explicitly closes the dialog box.
To support the different ways applications use dialog boxes, there are two types of dialog box: modal and modeless. A modal dialog box requires the user to supply information or cancel the dialog box before allowing the application to continue. Applications use modal dialog boxes in conjunction with menu items that require additional information before they can proceed. A modeless dialog box allows the user to supply information and return to the previous task without closing the dialog box. Modal dialog boxes are simpler to manage than modeless dialog boxes because they are created, perform their task, and are destroyed by calling a single function.
To create either a modal or modeless dialog box, an application must supply a dialog box template to describe the dialog box style and content; the application must also supply a dialog box procedure to carry out tasks. The dialog box template is a binary description
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.
Microsoft® Windows®. If the function fails for any other reason, the return value is –1. To get extended error information, call GetLastError.
The DialogBoxParam function uses the CreateWindowEx function to create the dialog box. DialogBoxParam 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 (regardless of whether the template specifies the WS_VISIBLE style), disables the owner window, and starts its own message loop to retrieve and dispatch messages for the dialog box.
When the dialog box procedure calls the EndDialog function, DialogBoxParam destroys the dialog box, ends the message loop, enables the owner window (if previously enabled), and returns the nResult parameter specified by the dialog box procedure when it called EndDialog.
20.5 Dialog Procedure
The DialogProc function is an application-defined callback function used with the CreateDialog and DialogBox families of functions. It processes messages sent to a modal or modeless dialog box. The DLGPROC type defines a pointer to this callback function. DialogProc is a placeholder for the application-defined function name.
INT_PTR CALLBACK DialogProc(
HWND hwndDlg , //handle to the dialog UINT uMsg , //message structure WPARAM wParam , //wParam LPARAM lParam //lParam );
hwndDlg: Handle to the dialog box.
uMsg: Specifies the message.
wParam: Specifies additional message-specific information.
lParam: Specifies additional message-specific information.
Return Value: Typically, the dialog box procedure should return TRUE if it processed the message, and FALSE if it did not. If the dialog box procedure returns FALSE, the dialog manager performs the default dialog operation in response to the message.
If the dialog box procedure processes a message that requires a specific return value, the dialog box procedure should set the desired return value by calling SetWindowLong( hwndDlg , DWL_MSGRESULT, lResult ) immediately before returning
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
20.9 Dialog Box Messages and functions
Following are the description of dialog box functions.
20.9.1 Retrieve handle of the control
The GetDlgItem function retrieves a handle to a control in the specified dialog box.
HWND GetDlgItem(
HWND hDlg , int nIDDlgItem );
hDlg [in] Handle to the dialog box that contains the control. nIDDlgItem [in] Specifies the identifier of the control to be retrieved.
Return Value:
If the function succeeds, the return value is the window handle of the specified control. If the function fails, the return value is NULL, indicating an invalid dialog box handle or a nonexistent control. To get extended error information, call GetLastError.
You can use the GetDlgItem function with any parent-child window pair, not just with dialog boxes. As long as the hDlg parameter specifies a parent window and the child window has a unique identifier (as specified by the hMenu parameter in the CreateWindow or CreateWindowEx function that created the child window), GetDlgItem returns a valid handle to the child window.
20.9.2 Set Window Text
The SetWindowText function changes the text of the specified window's title bar (if it has one). If the specified window is a control, the text of the control is changed. However, SetWindowText cannot change the text of a control in another application.
BOOL SetWindowText(
HWND hWnd , LPCTSTR lpString
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.
LRESULT SendDlgItemMessage(
HWND hDlg , /handle to the dialog/ int nIDDlgItem , /id of the dialog item/ UINT Msg , /message type/ WPARAM wParam , /message wParam/ LPARAM lParam /message lParam/ );
hDlg: Handle to the dialog box that contains the control.
nIDDlgItem: Specifies the identifier of the control that receives the message.
Msg: Specifies the message to be sent.
wParam: Specifies additional message-specific information.
lParam: Specifies additional message-specific information.
Return Value:
The return value specifies the result of the message processing and depends on the message sent.
The SendDlgItemMessage function does not return until the message has been processed.
Using SendDlgItemMessage is identical to retrieving a handle to the specified control and calling the SendMessage function.
Example
In this example we send a message to edit control of EM_LIMITTEXT. This message will limit the text to the given number say 25 in our case. Edit control will not receive more than this limit.
EM_LIMITTEXT wParam, // text length lParam // not used; must be zero //Sets the text limit of an edit control
//This message is sent by sendDlgItemMessage function. SendDlgItemMessage(hEdit, EM_LIMITTEXT, (WPARAM)25, (LPARAM)0);
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
