OPENFILENAME结构包含了GetOpenFileName和GetSaveFileName函 数用来初始化打开或另存为对话框的信息。在用户关闭对话框后,系统返回关于用户的选择信息到这个结构中。
typedef struct tagOFN {
DWORDlStructSize;
HWNDhwndOwner;
HINSTANCEhInstance;
LPCTSTRlpstrFilter;
LPTSTRlpstrCustomFilter;
DWORDnMaxCustFilter;
DWORDnFilterIndex;
LPTSTRlpstrFile;
DWORDnMaxFile;
LPTSTRlpstrFileTitle;
DWORDnMaxFileTitle;
LPCTSTRlpstrInitialDir;
LPCTSTRlpstrTitle;
DWORDFlags;
WORDnFileOffset;
WORDnFileExtension;
LPCTSTRlpstrDefExt;
LPARAMlCustData;
LPOFNHOOKPROClpfnHook;
LPCTSTRlpTemplateName;
#if (_WIN32_WINNT >= 0x0500)
void *pvReserved;
DWORDdwReserved;
DWORDFlagsEx;
#endif // (_WIN32_WINNT >= 0x0500)
} OPENFILENAME, *LPOPENFILENAME;
Windows 95/98和Windows NT 4.0:特意为Windows 95/98或Windows NT 4.0,及带有WINVER和_WIN32_WINNT >= 0x0500编译时,为这个成员使用OPENFILENAME_SIZE_VERSION_400。
Windows 2000及更高版本:这个参数使用sizeof (OPENFILENAME) 。
如果OFN_EXPLORER标记被设置,系统使用Explorer风格的默认对话框的子窗口作为指定模板来建立一个对话框。如果 OFN_EXPLORER标记没有被设置,系统使用模板建立一个旧风格的对话框。
第一个字符串是过滤器描述的显示字符串(例如,“文本文件”),第二个字符指定过滤样式(例如,“*.TXT”)。要为一个显示字符串指定多个过滤 样式,使用分号(“;”)分隔样式(例如,“*.TXT;*.DOC;*.BAK”)。一个样式字符串中可以包含有效的文件名字字符及星号(*)通配符。 不能在样式字符串中包含空格。
系统不能改变过滤器的次序。它按lpstrFilter指定的次序显示在文件类型组合框中。
如果lpstrFilter是NULL,对话框不能显示任何过滤器。
如果这个成员是NULL,对话框不能保留用户自定义过滤器样式。
如果这个成员不是NULL,nMaxCustFilter成员的值必须指定以TCHARs为单位的lpstrCustomFilter缓 冲的大小。对于ANSI版本,是字节的个数;对于Unicode版本,是字符的个数。
如果nFilterIndex是0及lpstrCustomFilter是NULL,系统使用在lpstrFilter缓 冲中的第一个过滤器。如果所有的三个成员都是0或NULL,系统不使用任何过滤器,在对话框的列表文件中不显示任何文件。
如果OFN_ALLOWMULTISELECT标记被设置并且用户选择了多个文件,缓冲包含了当前目录下被选择文件的文件名。对于Explorer 风格对话框,目录和文件名字符串是被NULL分开的,在文件名之后有一个额外的NULL。对于旧风格对话框,字符串是被空格分开的并且函数为带有空格的文 件名使用短文件名。你可以使用FindFirstFile函 数在长短文件名之间转换。如果用户只选择了一个文件,lpstrFile字符串在路径和文件名之间没有分隔。
如果缓冲太小,函数返回FALSE并且CommDlgExtendedError函 数返回FNERR_BUFFERTOOSMALL.。既然这样,lpstrFile缓冲的首先两个字节包含必需的大小(字节或字符)。
Windows 2000:
Windows 98:
Windows和Windows NT/ 2000的早期版本:
标记 | 含意 |
---|---|
OFN_ALLOWMULTISELECT | 指定文件名列表框允许多选。如果同时你设置了OFN_EXPLORER标记,对话框使用Explorer风格用户界面; 否则它使用旧风格用户界面。 如果用户选择了一个以上的文件,lpstrFile缓冲返回当前目录下所有被选择的文件的文件名。nFileOffset成 员是到第一个文件名的偏移量(字节或字符),并且nFileExtension成员不被使用。对于Explorer风格对话框,目录和文件 名是被NULL分隔的,在最后的文件名后带有额外的NULL。这个格式使Explorer风格的对话框能返回包含空格的长文件名。对于旧风格对话框,目录 和文件字符串是被空格分隔的,函数为带有空格的文件名使用短文件名。你可以使用FindFirstFile函数在短文件名和长文件名之间 转换。 如果你为一个旧风格对话框指定了一个定制的模板,文件名列表框的定义必须包含LBS_EXTENDEDSEL值。 |
OFN_CREATEPROMPT | 如果用户指定了一个不存在的文件,这个标记使用对话框能提示用户是否新建这个文件。如果用户选择了新建这个文件,对话框 关闭并且函数返回指定的名字;否则,对话框继续停留。如果你使用带有OFN_ALLOWMULTISELECT标记的这个标记,对话框允许用户去指定一个 不存在的文件。 |
OFN_DONTADDTORECENT | Windows 2000:防止系统为选择的文件增加快捷链接到最近使用文档中。要找回目录的位置,调用 还有CSIDL_RECENT标记的SHGetSpecialFolderLocation函 数。 |
OFN_ENABLEHOOK | 激活在lpfnHook成员中指定的钩子函数。 |
OFN_ENABLEINCLUDENOTIFY | Windows 2000:当用户打开一个文件夹时,引起对话框发送CDN_INCLUDEITEM通 知消息到你的OFNHookProc程 序。对话框为在最近打开的文件夹中的每一个项目发送一个通知。这些消息使你能够控制那些在对话框中显示的文件夹项目的列表。 |
OFN_ENABLESIZING | Windows 2000,Windows 98:使Explorer风格的对话框可以使用鼠标或键盘调 整大小。缺省时,Explorer风格的打开和另存为对话框允许被调整大小,不顾这个标记是否被设置。这标记仅在你提供了一个钩子程序或定制模板时是必需 的。旧风格的对话框不允许调整大小。 |
OFN_ENABLETEMPLATE | 指出lpTemplateName成员是指向对话框模板资源的名字,这个模板资源在能被hInstance成 员识别的模块中。 如果OFN_EXPLORER标记被设置,系统使用指定的模板去建立一个对话框,是默认Explorer风格对话框的子窗口。如果 OFN_EXPLORER标记没有被设置,系统使用旧风格的对话框替代默认的对话框。 |
OFN_ENABLETEMPLATEHANDLE | 指出hInstance成员能识别的包含预载对话框模板的数据块。如果这个标记被指定的,系统忽略lpTemplateName。 如果OFN_EXPLORER标记被设置,系统使用指定的模板去建立一个对话框,是默认Explorer风格对话框的子窗口。如果 OFN_EXPLORER标记没有被设置,系统使用模板去建立一个旧风格对话框替代默认对话框。 |
OFN_EXPLORER | 指出任何打开或另存为对话框使用新的Explorer风格的用户化模块。关于更多的信息,参见Explorer-Style. Hook Procedures和Explorer-Style. Custom Templates。 缺省下,打开和另存为对话框使用Explorer风格用户界面,不顾这个标记是否设置。这个标记仅在你提供了一个钩子程序或定制模板或设置了 OFN_ALLOWMULTISELECT标记时是必需的。 如果你想使用旧风格的界面,省略OFN_EXPLORER 标记,并且提供一个代替的旧风格模板或钩子程序。如果你想用旧风格但不需要一个定制模板或钩子程序,简单的提供一个钩子程序,让它返回FALSE。 |
OFN_EXTENSIONDIFFERENT | 指定用户输入的一个文件的扩展名与lpstrDefExt指定的扩展名不同。如果lpstrDefExt是 NULL,函数不使用这个标记。 |
OFN_FILEMUSTEXIST | 指定用户仅可以在文件名登录字段中输入已存在的文件的名字。如果这个标记被指定的并且用户输入了一个无效的名字,对话框 程序显示一个等待消息框。如果这个标记被指定,OFN_PATHMUSTEXIST标记也被使用。 |
OFN_FORCESHOWHIDDEN | Windows 2000:强制显示系统和隐藏属性的文件,从而压倒用户设置的显示或不显示隐藏文件。否 则,带有系统和隐藏标记的文件不被显示。 |
OFN_HIDEREADONLY | 隐藏只读复选框。 |
OFN_LONGNAMES | 对于旧风格对话框,这个标记引起对话框使用长文件名。如果这个标记没有被指定,或如果 OFN_ALLOWMULTISELECT标记也被设置,旧风格对话框为带有空格的文件名使用短文件名(8.3格式)。 Explorer风格对话框忽略这个标记,通常显示长文件名。 |
OFN_NOCHANGEDIR | 如果当搜索文件时用户改变了目录的时候,恢复当前目录到它的初始值。 |
OFN_NODEREFERENCELINKS | 引导对话框为选择的快捷方式(.LNK)文件返回路径和文件名。如果这个值没有被指定,对话框返回这个快捷方式所引用文 件的路径和文件名。 |
OFN_NOLONGNAMES | 对于旧风格对话框,这个标识引起对话框去使用短文件名(8.3格式)。 Explorer风格对话框忽略这个标记,通常显示长文件名。 |
OFN_NONETWORKBUTTON | 隐藏和显示风格按钮。 |
OFN_NOREADONLYRETURN | 指定返回的文件不带有只读复选框,不是在写保护的目录中。 |
OFN_NOTESTFILECREATE | 指定文件不是在对话框关闭前建立的。如果应用程序保存文件到一个建立的非映象风格共享上,这个标记应该被指定的。当一个 应用程序指定了这标记,库不能检查写保护,磁盘满,打开驱动器门或网络保护。应用程序使用这个标记必须小心执行文件操作,因为一旦文件被关闭,它不能重新 打开。 |
OFN_NOVALIDATE | 指定公共对话框允许在返回的文件名中有无效的字符。典型的,正在调用的程序使用一个钩子程序通过FILEOKSTRING消 息检查文件名。如果在编辑控件中的文本框是空的或只包含了空格,那么文件和目录列表框是被更新的。如果编辑控件中的文本框包含了别的东西,那么nFileOffset 和nFileExtension的设置值是通过分析文本产生的。没有默认的扩展名被添加到文本,也没有文本被复制到lpstrFileTitle指 定的缓冲。 如果通过nFileOffset指定的值比0小,文件是无效的。否则,文件名是有效的。如果OFN_NOVALIDATE没有被指 定,nFileExtension和nFileOffset可以被使用。 |
OFN_OVERWRITEPROMPT | 如果选择的文件已经存在,使用另存为对话框产生一个消息框。用户必须确认是否复盖这个文件。 |
OFN_PATHMUSTEXIST | 指定用户仅能输入的路径和文件名。如果这个标记被使用并且用户在文件名输入字段中键入了一个用效的路径和文件名,对话框 函数显示一个等待消息。 |
OFN_READONLY | 当对话框建立时,显示被选择的只读复选框。这个标记指出当对话框被关闭时只读复选框的状态。 |
OFN_SHAREAWARE | 指出如果调用OpenFile函 数因为网络共享冲突而失败,这个错误被忽略并且对话框返回选择的文件名。 如果这个标记没有被设置,当用户选择的文件名发生网络共享冲突时,对话框发送通知到你的钩子程序。如果你设置了OFN_EXPLORER标记,对话 框发送CDN_SHAREVIOLATION消 息到钩子程序。如果你没有设置OFN_EXPLORER,对话框发送SHAREVISTRING注 册的消息到钩子程序。 |
OFN_SHOWHELP | 使对话框显示帮助按钮。hwndOwner成员必须指定一个窗口,这个窗口作为接收对话框发送的HELPMSGSTRING注 册的消息,当用户单击帮助按钮时对话框发送这个消息。 当用户单击帮助按钮时,一个Explorer风格的对话框发送CDN_HELP通 知消息到你的钩子程序。 |
如果用户选择了多于一个的文件,nFileOffset是到第一个文件名的偏移。
如果在Flags成员中OFN_EXPLORER标记没有被设置,lpfnHook指向一个OFNHookProcOldStyle钩 子程序,这个程序有意的从对话框接收消息。钩子程序返回FALSE传递一个消息到默认的对话框程序或返回TRUE丢弃消息。
如果OFN_EXPLORER被设置,lpfnHook指向一个OFNHookProc钩 子程序。这个钩子程序接收从对话框发出的通知消息。这个钩子程序也接收你通过一个子对话框模板定义的附加控件的消息。钩子程序不有意接收默认对话框的标准 控件的消息。
如果OFN_EXPLORER标记被设置,系统使用指定的模板去建立一个对话框,是默认Explorer风格对话框的子窗口。如果 OFN_EXPLORER标记没有被设置,系统使用模板去建立一个旧风格的对话框来替代默认对话框。
标记 | 含意 |
---|---|
OFN_EX_NOPLACESBAR | 如果这个标记被设置,则位置栏被不显示。如果这个标记没有设置,则Explorer风格的对话框包含一般使用文件图标的 位置栏,例如像收藏夹和桌面。 |