Using Common Dialog Boxes

This section covers tasks that invoke common dialog boxes:

Choosing a Color

This topic describes sample code that displays a Color dialog box so that a user can select a color. The sample code first initializes a CHOOSECOLOR structure, and then calls the ChooseColor function to display the dialog box. If the function returns TRUE, indicating that the user selected a color, the sample code uses the selected color to create a new solid brush.

This example uses the CHOOSECOLOR structure to initialize the dialog box as follows:

• Initializes the lpCustColors member with a pointer to a static array of values. The colors in the array are initially black, but the static array preserves custom colors created by the user for subsequent ChooseColor calls.
• Sets the CC_RGBINIT flag and initializes the rgbResult member to specify the color that is initially selected when the dialog box opens. If not specified, the initial selection is black. The example uses the rgbCurrent static variable to preserve the selected value between calls to ChooseColor.
• Sets the CC_FULLOPEN flag so the custom colors extension of the dialog box is always displayed.

Choosing a Font

This topic describes sample code that displays a Font dialog box so that a user can choose the attributes of a font. The sample code first initializes a CHOOSEFONT structure, and then calls the ChooseFont function to display the dialog box.

This example sets the CF_SCREENFONTS flag to specify that the dialog box should display only screen fonts. It sets the CF_EFFECTS flag to display controls that allow the user to select strikeout, underline, and color options.

If ChooseFont returns TRUE, indicating that the user clicked the OK button, the CHOOSEFONT structure contains information that describes the font and font attributes selected by the user, including the members of the LOGFONT structure pointed to by the lpLogFont member. The rgbColors member contains the selected text color. The sample code uses this information to set the font and text color for the device context associated with the owner window.

Opening a File

Starting with WindowsВ Vista, the Common File Dialog has been superseded by the Common Item Dialog when used to open a file. We recommend that you use the Common Item Dialog API instead of the Common File Dialog API. For more information, see Common Item Dialog.

This topic describes sample code that displays an Open dialog box so that a user can specify the drive, directory, and name of a file to open. The sample code first initializes an OPENFILENAME structure, and then calls the GetOpenFileName function to display the dialog box.

In this example, the lpstrFilter member is a pointer to a buffer that specifies two file name filters that the user can select to limit the file names that are displayed. The buffer contains a double-null terminated array of strings in which each pair of strings specifies a filter. The nFilterIndex member specifies that the first pattern is used when the dialog box is created.

This example sets the OFN_PATHMUSTEXIST and OFN_FILEMUSTEXIST flags in the Flags member. These flags cause the dialog box to verify, before returning, that the path and file name specified by the user actually exist.

The GetOpenFileName function returns TRUE if the user clicks the OK button and the specified path and file name exist. In this case, the buffer pointed to by the lpstrFile member contains the path and file name. The sample code uses this information in a call to the function to open the file.

Although this example does not set the OFN_EXPLORER flag, it still displays the default Explorer-style Open dialog box. However, if you want to provide a hook procedure or a custom template and you want the Explorer user interface, you must set the OFN_EXPLORER flag.

In the C programming language, a string enclosed in quotation marks is null-terminated.

Displaying the Print Dialog Box

This topic describes sample code that displays a Print dialog box so that a user can select options for printing a document. The sample code first initializes a PRINTDLG structure, and then calls the PrintDlg function to display the dialog box.

This example sets the PD_RETURNDC flag in the Flags member of the PRINTDLG structure. This causes PrintDlg to return a device context handle to the selected printer in the hDC member. You can use the handle to render output on the printer.

On input, the sample code sets the hDevMode and hDevNames members to NULL. If the function returns TRUE, these members return handles to DEVNAMES structures that contain the user input and information about the printer. You can use this information to prepare the output to be sent to the selected printer.

Using the Print Property Sheet

This topic describes sample code that displays a Print property sheet so that a user can select options for printing a document. The sample code first initializes a PRINTDLGEX structure, then calls the PrintDlgEx function to display the property sheet.

The sample code sets the PD_RETURNDC flag in the Flags member of the PRINTDLG structure. This causes the PrintDlgEx function to return a device context handle to the selected printer in the hDC member.

On input, the sample code sets the hDevMode and hDevNames members to NULL. If the function returns S_OK, these members return handles to DEVNAMES structures containing the user input and information about the printer. You can use this information to prepare the output to be sent to the selected printer.

After the printing operation has been completed, the sample code frees the DEVMODE, DEVNAMES, and PRINTPAGERANGE buffers and calls the DeleteDC function to delete the device context.

Setting Up the Printed Page

