MSVC/MFC File Processing: The File Dialog Box

	Microsoft Visual C++/MFC File Processing: The File Dialog Box

The File Dialog

Introduction

One of the common dialog boxes provided by Microsoft Windows is for file processing. The File dialog box is used to open or save a file. In the MFC library, the File dialog box is implemented by a class named CFileDialog. The CFileDialog class is derived by the CCommonDialog class:

CFileDialog

The CFileDialog class is equipped with a constructor whose syntax is:

CFileDialog(BOOL bOpenFileDialog,
	   LPCTSTR lpszDefExt = NULL,
	   LPCTSTR lpszFileName = NULL,
	   DWORD dwFlags = OFN_HIDEREADONLY | OFN_OVERWRITEPROMPT,
	   LPCTSTR lpszFilter = NULL,
	   CWnd* pParentWnd = NULL );

The CFileDialog constructor requires one argument: the bOpenFileDialog.

File Saving

One of the operations you can allow a user to perform on a file is to save it, either after creating it or after saving it. If you want to save a file, pass the first argument of the CFileDialog constructor as FALSE. Here is an example:

void CExerciseDlg::OnBnClickedFileBtn()
{
	CFileDialog *dlg = new CFileDialog(FALSE);
}

File Opening

As opposed to saving a file, you can allow the user to open one of more files. To create a File dialog box that the user can use to open a file, pass the first argument of the CFileDialog constructor as TRUE. Here is an example:

void CExerciseDlg::OnBnClickedFileBtn()
{
	CFileDialog *dlg = new CFileDialog(TRUE);
}

File Dialog Properties

Introduction

There are various ways you can configure the File dialog box. Its constructor is equipped with many arguments and some arguments allow many options. As we will see, you can also use the Win32 to perform operations on the MFC's File dialog box.

The options on the File dialog box are referred to as flags. To support them, the dwFlags parameter of the CFileDialog constructor allows you to create a combination of options using the | operator.

The Win32 File Dialog Structure

The only member variable that the File Dialog has is called m_ofn. It is an object derived from a Win32 class (or structure) named OPENFILENAME. In fact, the MFC doesn't do miracles than the Win32 would. The MFC only provides some type of "translation" of the Win32 library on this issue.

The OPENFILENAME class is defined as follows:

typedef struct tagOFN { 
  DWORD         lStructSize; 
  HWND          hwndOwner; 
  HINSTANCE     hInstance; 
  LPCTSTR       lpstrFilter; 
  LPTSTR        lpstrCustomFilter; 
  DWORD         nMaxCustFilter; 
  DWORD         nFilterIndex; 
  LPTSTR        lpstrFile; 
  DWORD         nMaxFile; 
  LPTSTR        lpstrFileTitle; 
  DWORD         nMaxFileTitle; 
  LPCTSTR       lpstrInitialDir; 
  LPCTSTR       lpstrTitle; 
  DWORD         Flags; 
  WORD          nFileOffset; 
  WORD          nFileExtension; 
  LPCTSTR       lpstrDefExt; 
  LPARAM        lCustData; 
  LPOFNHOOKPROC lpfnHook; 
  LPCTSTR       lpTemplateName; 
#if (_WIN32_WINNT >= 0x0500)
  void *        pvReserved;
  DWORD         dwReserved;
  DWORD         FlagsEx;
#endif // (_WIN32_WINNT >= 0x0500)
} OPENFILENAME, *LPOPENFILENAME;

To use this structure, access the m_ofn member of the CFileDialog variable, then access the OPENFILENAME member you want and assign the desired value to it. This can be done as follows:

void CExerciseDlg::OnBnClickedFileBtn()
{
	CFileDialog *dlg = new CFileDialog(TRUE);

	dlg->m_ofn.Member = Value;
}

To let you get the OPENFILENAME object that the user is using, the CFileDialog class provides the GetOFN() member function. Its comes in two versions whoses syntaxes are:

const OPENFILENAME& GetOFN() const;
OPENFILENAME& GetOFN();

It is important to know that not all members behave as expected because there are changes, and there have been changes, in operating systems over the years.

Displaying the File Dialog Box

