OPENFILENAMEW 结构 (commdlg.h)

  • 项目

[从 Windows Vista 开始， “打开 ”和“ 另存为 ”常用对话框已被 “通用项”对话框取代。 建议使用通用项对话框 API，而不是通用对话框库中的这些对话框。]

包含 GetOpenFileName 和 GetSaveFileName 函数用于初始化 “打开 ”或“ 另存为 ”对话框的信息。 用户关闭对话框后，系统会返回有关此结构中用户选择的信息。

语法

typedef struct tagOFNW {
  DWORD         lStructSize;
  HWND          hwndOwner;
  HINSTANCE     hInstance;
  LPCWSTR       lpstrFilter;
  LPWSTR        lpstrCustomFilter;
  DWORD         nMaxCustFilter;
  DWORD         nFilterIndex;
  LPWSTR        lpstrFile;
  DWORD         nMaxFile;
  LPWSTR        lpstrFileTitle;
  DWORD         nMaxFileTitle;
  LPCWSTR       lpstrInitialDir;
  LPCWSTR       lpstrTitle;
  DWORD         Flags;
  WORD          nFileOffset;
  WORD          nFileExtension;
  LPCWSTR       lpstrDefExt;
  LPARAM        lCustData;
  LPOFNHOOKPROC lpfnHook;
  LPCWSTR       lpTemplateName;
  LPEDITMENU    lpEditInfo;
  LPCSTR        lpstrPrompt;
  void          *pvReserved;
  DWORD         dwReserved;
  DWORD         FlagsEx;
} OPENFILENAMEW, *LPOPENFILENAMEW;

成员

lStructSize

类型：DWORD

结构的长度（以字节为单位）。 将 sizeof (OPENFILENAME) 用于此参数。

hwndOwner

类型：HWND

拥有对话框的窗口的句柄。 此成员可以是任何有效的窗口句柄，如果对话框没有所有者，则它可以为 NULL 。

hInstance

类型： HINSTANCE

如果在 Flags 成员中设置了OFN_ENABLETEMPLATEHANDLE标志，则 hInstance 是包含对话框模板的内存对象的句柄。 如果设置了 OFN_ENABLETEMPLATE 标志， 则 hInstance 是包含由 lpTemplateName 成员命名的对话框模板的模块的句柄。 如果两个标志均未设置，则忽略此成员。 如果设置了 OFN_EXPLORER 标志，则系统会使用指定的模板创建一个对话框，该对话框是默认资源管理器样式对话框的子级。 如果未设置 OFN_EXPLORER 标志，系统将使用该模板创建替换默认对话框的旧样式对话框。

lpstrFilter

类型： LPCTSTR

包含以 null 结尾的筛选器字符串对的缓冲区。 缓冲区中的最后一个字符串必须以两个 NULL 字符结尾。

每对中的第一个字符串是一个显示字符串，用于描述筛选器 (，例如“文本文件”) ，第二个字符串指定筛选器模式 (例如“.TXT”) 。若要为单个显示字符串指定多个筛选模式，请使用分号分隔模式 (例如“.TXT;.DOC;。BAK“) 。 模式字符串可以是有效文件名字符和星号 (*) 通配符的组合。 不要在模式字符串中包含空格。

系统不会更改筛选器的顺序。 它按照 lpstrFilter 中指定的顺序在“文件类型”组合框中显示它们。

如果 lpstrFilter 为 NULL，则对话框不显示任何筛选器。

对于快捷方式，如果未设置筛选器， GetOpenFileName 和 GetSaveFileName 将检索.lnk文件的名称，而不是其目标。 此行为与在 Flags 成员中设置 OFN_NODEREFERENCELINKS 标志相同。 若要在不筛选的情况下检索快捷方式的目标，请使用字符串 "All Files\0*.*\0\0"。

lpstrCustomFilter

类型： LPTSTR

