OPENFILENAME

Article
06/30/2006

This structure contains information the operating system uses to initialize the system-defined Open or Save As 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;
  LPCSTR lpstrFilter;
  LPSTR lpstrCustomFilter;
  DWORD nMaxCustFilter;
  DWORD nFilterIndex;
  LPSTR lpstrFile;
  DWORD nMaxFile;
  LPSTR lpstrFileTitle;
  DWORD nMaxFileTitle;
  LPSTR lpstrInitialDir;
  LPCSTR lpstrTitle;
  DWORD Flags;
  WORD nFileOffset;
  WORD nFileExtension;
  LPCSTR lpstrDefExt;
  DWORD lCustData;
  LPOFNHOOKPROC lpfnHook;
  LPCSTR lpTemplateName;
} OPENFILENAME;

Members

lStructSize
Specifies the length, in bytes, of the structure.
hwndOwner
Handle to 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
Not supported.
lpstrFilter
Long pointer to a buffer that contains 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 file name characters and the asterisk (*) wildcard character. Do not include spaces in the pattern string.

The system does not change the order of the filters. It displays them in the FileTypes combo box in the order specified in lpstrFilter.

If lpstrFilter is NULL, the dialog box does not display any filters.
lpstrCustomFilter
Not supported.
nMaxCustFilter
Not supported.
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. 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, the system uses the first filter in the lpstrFilter buffer.
lpstrFile
Long pointer to a buffer that contains a file name 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, file name, and extension of the selected file.

If the buffer is too small, the function returns FALSE. 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 16-bit 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
Long pointer to a buffer that receives the file name and extension (without path information) of the selected file. This member can be NULL.
nMaxFileTitle
Specifies the size, in bytes (ANSI version) or 16-bit characters (Unicode version), of the buffer pointed to by lpstrFileTitle. This member is ignored if lpstrFileTitle is NULL.
lpstrInitialDir
Long pointer to a string that specifies the initial file directory. If this member is NULL, the system uses the root directory.
lpstrTitle
Long 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, SaveAs or Open).

Flags
A bitmask of flags used 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.

Value	Description
OFN_ALLOWMULTISELECT	Not supported.
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	Not supported.
OFN_ENABLESIZING	Not supported.
OFN_ENABLETEMPLATE	Not supported.
OFN_ENABLETEMPLATEHANDLE	Not supported.
OFN_EXPLORER	Ignored. The Explorer user interface is always used.
OFN_EXTENSIONDIFFERENT	Specifies that the user typed a file name 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 FileName 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	Ignored. The Explorer user interface is always used.
OFN_NOCHANGEDIR	Not supported.
OFN_NODEREFERENCELINKS	Directs the dialog box to return the path and file name of the selected shortcut (.LNK) file. If this value is not given, the dialog box returns the path and file name of the file referenced by the shortcut
OFN_NOLONGNAMES	Not supported.
OFN_NONETWORKBUTTON	Not supported.
OFN_NOREADONLYRETURN	Not supported.
OFN_NOTESTFILECREATE	Not supported.
OFN_NOVALIDATE	Ignored. A file name is always validated.
OFN_PROJECT	For version 2.0, causes the GetOpenFileName function to open the Project dialog box.
OFN_PROPERTY	For version 2.0, causes the GetSaveFileName function to open the Property dialog box.
OFN_OVERWRITEPROMPT	Causes the SaveAs 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 file names. If this flag is used and the user types an invalid path and file name in the FileName entry field, the dialog box function displays a warning in a message box.
OFN_READONLY	Not supported.
OFN_SHAREAWARE	Not supported.
OFN_SHOWHELP	Not supported.

nFileOffset
Specifies the zero-based offset, in bytes (ANSI version) or 16-bit characters (Unicode version), from the beginning of the path to the file name 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 the zero-based offset, in bytes (ANSI version) or 16-bit characters (Unicode version), from the beginning of the path to the file name 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 file name, this member specifies zero.
lpstrDefExt
Long pointer to a buffer that contains the default extension. GetOpenFileName and GetSaveFileName append this extension to the file name 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
Not supported.
lpfnHook
Not supported.
lpTemplateName
Not supported.

Requirements

OS Versions: Windows CE 1.0 and later.
Header: Commdlg.h.

Share via

OPENFILENAME

Members

Requirements

See Also

Additional resources