#include <commdlg.h>
typedef struct tagOPENFILENAME { /* ofn */
DWORD lStructSize;
HWND hwndOwner;
HINSTANCE hInstance;
LPCSTR lpstrFilter;
LPSTR lpstrCustomFilter;
DWORD nMaxCustFilter;
DWORD nFilterIndex;
LPSTR lpstrFile;
DWORD nMaxFile;
LPSTR lpstrFileTitle;
DWORD nMaxFileTitle;
LPCSTR lpstrInitialDir;
LPCSTR lpstrTitle;
DWORD Flags;
UINT nFileOffset;
UINT nFileExtension;
LPCSTR lpstrDefExt;
LPARAM lCustData;
UINT (CALLBACK *lpfnHook) (HWND, UINT, WPARAM, LPARAM);
LPCSTR lpTemplateName;
} OPENFILENAME;The OPENFILENAME structure contains information that the system uses to initialize the system-defined Open dialog box or Save dialog box. After the user chooses the OK button to close the dialog box, the system returns information about the user's selection in this structure.
lStructSize
Specifies the length of the structure, in bytes. This member is filled on input.
hwndOwner
Identifies the window that owns the dialog box. This member can be any valid window handle, or it should be NULL if the dialog box is to have no owner.
If the OFN_SHOWHELP flag is set, hwndOwner must identify the window that owns the dialog box. The window procedure for this owner window receives a notification message when the user chooses the Help button. (The identifier for the notification message is the value returned by the RegisterWindowMessage function when HELPMSGSTRING is passed as its argument.)
This member is filled on input.
hInstance
Identifies a data block that contains a dialog box template specified by the lpTemplateName member. This member is used only if the Flags member specifies the OFN_ENABLETEMPLATE or the OFN_ENABLETEMPLATEHANDLE flag; otherwise, this member is ignored.
This member is filled on input.
lpstrFilter
Points to a buffer containing one or more pairs of null-terminated strings specifying filters. The first string in each pair describes a filter (for example, “Text Files”); the second specifies the filter pattern (for example, “*.txt”). Multiple filters can be specified for a single item; in this case, the semicolon (;) is used to separate filter pattern strings—for example, “*.txt;*.doc;*.bak”. The last string in the buffer must be terminated by two null characters. If this parameter is NULL, the dialog box does not display any filters. The filter strings must be in the proper order—the system does not change the order.
This member is filled on input.
lpstrCustomFilter
Points to a buffer containing a pair of user-defined strings that specify a filter. The first string describes the filter, and the second specifies the filter pattern (for example, “WinWord”, “*.doc”). The buffer is terminated by two null characters. The system copies the strings to the buffer when the user chooses the OK button to close the dialog box. The system uses the strings as the initial filter description and filter pattern for the dialog box. If this parameter is NULL, the dialog box lists (but does not save) user-defined filter strings.
nMaxCustFilter
Specifies the size, in bytes, of the buffer identified by the lpstrCustomFilter member. This buffer should be at least 40 bytes long. This parameter is ignored if the lpstrCustomFilter member is NULL.
This member is filled on input.
nFilterIndex
Specifies an index into the buffer pointed to by the lpstrFilter member. The system uses the index value to obtain a pair of strings to use as the initial filter description and filter pattern for the dialog box. The first pair of strings has an index value of 1. When the user chooses the OK button to close the dialog box, the system copies the index of the selected filter strings into this location. If the nFilterIndex member is 0, the filter in the buffer pointed to by the lpstrCustomFilter member is used. If the nFilterIndex member is 0 and the lpstrCustomFilter member is NULL, the system uses the first filter in the buffer pointed to by the lpstrFilter member. If each of the three members is either 0 or NULL, the system does not use any filters and does not show any files in the File Name list box of the dialog box.
lpstrFile
Points to a buffer that specifies a filename used to initialize the File Name edit control. If initialization is not necessary, the first character of this buffer must be NULL. When the GetOpenFileName or GetSaveFileName function returns, this buffer contains the complete location and name of the selected file.
If the buffer is too small, the dialog box procedure copies the required size into this member and returns 0. To retrieve the required size, cast the lpstrFile member to type LPWORD. The buffer must be at least three bytes to receive the required size. When the buffer is too small, the CommDlgExtendedError function returns the FNERR_BUFFERTOOSMALL value.
nMaxFile
Specifies the size, in bytes, of the buffer pointed to by the lpstrFile member. The GetOpenFileName and GetSaveFileName functions return FALSE if the buffer is too small to contain the file information. The buffer should be at least 256 bytes long. If the lpstrFile member is NULL, this member is ignored.
This member is filled on input.
lpstrFileTitle
Points to a buffer that receives the title of the selected file. This buffer receives the filename and extension but no path information. An application should use this string to display the file title. If this member is NULL, the function does not copy the file title. This member is filled on output.
nMaxFileTitle
Specifies the maximum length, in bytes, of the string that can be copied into the lpstrFileTitle buffer. This member is ignored if lpstrFileTitle is NULL. This member is filled on input.
lpstrInitialDir
Points to a string that specifies the initial file directory. If this member is NULL, the system uses the current directory as the initial directory. (If the lpstrFile member contains a string that specifies a valid path, the common dialog box procedure will use the path specified by this string instead of the path specified by the string to which lpstrInitialDir points.)
This member is filled on input.
lpstrTitle
Points to a string to be placed in the title bar of the dialog box. If this member is NULL, the system uses the default title (that is, Save As or Open). This member is filled on input.
Flags
Specifies the dialog box initialization flags. This member may be a combination of the following values:
| Value | Meaning |
| OFN_ALLOWMULTISELECT | ||
| Specifies that the File Name list box is to allow multiple selections. When this flag is set, the lpstrFile member points to a buffer containing the path to the current directory and all filenames in the selection. The first filename is separated from the path by a space. Each subsequent filename is separated by one space from the preceding filename. Some of the selected filenames may be preceded by relative paths; for example, the buffer could contain something like this: | ||
| c:\files file1.txt file2.txt ..\bin\file3.txt | ||
| OFN_CREATEPROMPT | Causes the dialog box procedure to generate a message box to notify the user when a specified file does not currently exist and to make it possible for the user to specify that the file should be created. (This flag automatically sets the OFN_PATHMUSTEXIST and OFN_FILEMUSTEXIST flags.) | |
| OFN_ENABLEHOOK | Enables the hook function specified in the lpfnHook member. | |
| OFN_ENABLETEMPLATE | Causes the system to use the dialog box template identified by the hInstance and lpTemplateName members to create the dialog box. | |
| OFN_ENABLETEMPLATEHANDLE | ||
| Indicates that the hInstance member identifies a data block that contains a pre-loaded dialog box template. The system ignores the lpTemplateName member if this flag is specified. | ||
| OFN_EXTENSIONDIFFERENT | ||
| Indicates that the extension of the returned filename is different from the extension specified by the lpstrDefExt member. This flag is not set if lpstrDefExt is NULL, if the extensions match, or if the file has no extension. This flag can be set on output. | ||
| OFN_FILEMUSTEXIST | Specifies that the user can type only the names of existing files in the File Name edit control. If this flag is set and the user types an invalid filename in the File Name edit control, the dialog box procedure displays a warning in a message box. (This flag also causes the OFN_PATHMUSTEXIST flag to be set.) | |
| OFN_HIDEREADONLY | Hides the Read Only check box. | |
| OFN_NOCHANGEDIR | Forces the dialog box to reset the current directory to what it was when the dialog box was created. | |
| OFN_NOREADONLYRETURN | ||
| Specifies that the file returned will not have the Read Only attribute set and will not be in a write-protected directory. | ||
| OFN_NOTESTFILECREATE | Specifies that the file will not be created before the dialog box is closed. This flag should be set if the application saves the file on a create-no-modify network share point. When an application sets this flag, the library does not check against write protection, a full disk, an open drive door, or network protection. Therefore, applications that use this flag must perform file operations carefully—a file cannot be reopened once it is closed. | |
| OFN_NOVALIDATE | Specifies that the common dialog boxes will allow invalid characters in the returned filename. Typically, the calling application uses a hook function that checks the filename using the FILEOKSTRING registered message. If the text in the edit control is empty or contains nothing but spaces, the lists of files and directories are updated. If the text in the edit control contains anything else, the nFileOffset and nFileExtension members are set to values generated by parsing the text. No default extension is added to the text, nor is text copied to the lpstrFileTitle buffer. | |
| If the value specified by the nFileOffset mem-ber is negative, the filename is invalid. If the value specified by nFileOffset is not negative, the filename is valid, and nFileOffset and nFileExtension can be used as if the OFN_NOVALIDATE flag had not been set. | ||
| OFN_OVERWRITEPROMPT | Causes the Save As dialog box to generate a message box if the selected file already exists. The user must confirm whether to overwrite the file. | |
| OFN_PATHMUSTEXIST | Specifies that the user can type only valid paths. If this flag is set and the user types an invalid path in the File Name edit control, the dialog box procedure displays a warning in a message box. | |
| OFN_READONLY | Causes the Read Only check box to be initially checked when the dialog box is created. When the user chooses the OK button to close the dialog box, the state of the Read Only check box is specified by this member. This flag can be set on input and output. | |
| OFN_SHAREAWARE | Specifies that if a call to the OpenFile function has failed because of a network sharing violation, the error is ignored and the dialog box returns the given filename. If this flag is not set, the registered message for SHAREVISTRING is sent to the hook function, with a pointer to a null-terminated string for the path name in the lParam parameter. The hook function responds with one of the following values: | |
| Value | Meaning |
| OFN_SHAREFALLTHROUGH | ||
| Specifies that the filename is returned from the dialog box. | ||
| OFN_SHARENOWARN | ||
| Specifies no further action. | ||
| OFN_SHAREWARN | ||
| Specifies that the user receives the standard warning message for this error. (This is the same result as if there were no hook function.) | ||
| This flag may be set on output. | |
| OFN_SHOWHELP | Causes the dialog box to show the Help push button. The hwndOwner must not be NULL if this option is specified. |
These flags may be set when the structure is initialized, except where specified.
nFileOffset
Specifies a zero-based offset from the beginning of the path to the filename specified by the string in the buffer to which lpstrFile points. For example, if lpstrFile points to the string, “c:\dir1\dir2\file.ext”, this member contains the value 13.
This member is filled on output.
nFileExtension
Specifies a zero-based offset from the beginning of the path to the filename extension specified by the string in the buffer to which lpstrFile points. For example, if lpstrFile points to the following string, “c:\dir1\dir2\file.ext”, this member contains the value 18. If the user did not type an extension and lpstrDefExt is NULL, this member specifies an offset to the terminating null character. If the user typed a period (.) as the last character in the filename, this member is 0.
This member is filled on output.
lpstrDefExt
Points to a buffer that contains the default extension. The GetOpenFileName or GetSaveFileName function appends this extension to the filename if the user fails to enter an extension. If the filename with the default extension is not found, GetOpenFileName or GetSaveFileName attempts to find the file by using the name exactly as the user typed it. This string can be any length, but only the first three characters are appended. The string should not contain a period (.). If this member is NULL and the user fails to type an extension, no extension is appended. This member is filled on input.
lCustData
Specifies application-defined data that the system passes to the hook function pointed to by the lpfnHook member. The system passes a pointer to the OPENFILENAME structure in the lParam parameter of the WM_INITDIALOG message; this pointer can be used to retrieve the lCustData member.
lpfnHook
Points to a hook function that processes messages intended for the dialog box. To enable the hook function, an application must specify the OFN_ENABLEHOOK flag in the Flags member; otherwise, the system ignores this structure member. The hook function must return zero to pass a message that it didn't process back to the dialog box procedure in COMMDLG.DLL. The hook function must return a nonzero value to prevent the dialog box procedure in COMMDLG.DLL from processing a message it has already processed.
This member is filled on input.
lpTemplateName
Points to a null-terminated string that specifies the name of the resource file for the dialog box template that is to be substituted for the dialog box template in COMMDLG.DLL. An application can use the MAKEINTRESOURCE macro for numbered dialog box resources. This member is used only if the Flags member specifies the OFN_ENABLETEMPLATE flag; otherwise, this member is ignored.
This member is filled on input.