一个静态缓冲区，其中包含一对以 null 结尾的筛选器字符串，用于保留用户选择的筛选器模式。 第一个字符串是描述自定义筛选器的显示字符串，第二个字符串是用户选择的筛选器模式。 应用程序第一次创建对话框时，可以指定第一个字符串，该字符串可以是任何非空字符串。 当用户选择文件时，对话框会将当前筛选器模式复制到第二个字符串。 保留的筛选器模式可以是 lpstrFilter 缓冲区中指定的模式之一，也可以是用户键入的筛选器模式。 系统使用字符串在下次创建对话框时初始化用户定义的文件筛选器。 如果 nFilterIndex 成员为零，则对话框使用自定义筛选器。

如果此成员为 NULL，则对话框不会保留用户定义的筛选器模式。

如果此成员不是 NULL，则 nMaxCustFilter 成员的值必须指定 lpstrCustomFilter 缓冲区的大小（以字符为单位）。

nMaxCustFilter

类型：DWORD

lpstrCustomFilter 标识的缓冲区的大小（以字符为单位）。 此缓冲区的长度应至少为 40 个字符。 如果 lpstrCustomFilter 为 NULL 或指向 NULL 字符串，则忽略此成员。

nFilterIndex

类型：DWORD

“ 文件类型” 控件中当前所选筛选器的索引。 lpstrFilter 指向的缓冲区包含定义筛选器的字符串对。 第一对字符串的索引值为 1，第二对为 2，依依。 索引为零表示 lpstrCustomFilter 指定的自定义筛选器。 可以在输入上指定索引，以指示对话框的初始筛选器说明和筛选器模式。 当用户选择文件时， nFilterIndex 将返回当前显示的筛选器的索引。 如果 nFilterIndex 为零且 lpstrCustomFilter 为 NULL，则系统会使用 lpstrFilter 缓冲区中的第一个筛选器。 如果所有三个成员均为零或 NULL，则系统不使用任何筛选器，并且不会在对话框的文件列表控件中显示任何文件。

lpstrFile

类型： LPTSTR

用于初始化“文件名”编辑控件的 文件名 。 如果不需要初始化，则此缓冲区的第一个字符必须为 NULL 。 当 GetOpenFileName 或 GetSaveFileName 函数成功返回时，此缓冲区包含所选文件的驱动器指示符、路径、文件名和扩展名。

如果设置了 OFN_ALLOWMULTISELECT 标志，并且用户选择了多个文件，则缓冲区包含当前目录，后跟所选文件的文件名。 对于“资源管理器”样式的对话框，目录和文件名字符串以 NULL 分隔，最后一个文件名后还有一个额外的 NULL 字符。 对于旧式对话框，字符串以空格分隔，函数对带空格的文件名使用短文件名。 可以使用 FindFirstFile 函数在长文件名和短文件名之间进行转换。 如果用户仅选择一个文件， 则 lpstrFile 字符串在路径和文件名之间没有分隔符。

如果缓冲区太小，函数返回 FALSE，CommDlgExtendedError 函数返回FNERR_BUFFERTOOSMALL。 在这种情况下， lpstrFile 缓冲区的前两个字节包含所需的大小（以字节或字符为单位）。

nMaxFile

类型：DWORD

lpstrFile 指向的缓冲区的大小（以字符为单位）。 缓冲区必须足够大，才能存储路径和文件名字符串，包括终止 NULL 字符。 如果缓冲区太小而无法包含文件信息，则 GetOpenFileName 和 GetSaveFileName 函数返回 FALSE。 缓冲区的长度应至少为 256 个字符。

lpstrFileTitle

类型： LPTSTR

文件名和扩展名 (未) 所选文件的路径信息。 此成员可以为 NULL。

nMaxFileTitle

类型：DWORD

lpstrFileTitle 指向的缓冲区的大小（以字符为单位）。 如果 lpstrFileTitle 为 NULL，则忽略此成员。

lpstrInitialDir

类型： LPCTSTR

初始目录。 用于选择初始目录的算法因平台而异。

