通过

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

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

lpstrFilter

类型：LPCTSTR

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

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

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

如果 lpstrFilterNULL，则对话框不会显示任何筛选器。

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

lpstrCustomFilter

类型：LPTSTR

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

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

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

nMaxCustFilter

类型：DWORD

lpstrCustomFilter标识的缓冲区的大小（以字符为单位）。 此缓冲区长度应至少为 40 个字符。 如果 lpstrCustomFilterNULL 或指向 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指向的缓冲区的大小（以字符为单位）。 如果 lpstrFileTitleNULL，则忽略此成员。

lpstrInitialDir

类型：LPCTSTR

初始目录。 选择初始目录的算法因不同平台而异。

Windows 7：

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

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
 指示对 打开 或 另存为 对话框中所做的任何自定义项都使用资源管理器样式的自定义方法。 有关详细信息，请参阅 Explorer-Style 挂钩过程 和 Explorer-Style 自定义模板。

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

如果需要旧式用户界面，请省略 OFN_EXPLORER 标志并提供替换旧样式模板或挂钩过程。 如果想要旧样式，但不需要自定义模板或挂钩过程，只需提供始终返回 FALSE的挂钩过程。
OFN_EXTENSIONDIFFERENT
0x00000400
 用户键入的文件扩展名不同于 lpstrDefExt指定的扩展名。 如果 lpstrDefExtNULL，则该函数不使用此标志。
OFN_FILEMUSTEXIST
0x00001000
 用户只能在 文件名 输入字段中键入现有文件的名称。 如果指定了此标志，并且用户输入了无效的名称，则对话框过程会在消息框中显示警告。 如果指定了此标志，则还会使用 OFN_PATHMUSTEXIST 标志。 此标志可在 “打开”对话框中使用。 它不能与 另存为 对话框一起使用。
OFN_FORCESHOWHIDDEN
0x10000000
 强制显示系统和隐藏文件，从而重写用户设置以显示或不显示隐藏文件。 但是，不会显示标记为系统和隐藏的文件。
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
 在关闭对话框之前，不会创建该文件。 如果应用程序将文件保存在创建非修改网络共享上，则应指定此标志。 当应用程序指定此标志时，库不会检查写入保护、完整磁盘、打开的驱动器门或网络保护。 使用此标志的应用程序必须仔细执行文件操作，因为文件在关闭后无法重新打开。
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

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

如果未在 标志 成员中设置 OFN_EXPLORER 标志，lpfnHook 是指向接收对话框所要消息的 OFNHookProcOldStyle 挂钩过程的指针。 挂钩过程返回 FALSE 将消息传递给默认对话框过程，或 TRUE 放弃消息。

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

lpTemplateName

类型：LPCTSTR

hInstance 成员标识的模块中的对话框模板资源的名称。 对于编号对话框资源，此值可以是由 MAKEINTRESOURCE 宏 返回的值。 除非在 标志 成员中设置 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
 如果设置了此标志，则不显示位置栏。 如果未设置此标志，则资源管理器样式对话框包括一个位置栏，其中包含常用文件夹（如收藏夹和桌面）的图标。

言论

出于兼容性原因，如果 标志 设置为 OFN_ENABLEHOOK，lStructSizeOPENFILENAME_SIZE_VERSION_400，则会隐藏“位置栏”。

注意

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

要求

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

另请参阅

通用对话框库

概念

GetOpenFileName

GetSaveFileName

其他资源

参考

SHGetSpecialFolderLocation