In order to use a File dialog box, the user must open it. This can be done by calling the CFileDialog::DoModal() member function. Its syntax is:

virtual INT_PTR DoModal( );

Here is an example of calling this member function:

void CExerciseDlg::OnBnClickedFileBtn()
{
	CFileDialog *dlg = new CFileDialog(TRUE);
	dlg->DoModal();
}

When it comes up, the File dialog displays two buttons regularly available on a normal dialog box. If the file is being opened, the buttons are Open and Cancel. If the user is saving a file, the buttons are Save and Cancel. In both cases, the compiler system automatically specifies the buttons based on the first argument you passed to the CFileDialog copnstructor.

After using the dialog box, either to open or to save a file, the user can click Open/Save or Cancel. If the user clicks Open or Save, the dialog box is (partly) equipped to validate the operation. For example, if the user clicks Open, the dialog box is configured to make sure that the user selected a file. If the user clicks Save, he or she should have given a name to the file.

To dismiss the dialog box without continuing with the intended operation, the user can click Cancel. If the user clicks Cancel, the dialog box throws a CommDlgExtendedError exception. This error allows you to find out what happened: maybe the user didn't click Cancel, maybe the dialog box was not even created, maybe this, maybe that. This error allows you to diagnose a potential problem and deal with it. If you don't want to go through this, you can just cancel the operation yourself.

The Title of the File Dialog Box

By default, if you declare a CFileDialog variable and pass the first argument as TRUE, when it displays, the dialog box's title shows "Open". If you pass the first argument as FALSE, the dialog box's title would display Save As. The operating system allows you to specify a title of your choice. This can be done by assigning a string to the lpstrTitle member variable of the OPENFILENAME structure through the CFileDialog::m_ofn member. Here is an example:

void CExerciseDlg::OnBnClickedFileBtn()
{
	CFileDialog *dlg = new CFileDialog(TRUE);

	dlg->m_ofn.lpstrTitle = L"It's Time to Open the File";

	dlg->DoModal();
}

The Location of a File

Files must be meticulously organized in a computer so they can be easily retrieved and used. In Microsoft Windows, files are organized as a tree. The root of a file is a drive. The file is stored in the current computer, it is considered local. A file can be located in another computer that is connected to the computer that is trying to access the file.

A file can be stored on local drive but most of the time, under the root, there more many directories. In the Microsoft Windows dialect, these are also called folders. Folders can contain sub-folders and sub-folders can contain other sub-folders. A file can be stored on the root, inside a directory created on the root, or inside a sub-directory or a directory. A file can also be stored in a drive or a directory on another computer.

The location of a file is a combination of the root and directories that constitute its ancestry. When using the File dialog box, the user can select a local or a network drive to save or open a file, provided the permissions allow him to perform the operation.

In the strict sense, the file name is a long string that starts from its drive all the way to its "normal" name. This is also referred to as its path. To get the path of the being dealt with, you can call the CFileDialog::GetPathName() member function. Its syntax is:

CString GetPathName() const;

The Name of a File

As far as a user is concerned, the most important aspect of a file is its name. When saving a file, the user must enter a name in the File Name of the dialog box. When opening a file, the user must select it by its name. If you want, you can enter a default file name for the user when the dialog box comes up. To do this, pass the desired string as the third argument to the CFileDialog variable. Here is an example:

void CExerciseDlg::OnBnClickedFileBtn()
{
	CFileDialog *dlg = new CFileDialog(FALSE, NULL, L"Exercise");

	dlg->DoModal();
}

This time, when the dialog box displays, the file name box would show the string from the third argument.

To let you get the name of the file the user is dealing with or dealt with on the dialog box, you can call the CFileDialog::GetFileName() member function. Its syntax is:

CString GetFileName() const;

The Extension to a File

Besides its name, the most important detail of a file is its extension. This is 1 or a combination of 2, 3, 4, or more characters that end the full name of a file. The extension is separated from the actual name of a file by a period. For example, the extension of a Microsoft Word file is .docx. The extension of a Perl file is pl.