Windows 7：

  1. 如果 lpstrInitialDir 的值与应用程序首次使用 “打开 ”或“ 另存为 ”对话框时传递的值相同，则用户最近选择的路径将用作初始目录。
  2. 否则，如果 lpstrFile 包含路径，则该路径为初始目录。
  3. 否则，如果 lpstrInitialDir 不为 NULL，则指定初始目录。
  4. 如果 lpstrInitialDir 为 NULL 且当前目录包含指定筛选器类型的任何文件，则初始目录为当前目录。
  5. 否则，初始目录是当前用户的个人文件目录。
  6. 否则，初始目录为 Desktop 文件夹。
Windows 2000/XP/Vista：
  1. 如果 lpstrFile 包含路径，则该路径是初始目录。
  2. 否则， lpstrInitialDir 指定初始目录。
  3. 否则，如果应用程序过去曾使用 过“打开 ”或“ 另存为 ”对话框，则会选择最近使用的路径作为初始目录。 但是，如果应用程序长时间未运行，则会放弃其保存的选定路径。
  4. 如果 lpstrInitialDir 为 NULL 且当前目录包含指定筛选器类型的任何文件，则初始目录为当前目录。
  5. 否则，初始目录是当前用户的个人文件目录。
  6. 否则，初始目录为 Desktop 文件夹。

lpstrTitle

类型： LPCTSTR

要放置在对话框标题栏中的字符串。 如果此成员为 NULL，则系统使用默认标题 (即 另存为 或 打开) 。

Flags

类型：DWORD

一组可用于初始化对话框的位标志。 当对话框返回时，它会设置这些标志以指示用户的输入。 此成员可以是以下标志的组合。

值 含义
OFN_ALLOWMULTISELECT
0x00000200
 “ 文件名” 列表框允许进行多项选择。 如果还设置了 OFN_EXPLORER 标志，则对话框将使用资源管理器样式的用户界面;否则，它使用旧式用户界面。

如果用户选择多个文件， lpstrFile 缓冲区将返回当前目录的路径，后跟所选文件的文件名。 nFileOffset 成员是第一个文件名的偏移量（以字节或字符为单位），不使用 nFileExtension 成员。 对于资源管理器样式的对话框，目录字符串和文件名字符串以 NULL 分隔，最后一个文件名后面有一个额外的 NULL 字符。 此格式使资源管理器样式的对话框能够返回包含空格的长文件名。 对于旧样式对话框，目录和文件名字符串用空格分隔，对于带空格的文件名，此函数使用短文件名。 可以使用 FindFirstFile 函数在长文件名和短文件名之间转换。

如果为旧样式对话框指定自定义模板，则 “文件名 ”列表框的定义必须包含 LBS_EXTENDEDSEL 值。
OFN_CREATEPROMPT
0x00002000
 如果用户指定的文件不存在，则此标志会导致对话框提示用户提供创建文件的权限。 如果用户选择创建文件，对话框将关闭，函数将返回指定的名称;否则，对话框将保持打开状态。 如果将此标志与 OFN_ALLOWMULTISELECT 标志一起使用，则对话框允许用户仅指定一个不存在的文件。
OFN_DONTADDTORECENT
0x02000000
 阻止系统在包含用户最近使用的文档的文件系统目录中添加指向所选文件的链接。 若要检索此目录的位置，请使用 CSIDL_RECENT 标志调用 SHGetSpecialFolderLocation 函数。
OFN_ENABLEHOOK
0x00000020
 启用 在 lpfnHook 成员中指定的挂钩函数。
OFN_ENABLEINCLUDENOTIFY
0x00400000
 导致对话框在用户打开文件夹时将 CDN_INCLUDEITEM 通知消息发送到 OFNHookProc 挂钩过程。 该对话框为新打开的文件夹中的每一项发送通知。 通过这些邮件，您可以控制对话框在文件夹的项目列表中显示哪些项目。
OFN_ENABLESIZING
0x00800000
 允许使用鼠标或键盘调整资源管理器样式对话框的大小。 默认情况下，无论是否设置了此标志，“资源管理器”样式的“ 打开 ”和“ 另存为 ”对话框都允许调整对话框的大小。 仅当提供挂钩过程或自定义模板时，才需要此标志。 旧样式对话框不允许调整大小。
