Common Dialog Tutorial

Note: There is no sample program for this tutorial since basically this tutorial teaches you how to call the functions properly.

showMessageBox()

This function is used to display a popup box to show some kind of textual data. The style and the user's selection determines its return value. The simplest way to use a message box is like the following:

showMessageBox( &com, "This is a string" );

This will show a small popup box that displays "This is a string", a captionless title bar, and a "Ok" button. You can add a caption by specifiying a string in the third parameter. To ask the user a question you must specify one of the following in the fourth parameter:

• MB_ABORTRETRYIGNORE
• MB_OKCANCEL
• MB_RETRYCANCEL
• MB_YESNO
• MB_YESNOCANCEL
• MB_OK

To get information about further styles and the return values look under MessageBox in MSDN®.

showErrorDlg()

This function is simply a covinence method of ShowMessageBox() specifically aimed at showing error messages. It shows a message box with a MB_ICONERROR icon, and a MB_OK button. Other than these specifying these default styles it works just the same as showMessageBox().

showOpenFileDlg() and showSaveFileDlg()

These are propably the most complicated functions in the library. They are exactly the same except that the first displays an "Open" dialog and the latter shows a "Save" dialog. For brevity I will refer only to the ShowOpenFileDlg function, since they are semantically the same. The simplest way to display an open dialog is the following:

char* filename = showOpenFileDlg( &parent );

This should show an open file dialog whose current directory is "My Documents". It returns the filename that the user selected. To set a default directory put second parameter:

char* filename = showOpenFileDlg( &parent, "C:\Temp" );

This brings us to the most complicated portion of file dialogs and that is filters. Filters are those things in the combo box at the bottom of the dialog that automatically displays only the files with a certain extension. To create a filter you have to create a null terminated list like this:

char* filter = "C++ Source Files\0*.CPP\0C/C++ Header Files/0*.H\0All Files (*.*)\0";

The first thing you notice is all those null characters hanging around in the middle of the string. Don't blame me for this wierd system, this is part of the Windows® specification. The combo box would display "C++ Source Files", "C/C++ Header Files", and "All Files (*.*)". Now it is important to notice that the extension information is not displayed unless it is part of the description like it is for "All Files". Next notice that the extension part all follows the same format, which is an asterisk, dot, all caps extention. Your extension part should follow the same format. Next you can specify the index of the default filter in the fourth parameter. The last parameter should most often be ignored but information about valid flags can be found under OPENFILENAME in MSDN®. So puting it all together we get:

char* filter = "C++ Source Files\0*.CPP\0C/C++ Header Files/0*.H\0All Files (*.*)\0";
char* filename = showOpenFileDlg( &parent, "C:\Temp", filter, 2 );

This would show an open dialog whose default directory is "Temp" and whose default file filter is "*.H".