OPENFILENAME
The OPENFILENAME
structure contains information that the GetOpenFileName and GetSaveFileName functions use to
initialize an Open or Save As common dialog box. After the user closes the
dialog box, the system returns information about the user s selection in this structure.
typedef struct tagOFN { // ofn
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;
DWORD lCustData;
LPOFNHOOKPROC lpfnHook;
LPCTSTR lpTemplateName;
} OPENFILENAME;
Members
lStructSize
Specifies the
length, in bytes, of the structure.
hwndOwner
Identifies
the window that owns the dialog box. This member can be any valid window
handle, or it can be NULL if the dialog box has no owner.
hInstance
If the
OFN_ENABLETEMPLATEHANDLE flag is set in the Flags member, hInstance
is the handle of a memory object containing a dialog box template. If the
OFN_ENABLETEMPLATE flag is set, hInstance identifies a module that
contains a dialog box template named by the lpTemplateName member. If
neither flag is set, this member is ignored.
If the OFN_EXPLORER flag is set, the system uses the specified template
to create a dialog box that is a child of the default Explorer-style dialog
box. If the OFN_EXPLORER flag is not set, the system uses the template to create
an old-style dialog box that replaces the default dialog box.
lpstrFilter
Pointer to a
buffer containing pairs of null-terminated filter strings. The last string in
the buffer must be terminated by two NULL characters.
The first
string in each pair is a display string that describes the filter (for example,
Text Files ),
and the second string specifies the filter pattern (for example, *.TXT ). To specify
multiple filter patterns for a single display string, use a semicolon to
separate the patterns (for example, *.TXT;*.DOC;*.BAK ). A pattern string can be a combination of valid
filename characters and the asterisk (*) wildcard character. Do not include
spaces in the pattern string.
The operating
system does not change the order of the filters. It displays them in the File
Types combo box in the order specified in lpstrFilter.
If lpstrFilter
is NULL, the dialog box does not display any filters.
lpstrCustomFilter
Pointer to a
static buffer that contains a pair of null-terminated filter strings for preserving
the filter pattern chosen by the user. The first string is your display string
that describes the custom filter, and the second string is the filter pattern
selected by the user. The first time your application creates the dialog box,
you specify the first string, which can be any nonempty string. When the user
selects a file, the dialog box copies the current filter pattern to the second
string. The preserved filter pattern can be one of the patterns specified in
the lpstrFilter buffer, or it can be a filter pattern typed by the user.
The system uses the strings to initialize the user-defined file filter the next
time the dialog box is created. If the nFilterIndex member is zero, the
dialog box uses the custom filter.
If this
member is NULL, the dialog box does not preserve user-defined filter patterns.
If this member is not NULL, the value of the nMaxCustFilter
member must specify the size, in bytes (ANSI version) or characters (Unicode
version), of the lpstrCustomFilter buffer.
nMaxCustFilter
Specifies the
size, in bytes or characters, of the buffer identified by lpstrCustomFilter.
This buffer should be at least 40 characters long. This member is ignored if lpstrCustomFilter
is NULL or points to a NULL string.
nFilterIndex
Specifies the
index of the currently selected filter in the File Types control. The buffer
pointed to by lpstrFilter contains pairs of strings that define the
filters. The first pair of strings has an index value of 1, the second pair 2,
and so on. An index of zero indicates the custom filter specified by lpstrCustomFilter.
You can specify an index on input to indicate the initial filter description
and filter pattern for the dialog box. When the user selects a file, nFilterIndex
returns the index of the currently displayed filter.
If nFilterIndex
is zero and lpstrCustomFilter is NULL, the system uses the first filter
in the lpstrFilter buffer. If all three members are zero or NULL, the
system does not use any filters and does not show any files in the file list
control of the dialog box.
lpstrFile
Pointer to a
buffer that contains a filename used to initialize the File Name edit control.
The first character of this buffer must be NULL if initialization is not
necessary. When the GetOpenFileName or GetSaveFileName function returns
successfully, this buffer contains the drive designator, path, filename, and extension
of the selected file.
If the
OFN_ALLOWMULTISELECT flag is set and the user selects multiple files, the
buffer contains the current directory followed by the filenames of the selected
files. For Explorer-style dialog boxes, the directory and filename strings are
NULL separated, with an extra NULL character after the last filename. For
old-style dialog boxes, the strings are space separated and the function uses
short filenames for filenames with spaces. You can use the FindFirstFile function to convert
between long and short filenames.
If the buffer is too small, the function returns FALSE and the CommDlgExtendedError function returns
FNERR_BUFFERTOOSMALL. In this case, the first two bytes of the lpstrFile
buffer contain the required size, in bytes or characters.
nMaxFile
Specifies the
size, in bytes (ANSI version) or characters (Unicode version), of the buffer
pointed to by lpstrFile. 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 characters long.
lpstrFileTitle
Pointer to a
buffer that receives the filename and extension (without path information) of
the selected file. This member can be NULL.
nMaxFileTitle
Specifies the
size, in bytes (ANSI version) or characters (Unicode version), of the buffer
pointed to by lpstrFileTitle. This member is ignored if lpstrFileTitle
is NULL.
lpstrInitialDir
Pointer to a
string that specifies the initial file directory. If this member is NULL, the
system uses the current directory as the initial directory.
lpstrTitle
Pointer 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 ).
Flags
A set of bit flags
you can use to initialize the dialog box. When the dialog box returns, it sets
these flags to indicate the user s
input. This member can be a combination of the following flags:
|
Flag |
Meaning |
|
OFN_ALLOWMULTISELECT |
|
|
|
Specifies
that the File Name list box allows multiple selections. If you also set the
OFN_EXPLORER flag, the dialog box uses the Explorer-style user interface;
otherwise, it uses the old-style user interface. If the user
selects more than one file, the lpstrFile buffer returns the path to
the current directory followed by the filenames of the selected files. The nFileOffset
member is the offset to the first filename, and the nFileExtension
member is not used. For Explorer-style dialog boxes, the directory and
filename strings are NULL separated, with an extra NULL character after the
last filename. This format enables the Explorer-style dialogs to return long
filenames that include spaces. For old-style dialog boxes, the directory and
filename strings are separated by spaces and the function uses short
filenames for filenames with spaces. You can use the FindFirstFile function to convert
between long and short filenames. If you
specify a custom template for an old-style dialog box, the definition of the
File Name list box must contain the LBS_EXTENDEDSEL value. |
|
OFN_CREATEPROMPT |
|
|
|
If the user
specifies a file that does not exist, this flag causes the dialog box to
prompt the user for permission to create the file. If the user chooses to
create the file, the dialog box closes and the function returns the specified
name; otherwise, the dialog box remains open. |
|
OFN_ENABLEHOOK |
|
|
|
Enables the
hook function specified in the lpfnHook member. |
|
OFN_ENABLETEMPLATE |
|
|
|
Indicates
that the lpTemplateName member points to the name of a dialog template
resource in the module identified by the hInstance member. If the
OFN_EXPLORER flag is set, the system uses the specified template to create a
dialog box that is a child of the default Explorer-style dialog box. If the
OFN_EXPLORER flag is not set, the system uses the template to create an
old-style dialog box that replaces the default dialog box. |
|
OFN_ENABLETEMPLATEHANDLE |
|
|
|
Indicates
that the hInstance member identifies a data block that contains a
preloaded dialog box template. The system ignores the lpTemplateName
if this flag is specified. If the
OFN_EXPLORER flag is set, the system uses the specified template to create a
dialog box that is a child of the default Explorer-style dialog box. If the
OFN_EXPLORER flag is not set, the system uses the template to create an
old-style dialog box that replaces the default dialog box. |
|
OFN_EXPLORER |
|
|
|
Indicates
that any customizations made to the Open or Save As dialog box use the new
Explorer-style customization methods. For more information, see the Explorer-Style Hook Procedures and Explorer-Style
Custom Templates sections of the Common Dialog Box Library overview. By default,
the Open and Save As dialog boxes use the Explorer-style user interface
regardless of whether this flag is set. This flag is necessary only if you
provide a hook procedure or custom template, or set the OFN_ALLOWMULTISELECT
flag. If you want
the old-style user interface, omit the OFN_EXPLORER flag and provide a
replacement old-style template or hook procedure. If you want the old style
but do not need a custom template or hook procedure, simply provide a hook
procedure that always returns FALSE. |
|
OFN_EXTENSIONDIFFERENT |
|
|
|
Specifies
that the user typed a filename extension that differs from the extension
specified by lpstrDefExt. The function does not use this flag if lpstrDefExt
is NULL. |
|
OFN_FILEMUSTEXIST |
|
|
|
Specifies
that the user can type only names of existing files in the File Name entry
field. If this flag is specified and the user enters an invalid name, the
dialog box procedure displays a warning in a message box. If this flag is
specified, the OFN_PATHMUSTEXIST flag is also used. |
|
OFN_HIDEREADONLY |
|
|
|
Hides the
Read Only check box. |
|
OFN_LONGNAMES |
|
|
|
For
old-style dialog boxes, this flag causes the dialog box to use long
filenames. If this flag is not specified, or if the OFN_ALLOWMULTISELECT flag
is also set, old-style dialog boxes use short filenames (8.3 format) for
filenames with spaces. Explorer-style
dialog boxes ignore this flag and always display long filenames. |
|
OFN_NOCHANGEDIR |
|
|
|
Restores
the current directory to its original value if the user changed the directory
while searching for files. |
|
OFN_NODEREFERENCELINKS |
|
|
|
Directs the
dialog box to return the path and filename of the selected shortcut (.LNK)
file. If this value is not given, the dialog box returns the path and
filename of the file referenced by the shortcut |
|
OFN_NOLONGNAMES |
|
|
|
For
old-style dialog boxes, this flag causes the dialog box to use short
filenames (8.3 format). Explorer-style
dialog boxes ignore this flag and always display long filenames. |
|
OFN_NONETWORKBUTTON |
|
|
|
Hides and
disables the Network button. |
|
OFN_NOREADONLYRETURN |
|
|
|
Specifies
that the returned file does not have the Read Only check box checked and is
not in a write-protected directory. |
|
OFN_NOTESTFILECREATE |
|
|
|
Specifies
that the file is not created before the dialog box is closed. This flag
should be specified if the application saves the file on a create-nonmodify
network sharepoint. When an application specifies this flag, the library does
not check for write protection, a full disk, an open drive door, or network
protection. Applications using this flag must perform file operations
carefully, because a file cannot be reopened once it is closed. |
|
OFN_NOVALIDATE |
|
|
|
Specifies
that the common dialog boxes allow invalid characters in the returned
filename. Typically, the calling application uses a hook procedure that
checks the filename by using the FILEOKSTRING message. If the text box in the
edit control is empty or contains nothing but spaces, the lists of files and
directories are updated. If the text box in the edit control contains
anything else, nFileOffset and nFileExtension are set to values
generated by parsing the text. No default extension is added to the text, nor
is text copied to the buffer specified by lpstrFileTitle. |
|
|
If the
value specified by nFileOffset is less than zero, the filename is
invalid. Otherwise, the filename is valid, and nFileExtension and nFileOffset
can be used as if the OFN_NOVALIDATE flag had not been specified. |
|
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 and filenames. If this flag is used
and the user types an invalid path and filename in the File Name entry field,
the dialog box function displays a warning in a message box. |
|
OFN_READONLY |
|
|
|
Causes the
Read Only check box to be checked initially when the dialog box is created.
This flag indicates the state of the Read Only check box when the dialog box
is closed. |
|
OFN_SHAREAWARE |
|
|
|
Specifies
that if a call to the OpenFile function fails because of a network sharing violation,
the error is ignored and the dialog box returns the selected filename. If this
flag is not set, the dialog box notifies your hook procedure when a network
sharing violation occurs for the filename specified by the user. If you set
the OFN_EXPLORER flag, the dialog box sends the CDN_SHAREVIOLATION message to the hook
procedure. If you do not set OFN_EXPLORER, the dialog box sends the SHAREVISTRING registered message to the
hook procedure. |
|
OFN_SHOWHELP |
|
|
|
Causes the
dialog box to display the Help button. The hwndOwner member must
specify the window to receive the HELPMSGSTRING1N5CG6 registered messages that the dialog box
sends when the user clicks the Help button. An
Explorer-style dialog box sends a CDN_HELP notification message to your hook procedure when
the user clicks the Help button. |
nFileOffset
Specifies a
zero-based offset from the beginning of the path to the filename in the string
pointed to by lpstrFile. For example, if lpstrFile points to the
following string, c:\dir1\dir2\file.ext , this member contains the value 13 to indicate the offset of the file.ext
string.
nFileExtension
Specifies a
zero-based offset from the beginning of the path to the filename extension in
the string pointed to by lpstrFile. 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 . as the last
character in the filename, this member specifies zero.
lpstrDefExt
Points to a
buffer that contains the default extension. GetOpenFileName and GetSaveFileName append this extension to
the filename if the user fails to type an extension. 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.
lCustData
Specifies
application-defined data that the system passes to the hook procedure
identified by the lpfnHook member. When the system sends the WM_INITDIALOG message to the hook procedure,
the message s lParam parameter is a pointer to the OPENFILENAME
structure specified when the dialog box was created. The hook procedure can use
this pointer to get the lCustData value.
lpfnHook
Pointer to a
hook procedure. This member is ignored unless the Flags member includes
the OFN_ENABLEHOOK flag.
If the
OFN_EXPLORER flag is not set in the Flags member, lpfnHook is a
pointer to an OFNHookProcOldStyle hook procedure that receives messages intended
for the dialog box. The hook procedure returns FALSE to pass a message to the
default dialog box procedure or TRUE to discard the message.
If
OFN_EXPLORER is set, lpfnHook is a pointer to an OFNHookProc hook procedure. The hook
procedure receives notification messages sent from the dialog box. The hook
procedure also receives messages for any additional controls that you defined
by specifying a child dialog template. The hook procedure does not receive
messages intended for the standard controls of the default dialog box.
lpTemplateName
Pointer to a
null-terminated string that names a dialog template resource in the module
identified by the hInstance member. For numbered dialog box resources,
this can be a value returned by the MAKEINTRESOURCE macro. This member is
ignored unless the OFN_ENABLETEMPLATE flag is set in the Flags member.
If the OFN_EXPLORER flag is set, the system uses the specified template
to create a dialog box that is a child of the default Explorer-style dialog
box. If the OFN_EXPLORER flag is not set, the system uses the template to
create an old-style dialog box that replaces the default dialog box.
See Also