OFN_ENABLETEMPLATE
0x00000040
 lpTemplateName 成员是指向 hInstance 成员标识的模块中对话框模板资源名称的指针。 如果设置了 OFN_EXPLORER 标志，则系统会使用指定的模板创建一个对话框，该对话框是默认资源管理器样式对话框的子级。 如果未设置 OFN_EXPLORER 标志，系统将使用该模板创建替换默认对话框的旧样式对话框。
OFN_ENABLETEMPLATEHANDLE
0x00000080
 hInstance 成员标识包含预加载对话框模板的数据块。 如果指定了此标志，系统将忽略 lpTemplateName 。 如果设置了 OFN_EXPLORER 标志，则系统会使用指定的模板创建一个对话框，该对话框是默认资源管理器样式对话框的子级。 如果未设置 OFN_EXPLORER 标志，系统将使用该模板创建替换默认对话框的旧样式对话框。
OFN_EXPLORER
0x00080000
 指示对“ 打开 ”或“ 另存为 ”对话框所做的任何自定义都使用资源管理器样式的自定义方法。 有关详细信息，请参阅 资源管理器样式挂钩过程 和 资源管理器样式自定义模板。

默认情况下，无论是否设置了此标志，“ 打开 ”和“ 另存为 ”对话框都使用资源管理器样式的用户界面。 仅当提供挂钩过程或自定义模板，或设置 OFN_ALLOWMULTISELECT 标志时，才需要此标志。

如果需要旧式用户界面，请省略 OFN_EXPLORER 标志，并提供替换旧样式模板或挂钩过程。 如果需要旧样式，但不需要自定义模板或挂钩过程，只需提供始终返回 FALSE 的挂钩过程。
OFN_EXTENSIONDIFFERENT
0x00000400
 用户键入的文件扩展名不同于 lpstrDefExt 指定的扩展名。 如果 lpstrDefExt 为 NULL，则函数不使用此标志。
OFN_FILEMUSTEXIST
0x00001000
 用户只能在“文件名”条目字段中键入现有文件 的名称 。 如果指定了此标志，并且用户输入了无效的名称，则对话框过程会在消息框中显示警告。 如果指定了此标志，则还会使用 OFN_PATHMUSTEXIST 标志。 此标志可以在 “打开 ”对话框中使用。 它不能与 “另存为 ”对话框一起使用。
OFN_FORCESHOWHIDDEN
0x10000000
 强制显示系统和隐藏文件，从而替代用户设置以显示或不显示隐藏的文件。 但是，不会显示同时标记为 system 和 hidden 的文件。
OFN_HIDEREADONLY
0x00000004
 隐藏“只读检查框。
OFN_LONGNAMES
0x00200000
 对于旧式对话框，此标志会导致对话框使用长文件名。 如果未指定此标志，或者如果还设置了 OFN_ALLOWMULTISELECT 标志，则旧式对话框使用 (8.3 格式的短文件名) 带空格的文件名。 资源管理器样式对话框将忽略此标志，并始终显示长文件名。
OFN_NOCHANGEDIR
0x00000008
 如果用户在搜索文件时更改了目录，则将当前目录还原为其原始值。

此标志对 GetOpenFileName 无效。
OFN_NODEREFERENCELINKS
0x00100000
 指示对话框返回所选快捷方式的路径和文件名 (。LNK) 文件。 如果未指定此值，对话框将返回快捷方式引用的文件的路径和文件名。
OFN_NOLONGNAMES
0x00040000
 对于旧样式的对话框，此标志会导致对话框使用 (8.3 格式的短文件名) 。 资源管理器样式对话框将忽略此标志，并始终显示长文件名。
OFN_NONETWORKBUTTON
0x00020000
 隐藏和禁用“ 网络 ”按钮。