This topic describes sample code that displays a Page Setup dialog box so that a user can select the attributes of the printed page, such as the paper type, paper source, page orientation, and page margins. The sample code first initializes a PAGESETUPDLG structure, and then calls the PageSetupDlg function to display the dialog box.

This example sets the PSD_MARGINS flag in the Flags member and uses the rtMargin member to specify the initial margin values. It sets the PSD_INTHOUSANDTHSOFINCHES flag to ensure that the dialog box expresses margin dimensions in thousandths of an inch.

On input, the sample code sets the hDevMode and hDevNames members to NULL. If the function returns TRUE, the function uses these members to return handles to DEVNAMES structures containing the user input and information about the printer. You can use this information to prepare the output to be sent to the selected printer.

The following example also enables a PagePaintHook hook procedure to customize drawing the contents of the sample page.

The following example shows a sample PagePaintHook hook procedure that draws the margin rectangle in the sample page area:

Finding Text

This topic describes sample code that displays and manages a Find dialog box so that the user can specify the parameters of a search operation. The dialog box sends messages to the window procedure so you can perform the search operation.

The code for displaying and managing a Replace dialog box is similar, except that it uses the ReplaceText function to display the dialog box. The Replace dialog box also sends messages in response to user clicks on the Replace and Replace All buttons.

To use the Find or Replace dialog box, you must perform three separate tasks:

1. Get a message identifier for the FINDMSGSTRING registered message.
2. Display the dialog box.
3. Process FINDMSGSTRING messages when the dialog box is open.

When you initialize your application, call the RegisterWindowMessage function to get a message identifier for the FINDMSGSTRING registered message.

To display a Find dialog box, first initialize a FINDREPLACE structure and then call the FindText function. Note that the FINDREPLACE structure and the buffer for the search string should be a global or static variable so that it does not go out of scope before the dialog box closes. You must set the hwndOwner member to specify the window that receives the registered messages. After you create the dialog box, you can move or manipulate it by using the returned handle.

When the dialog box is open, your main message loop must include a call to the IsDialogMessage function. Pass a handle to the dialog box as a parameter in the IsDialogMessage call. This ensures that the dialog box correctly processes keyboard messages.

To monitor messages sent from the dialog box, your window procedure must check for the FINDMSGSTRING registered message and process the values passed in the FINDREPLACE structure as in the following example.

Windows Programming/Dialog Boxes

People are familiar with dialog boxes. They are the grey windows that pop up on Windows systems to display messages, and allow the user to set parameters. There are 3 types of dialog boxes: modeless, modal, and system modal.

Modal Modal dialog boxes are generally used inside a program, to display messages, and to set program parameters. Modal dialog boxes come to the front of the screen, and you may not use the program while the modal dialog box is open. to continue using the program, the modal dialog box must be closed. System Modal System modal dialog boxes are like modal boxes, except that they supersede the entire desktop area. When a system modal dialog box is open, nothing else on the screen can be clicked or selected. Modeless Modeless dialog boxes are able to be deselected, and control can be taken away from a modeless dialog box and transferred to some other window. Modeless dialog boxes are frequently used as a fast and easy way to create a window, without having to register a window class. Modeless dialog boxes are common in the Windows control panel.

Contents

MessageBox [ edit | edit source ]

The most simple type of dialog box is the MessageBox function. The MessageBox function takes 5 parameters: a handle to a parent, a message, a title, and an option. If the parent handle is NULL, the message box is modeless. If you provide a handle for a parent window, the MessageBox can become Modal to the parent window.

MessageBox dialog boxes have a number of different options that can be specified: Button types, Icons, modality (modal/modeless), and text justification. These options are specified as bit flags, that can be used by bitwise ORing them together.

Buttons [ edit | edit source ]

Message boxes can have standard OK or Cancel buttons, or they can have a «Yes, No, Cancel» configuration, or a number of derivatives. Only one primary button scheme can be used per message box:

• MB_ABORTRETRYIGNORE: The message box contains three push buttons: Abort, Retry, and Ignore.
• MB_CANCELTRYCONTINUE: Same as MB_ABORTRETRYIGNORE, but preferred on Windows 2000/XP.
• MB_OK: The message box contains an «OK» button. This is the default.
• MB_OKCANCEL: The message box contains two push buttons: OK and Cancel.
• MB_RETRYCANCEL: The message box contains two push buttons: Retry and Cancel.
• MB_YESNO: The message box contains two push buttons: Yes and No.
• MB_YESNOCANCEL: The message box contains three push buttons: Yes, No, and Cancel.

To display an icon in the message box, specify one of the following values. In addition, a message box can add an additional «Help» button by specifying the «MB_HELP» flag. A «Default Button», a concept that we will see frequently in this chapter, is the button that is automatically selected when a dialog box is opened. Windows provides the ability to set the default button to any of the buttons on a message box, by using the MB_DEFBUTTONx macro. Here is an example:

This will have a message box with an «OK», a «Cancel», and a «Help» button, and the «Cancel» button will be automatically selected.

Icons [ edit | edit source ]

A message box may have no icons, or it may have one. You shouldn’t specify a message box to have multiple icons. The different icons, according to MSDN are:

• MB_ICONEXCLAMATION: An exclamation point icon appears in the message box.
• MB_ICONWARNING: An exclamation point icon appears in the message box.
• MB_ICONINFORMATION: An icon consisting of a lowercase letter i in a circle appears in the message box.
• MB_ICONASTERISK: An icon consisting of a lowercase letter i in a circle appears in the message box.
• MB_ICONQUESTION: A question mark icon appears in the message box.
  The question mark message icon is no longer recommended because it does not clearly represent a specific type of message and because the phrasing of a message as a question could apply to any message type. In addition, users can confuse the message symbol question mark with Help information. Therefore, do not use this question mark message symbol in your message boxes. The system continues to support its inclusion only for backward compatibility.
• MB_ICONSTOP: A stop sign icon appears in the message box.
• MB_ICONERROR: A stop sign icon appears in the message box.
• MB_ICONHAND: A stop sign icon appears in the message box.

Modality [ edit | edit source ]

Finally, the MessageBox can be defined as being Modal, Modeless, or System Modal, by using another identifier: MB_APPLMODAL, MB_SYSTEMMODAL, or MB_TASKMODAL. MB_APPLMODAL is the default value, and only works if a parent window handle was specified to the function. There are a number of other options available, check out MSDN for more details.

Dialog Box Procedures [ edit | edit source ]

Dialog box procedures are slightly different from window procedures. Specifically, they return BOOL values, instead of LRESULT values. Also, dialog boxes do not have a default message processing function, because messages don’t always need to be handled. Specifically, Windows manages dialog boxes, and Windows will handle the unused messages. If a dialog box processes a certain message, it should return TRUE. If the message is not processed, the function should return FALSE. Also, Dialog boxes do not get a WM_CREATE message, but instead get a WM_INITDIALOG message. Furthermore, when a dialog box has finished its business, it should call the EndDialog function.

Here is an example of a skeleton dialog box function:

Creating Modal Dialog Boxes [ edit | edit source ]

Once a dialog box procedure has been defined, a dialog box can be created by calling either the DialogBox or DialogBoxParam function. These functions return an NRESULT value, that is the integer number passed to the EndDialog function in the dialog box procedure.

The DialogBox function will not return until the dialog box is closed. This means, essentially, that the program is frozen in time until we close the dialog box. The DialogBox function requires 2 handles: the module instance handle and the handle of the parent window. Also, the DialogBox function requires that a string be passed naming the resource where the dialog box is defined. The last argument to DialogBox is a pointer to the dialog box procedure function, that you have already defined.

To pass a parameter to a dialog box, the function DialogBoxParam can be used. DialogBoxParam has all the same parameters as the regular version, except it takes a fifth argument as a 32-bit pointer. This 32 bit value will be passed as the LPARAM element of the WM_INITDIALOG message.

Indirect Dialog Boxes [ edit | edit source ]

DialogBox and DialogBoxParam both require that the dialog box be defined in a resource. However, if you want to make the dialog box on the fly, you can use the DialogBoxIndirect or the DialogBoxIndirectParam functions. When defining a dialog box indirectly, we need to fill out a DLGTEMPLATE structure, and pass a pointer to that structure to the function, in place of a resource identifier. The DLGTEMPLATE contains fields for determining some of the characteristics of the dialog box, such as the dimensions and screen location.

The DLGITEMTEMPLATE structure is used to define individual dialog box items. For more information on this subject, search MSDN.

Creating Modeless Dialog Boxes [ edit | edit source ]

Modeless dialog boxes are a breed of a different color, and are more like windows than dialog boxes. First, we need to modify the message loop, to ensure that dialog box messages are routed correctly:

Now, there are 2 ways we can define a message box in a resource script, with a class or without. We will discuss each in turn.

Without Class [ edit | edit source ]

We can define a dialog box in a resource script with the DIALOG keyword. The resource will have an ID associated with it (either a number or a string), and this ID can be passed directly to the CreateDialog function.

With Class [ edit | edit source ]

If we want to define a modeless dialog box in terms of a window class, we can use a few additions to make the job easier. First, we create a WNDCLASS structure with the information about our dialog box. However, there is one difference, in that we must set the cbWndExtra field to the value DLGWINDOWEXTRA value:

Then, we register the class like normal. Since we are registering our window classes like normal windows, it shouldn’t come as a surprise that Modeless dialog boxes use a regular window procedure, and not a dialog box procedure. Now, Windows identifies classes by name, so we should remember the name of our class. Let’s say we named our class «MyDlgClass». We could create a dialog box resource as such:

Notice the field that says «CLASS»? This is the same string that we used in our WNDCLASS structure to name the class. It is important that these two strings be identical, because Windows needs this string to link the WNDCLASS and the dialog box resource together. Notice also that we used the string «MYDLGCLASS» to identify the dialog resource. This isn’t mandatory, but it does make things convenient later on.

Now, instead of calling CreateWindow, we will call the easier-to-use function CreateDialog. We do not use the DialogBox function, because CreateDialog returns immediately, and doesn’t halt program execution.

Here is an example:

Here, we are saying that «hInst» is the instance handle of the application, and «hwndParent» is the handle to the parent window of our dialog box. If the hwndParent parameter is NULL, the dialog box won’t have a parent. When the modeless dialog box is finished, it calls «DestroyWindow», not «EndDialog», like a modal dialog box would.

Common Dialog Boxes [ edit | edit source ]

The Common Dialogs is a library of functions that automatically produce some of the most common dialog boxes in Windows. This is an effort to make some amount of continuity between different programs, so that each different program doesn’t create its own proprietary «File Open» dialog, for instance.

Each Common Dialog generally has a single function that takes a pointer to a structure. This structure is defined specifically for each different control. The common controls can be added to a project by including the header file, and linking to the comdlg32.dll library.

Some of the common controls available through this library are the «Choose Font» dialog box, the «File open» and «File save» boxes, and the «Color Palette» dialog box.

ChooseColor [ edit | edit source ]

The ChooseColor function brings up the color palette window, and returns a 32-bit color value to your program.

ChooseColor takes a single argument, in the form of a pointer to a CHOOSECOLOR structure. This structure is initialized with various values, and when the function returns, the CHOOSECOLOR structure contains the color value code.

GetOpenFileName and GetSaveFileName [ edit | edit source ]

These two functions bring up the familiar file open and file save dialog boxes that are found in nearly every Windows application.

Both of these functions take a pointer to an OPENFILENAME structure. This structure controls such things as the file extensions that may be loaded, and the starting path to look in. When the function returns, the structure will contain the name of the file selected. Once your program has this information, you can use the File I/O API to access the file.

ChooseFont [ edit | edit source ]

The ChooseFont function brings up a familiar dialog box that allows the user to select a font and various font attributes such as size, underline/bold/italics, color, etc. This function takes a pointer to a CHOOSEFONT structure.

Dialog Box Resources [ edit | edit source ]

Dialog boxes can be specified in a resource script, to handle the tricky task of creating all the various child windows (buttons and editboxes, etc.) that a dialog box may contain. This process is described in detail in the Resource Script Reference in the appendix. Here, we will discuss some of the basics of using a resource script to define a dialog box.

The DIALOG keyword [ edit | edit source ]

A dialog box resource is specified with the DIALOG (must be all caps) keyword. The DIALOG keyword is preceded by the resource identifier, and is followed by a series of dimension values:

ID_DLGBOX DIALOG X, Y, CX, CY

X and Y are the location coordinates of the upper-left corner of the dialog box, in relation to the upper-left corner of the screen. Remember, all the coordinates start at (0,0) in the upper-left hand corner. The next set of numbers, CX and CY, are the dimensions of the dialog box. These dimensions do not include the title bar (if any), so setting your Y value to 0 will make a dialog box that is only a title bar.

After the DIALOG declaration, there are a number of other fields that can be filled in, to provide information about your dialog box:

The STYLE declaration contains all the window styles, bitwise OR’d, that you would have used in the WNDCLASS structure, or in the style field of the CreateWindow function. All the same values are available. The CAPTION is the title of the dialog box. The FONT is the point-size and the TrueType font to be used on all the surfaces of the dialog box. Any font and size can be specified, although if the font is too big, your dialog box will be very annoying.

Now, once we have our dialog box sized and shaped the way we want it, we can start to fill it with control buttons and edit boxes, and all sorts of other goodies. First, we use the BEGIN and END tags:

Next, we can start to fill in the dialog box with buttons, checkboxes, or whatever we want, using the following format:

After the declaration, you may optionally include one or more style flags, to specify how you want a particular control to appear. The WS_TABSTOP identifier specifies which controls can be selected when you press the TAB key on the keyboard. When you press the TAB key, control switches among the dialog box controls in the same order that they are specified in the resource script (top to bottom).