When you display a File dialog box to the user, you have many options to specify a default file extension to filter the types of files the user would deal with. To assist you, the CFileDialog class provides a second argument: lpszDefExt. If you decide to use it. Pass the desired extension. This is mostly useful when saving a file, in which case if the user gives only a name to the file but doesn't select an extension, when the user clicks Save, the operating system would apply the value of the lpszDefExt argument to it. Here is an example of specifying a default file extension:

void CExerciseDlg::OnBnClickedFileBtn()
{
	CFileDialog *dlg = new CFileDialog(FALSE, L".txt");

	dlg->DoModal();
}

If you don't want to specify a default file extension, pass the second argument as NULL. After dealing with the File dialog box (whether opening or saving a file), if the user clicks the Save or the Open button, to let you find out the extension of that file, you can call the CFileDialog::GetFileExt() member function. Its syntax is:

CString GetFileExt() const;

Filtering Files

You can create an application that deals with only one type of file and you specify the type of extension. Or you can create application that can handle many types of files. In this case, you would allow a user to specify the type of file to open or save. In reality, a file extension is the primary means of a user to categorize a file. If your application can deal with various types of files, when opening or saving a file, you can assist the user by giving an extension to the file. In fact, you can create a series of file extensions that the user would select from.

A filter is one or more strings that specify or restrict the types of files the user can use when opening files or when saving one. For a text-based application, you may allow only text files, that is, files with a txt extension. For a rich text-based application, you may allow only Rich Text Format files, which are files with rtf extension. On the other hand, if you are creating an application for web files, you can allow as many file extensions as necessary, such as htm, html, php, asp, etc. As you may realize, text files or web files are all text-based files. This means that if you create a text-based or rich-text based application, you should allow the users to decide whether the file they are trying to open can be "read" by a text-based control.

To create a list of file extensions for your File dialog box, create one or a combinations of values where each uses the following formula:

Prompt|Extension

If saving a file, the Prompt is a section that defines what the user would see in the Save As Type combo box:

If opening the file, the Prompt would display in a combo box on the right side of the File Name box:

An example would be Text Files. Such a string does not let the user know what actual extension the file would use. Therefore, as a courtesy, you can specify, between parentheses, the extension that would be applied if this extension is used. Therefore, the Prompt can be Text Files (*.txt). In this case, the extension used would be .txt. The asterisk * lets the user know that whatever is provided as the file name would be used in place of the asterisk. The period indicates the separation from the file to its extension. This means that the characters on the left of the period would be the file name, the characters on the right side of the period would be used as the actual file extension.

To specify the extension that the operating system would use to associate to the file, you provide a second part of the string as Extension. In Microsoft Windows, most extensions are made of three characters. Some applications use a 2-letter extensions (for example Perl files have a .pl extension and C# files use .cs) and some others use 4 letters (such as .html for some HTML files). This depends. An example of a string that species an extension is:

Text Files (*.txt)|*.txt

You should end a file with ||. If you want to provide various extensions to your Save dialog box, you can separate them with a | symbol. An example would be:

HTML Files (*.htm)|*.htm|Active Server Pages (*.asp)|*.asp|Perl Script (*.pl)|*.pl||

To specify the filter used by the File dialog box, you can pass its string as the fourth argument to the CFileDialog constructor. Here is an example:

void CExerciseDlg::OnBnClickedFileBtn()
{
	CFileDialog *dlg = new CFileDialog(TRUE, L"txt", NULL, NULL,
					   L"HTML Files (*.htm)|*.htm|"
					   L"Active Server Pages (*.asp)|*.asp|"
					   L"Apache Files (*.php)|*.php|"
					   L"Perl Script (*.pl)|*.pl|"
					   L"All Files||");

	dlg->DoModal();
}

This would produce:

Opening Many Files

By default, the File dialog box allows a user to select one file and open it. If you want, you can make it possible to open many files at once. To start, add the OFN_ALLOWMULTISELECT flag to either the appropriate member of the OPENFILENAME variable or add it to the fourth argument of the CFileDialog constructor. Here is an example:

void CExerciseDlg::OnBnClickedFileBtn()
{
	CFileDialog *dlg = new CFileDialog(TRUE, L"txt", NULL, OFN_ALLOWMULTISELECT);

	dlg->DoModal();
}

When this has been done, the user can press the Ctrl or Shift keys to select the files.