OFN_NOREADONLYRETURN
0x00008000
 返回的文件未选中“只读检查框，并且不在受写保护的目录中。
OFN_NOTESTFILECREATE
0x00010000
 在关闭对话框之前，不会创建文件。 如果应用程序将文件保存在 create-nonmodify 网络共享上，则应指定此标志。 当应用程序指定此标志时，库不会检查写入保护、完整磁盘、打开的驱动器门或网络保护。 使用此标志的应用程序必须小心执行文件操作，因为文件在关闭后无法重新打开。
OFN_NOVALIDATE
0x00000100
 通用对话框允许返回的文件名中包含无效字符。 通常，调用应用程序使用挂钩过程，该过程使用 FILEOKSTRING 消息检查文件名。 如果编辑控件中的文本框为空或只包含空格，则会更新文件和目录的列表。 如果编辑控件中的文本框包含任何其他内容， 则 nFileOffset 和 nFileExtension 将设置为通过分析文本生成的值。 不会向文本添加默认扩展名，也不会将文本复制到 lpstrFileTitle 指定的缓冲区。 如果 nFileOffset 指定的值小于零，则文件名无效。 否则，文件名有效，可以使用 nFileExtension 和 nFileOffset ，就像未指定 OFN_NOVALIDATE 标志一样。
OFN_OVERWRITEPROMPT
0x00000002
 如果所选文件已存在，则会导致“ 另存为 ”对话框生成消息框。 用户必须确认是否覆盖文件。
OFN_PATHMUSTEXIST
0x00000800
 用户只能键入有效路径和文件名。 如果使用此标志，并且用户在“ 文件名 ”条目字段中键入了无效的路径和文件名，则对话框函数会在消息框中显示警告。
OFN_READONLY
0x00000001
 在创建对话框时，首先选择“只读检查框。 此标志指示关闭对话框时“只读检查框的状态。
OFN_SHAREAWARE
0x00004000
 指定如果由于网络共享冲突导致 对 OpenFile 函数的调用失败，则忽略该错误，并且对话框将返回所选文件名。 如果未设置此标志，则当用户指定的文件名发生网络共享冲突时，对话框会通知挂钩过程。 如果设置 OFN_EXPLORER 标志，对话框会将 CDN_SHAREVIOLATION 消息发送到挂钩过程。 如果未设置 OFN_EXPLORER，对话框会将 SHAREVISTRING 注册的消息发送到挂钩过程。
OFN_SHOWHELP
0x00000010
 使对话框显示“ 帮助 ”按钮。 hwndOwner 成员必须指定用于接收用户单击“帮助”按钮时对话框发送的 HELPMSGSTRING 注册消息的窗口。 当用户单击“帮助”按钮时，资源管理器样式对话框会向挂钩过程发送CDN_HELP通知消息。

nFileOffset

类型： WORD

从路径开头到 lpstrFile 指向的字符串中文件名的从零开始的偏移量（以字符为单位）。 对于 ANSI 版本，这是字节数;对于 Unicode 版本，这是字符数。 例如，如果 lpstrFile 指向以下字符串“c：\dir1\dir2\file.ext”，则此成员包含值 13 以指示“file.ext”字符串的偏移量。 如果用户选择多个文件， 则 nFileOffset 是第一个文件名的偏移量。

nFileExtension

类型： WORD

从路径开头到 lpstrFile 指向的字符串中文件扩展名的从零开始的偏移量（以字符为单位）。 对于 ANSI 版本，这是字节数;对于 Unicode 版本，这是字符数。 通常，文件扩展名是最后一个点 (“之后的子字符串。) 字符。 例如，txt 是文件名的扩展名 readme.txt，html 是 readme.txt.html 的扩展名。 因此，如果 lpstrFile 指向字符串“c:\dir1\dir2\readme.txt”，则此成员包含值 20。 如果 lpstrFile 指向字符串“c:\dir1\dir2\readme.txt.html”，则此成员包含值 24。 如果 lpstrFile 指向字符串“c:\dir1\dir2\readme.txt.html.”，则此成员包含值 29。 如果 lpstrFile 指向不包含任何“.”字符（如“c：\dir1\dir2\readme”）的字符串，则此成员包含零。

lpstrDefExt

类型： LPCTSTR

默认扩展。 如果用户无法键入扩展名，GetOpenFileName 和 GetSaveFileName 会将此扩展名追加到文件名。 此字符串可以是任意长度，但只追加前三个字符。 字符串不应包含句点 (.) 。 如果此成员为 NULL ，并且用户无法键入扩展，则不会追加任何扩展。

lCustData

类型：LPARAM

系统传递给 由 lpfnHook 成员标识的挂钩过程的应用程序定义数据。 当系统将 WM_INITDIALOG 消息发送到挂钩过程时，消息的 lParam 参数是指向创建对话框时指定的 OPENFILENAME 结构的指针。 挂钩过程可以使用此指针获取 lCustData 值。

lpfnHook

类型： LPOFNHOOKPROC

指向挂钩过程的指针。 除非 Flags 成员包含 OFN_ENABLEHOOK 标志，否则将忽略此成员。

如果未在 Flags 成员中设置OFN_EXPLORER标志，则 lpfnHook 是指向接收用于对话框的消息的 OFNHookProcOldStyle 挂钩过程的指针。 挂钩过程返回 FALSE 以将消息传递到默认对话框过程，或 返回 TRUE 以丢弃消息。

如果设置了 OFN_EXPLORER ， 则 lpfnHook 是指向 OFNHookProc 挂钩过程的指针。 挂钩过程接收从对话框发送的通知消息。 挂钩过程还会接收通过指定子对话模板定义的任何其他控件的消息。 挂钩过程不会接收用于默认对话框的标准控件的消息。

lpTemplateName

类型： LPCTSTR

模块中由 hInstance 成员标识的对话模板资源的名称。 对于编号对话框资源，它可以是 MAKEINTRESOURCE 宏返回的值。 除非在 Flags 成员中设置了OFN_ENABLETEMPLATE标志，否则将忽略此成员。 如果设置了 OFN_EXPLORER 标志，则系统会使用指定的模板创建一个对话框，该对话框是默认资源管理器样式对话框的子级。 如果未设置 OFN_EXPLORER 标志，系统将使用该模板创建替换默认对话框的旧样式对话框。

lpEditInfo

此成员使用 #ifdef _MAC) 有条件地编译 (，因此它仅适用于 Motorola 68K Macintosh 计算机，不适用于 Windows 客户端操作系统。

lpstrPrompt

此成员使用 #ifdef _MAC) 有条件地编译 (，因此它仅适用于 Motorola 68K Macintosh 计算机，不适用于 Windows 客户端操作系统。

pvReserved

类型： void*

此成员是保留的。

dwReserved

类型：DWORD

此成员是保留的。

FlagsEx

类型：DWORD

可用于初始化对话框的一组位标志。 目前，此成员可以为零或以下标志。

值 含义
OFN_EX_NOPLACESBAR
0x00000001
 如果设置了此标志，则不显示位置栏。 如果未设置此标志，资源管理器样式的对话框将包含包含常用文件夹（如收藏夹和桌面）图标的位置栏。

注解

出于兼容性原因，如果 Flags设置为 OFN_ENABLEHOOK 并且 lStructSize OPENFILENAME_SIZE_VERSION_400，则会隐藏Places栏。

注意

commdlg.h 标头将 OPENFILENAME 定义为别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。 将非特定编码别名的使用与非非特定编码的代码混合使用可能会导致不匹配，从而导致编译或运行时错误。 有关详细信息，请参阅 函数原型的约定。

要求

要求 值
最低受支持的客户端 Windows 2000 Professional [仅限桌面应用]
最低受支持的服务器 Windows 2000 Server [仅限桌面应用]
标头 commdlg.h (包括 Windows.h)

另请参阅

通用对话框库

概念性

GetOpenFileName

GetSaveFileName

其他资源

引用

SHGetSpecialFolderLocation