Структура OPENFILENAME содержит информацию, которую используют функции GetOpenFileName и GetSaveFileName, чтобы инициализировать диалоговое окно Открыть (Open) или Сохранить как (Save As). После того как пользователь закроет диалоговое окно, в этой структуре система возвращает информацию о выборе пользователя.
Синтаксис
|
Члены структуры
lStructSize
Определяет длину структуры, в байтах.Windows NT 4.0: В приложении, которое компилировано с WINVER и _WIN32_WINNT> = 0x0500, для этого члена структуры используется OPENFILENAME_SIZE_VERSION_400.
Windows 2000/XP: Для этого параметра используется sizeof (OPENFILENAME).
hwndOwner
Дескриптор окна, которое владеет блоком диалога. Этот член может быть любым допустимым дескриптором окна или может иметь значение ПУСТО (NULL), если у диалогового окна нет владельца.hInstance
Если в члене Flags установлен флажок OFN_ENABLETEMPLATEHANDLE, hInstance является дескриптором объекта памяти, содержащего шаблон диалогового окна. Если установлен флажок OFN_ENABLETEMPLATE, hInstance дескриптор модуля, именованного в члене структуры lpTemplateName, который содержит шаблон диалогового окна. Если ни один флаг не установлен, этот член игнорируется. Если установлен флажок OFN_EXPLORER, система использует заданный шаблон для создания диалогового окна, которое является дочерним блоком диалога в стиле Проводника по умолчанию. Если флажок OFN_EXPLORER не установлен, система использует шаблон для создания диалогового окна в старом стиле, который заменяет блок диалога по умолчанию.lpstrFilter
Указатель на буфер, содержащий пары строк фильтров с нулевым символом в конце. Последняя строка в буфере должна быть завершена двумя символами ПУСТО (NULL).Первая строка в каждой паре - информационная строка, которая описывает фильтр (например, Текстовые файлы (Text Files)), а вторая строка определяет модель фильтра (например, "*.TXT"). Чтобы определить модели сложного фильтра для отдельной информационной строки, используйте точку с запятой, чтобы отделять их (например, " *.TXT; *.DOC; *.BAK "). Строка модели может быть комбинацией допустимых символов имени файла и звездочки (*) в качестве группового символа. Не включайте пробелы в строку модели.
Операционная система не изменяет порядок фильтров. Она показывает их в комбинированном блоке Типы файлов (File Types), по порядку определяемому в члене lpstrFilter.
Если lpstrFilter имеет значение ПУСТО (NULL), диалоговое окно не показывает каких-либо фильтров.
lpstrCustomFilter
Указатель на статический буфер, который содержит пару строк фильтра с нулевым символом в конце для сохранения модели фильтра, выбранного пользователем. Первая строка - информирующая вас строка, которая описывает пользовательский фильтр, а вторая строка - модель фильтра, выбранного пользователем. Первый раз, когда ваша прикладная программа создает диалоговое окно, вы определяете первую строку, которая может быть любой непустой строкой. Когда пользователь выбирает файл, диалоговое окно копирует текущую модель фильтра во вторую строку. Сохраняемая модель фильтра может быть одной из моделей, определяемых в буфере lpstrFilter, или это может быть модель фильтра, введенная с клавиатуры пользователем. Система использует строки, чтобы инициализировать определяемый пользователем фильтр файла, в следующий раз, когда создается диалоговое окно. Если член nFilterIndex нулевой, диалоговое окно использует этот пользовательский фильтр.Если этот член имеет значение ПУСТО (NULL), диалоговое окно не сохраняет определяемые пользователем модели фильтра.
Если этот член структуры - не ПУСТО (NULL), значение члена nMaxCustFilter должно определять размер, в TCHARs, буфера lpstrCustomFilter. Для версии ANSI - это число байтов; для версии Unicode - это число символов.
nMaxCustFilter
Определяет размер, в TCHARs, буфера, идентифицированного членом lpstrCustomFilter. Для версии ANSI - это число байтов; для версии Unicode - это число символов. Этот буфер должен быть, по крайней мере, длиной 40 символов. Если lpstrCustomFilter имеет значение ПУСТО (NULL) или указывает на пустую (NULL) строку, этот элемент игнорируется.nFilterIndex
Определяет индекс текущего выбранного фильтра в органе управления Типы файлов (File Types). Буфер, указанный членом lpstrFilter, содержит пары строк, которые задают фильтры. Первая пара строк имеет индексное значение 1, вторая пара 2, и так далее. Индекс нуля указывает на то, что пользовательский фильтр определен при помощи lpstrCustomFilter. Вы можете определить индекс при вводе данных, чтобы обозначить начальное описание и модель фильтра для диалогового окна. Когда пользователь выбирает файл, член nFilterIndex возвращает значение индекса текущего отображаемого фильтра. Если член nFilterIndex нулевой и lpstrCustomFilter имеет значение ПУСТО (NULL), система использует первый фильтр в буфере lpstrFilter. Если все три члена нулевые или имеют значение ПУСТО (NULL), система не использует какой-либо фильтр и не показывает какие-либо файлы в окне списка файлов диалогового окна.lpstrFile
Указатель на буфер, который содержит имя файла, используемое, чтобы инициализировать поле редактирования Имя файла (File Name). Первый символ этого буфера должен быть ПУСТО (NULL), если в инициализации нет необходимости. Когда функция GetOpenFileName или GetSaveFileName успешно возвращает значение, этот буфер содержит буквенный идентификатор диска, путь, имя и расширение выбранного файла.Если установлен флажок OFN_ALLOWMULTISELECT и пользователь выбирает несколько файлов, буфер содержит текущий каталог, сопровождаемый выбранными именами файлов. В диалоговых окнах в стиле Проводника, каталог и строки имен файлов отделяются значением ПУСТО (NULL), с дополнительным символом ПУСТО (NULL) после последнего имени файла. В диалоговых окнах старого стиля, строки отделяются пробелами и функция использует короткие имена для имен файлов с пробелами. Вы можете использовать функцию FindFirstFile, чтобы преобразовывать длинные и короткие имена файлов. Если пользователь выбирает только один файл, строка lpstrFile не имеет разделителя между путем и именем файла.
Если буфер слишком маленький, функция возвращает значение ЛОЖЬ (FALSE), а функция CommDlgExtendedError возвращает значение FNERR_BUFFERTOOSMALL. В данном случае, первые два байта буфера lpstrFile содержат требуемый размер его, в байтах или символах.
nMaxFile
Определяет размер буфера, в TCHARs, указанного членом lpstrFile. Для версии ANSI - это число байтов; для версии Unicode - это число символов. Буфер должен быть достаточно большим, чтобы сохранить путь и символьную строку или строки имени файла, включая символ завершения строки ('0').Функции GetOpenFileName и GetSaveFileName возвращают значение ЛОЖЬ (FALSE), если буфер слишком маленький, чтобы содержать информацию о файле. Буфер должен быть по крайней мере длиной 256 символов.lpstrFileTitle
Указатель на буфер, который принимает имя файла и расширение (без информации о пути) выбранного файла. Этот элемент может быть значением ПУСТО (NULL).nMaxFileTitle
Определяет размер буфера, в TCHARs, указанного элементом lpstrFileTitle. Для версии ANSI - это число байтов; для версии Unicode - это число символов. Этот элемент игнорируется, если lpstrFileTitle имеет значение ПУСТО (NULL).lpstrInitialDir
Указатель на строку, которая может определить начальный каталог. Алгоритм выбора начального каталога на различных платформах происходит по разному.Windows 2000/XP:
Windows 98/Me:
Более ранние версии Windows и Windows NT:
lpstrTitle
Указатель на строку, которая будет помещена в области заголовка диалогового окна. Если этот элемент имеет значение ПУСТО (NULL), система использует заданный по умолчанию заголовок (то есть Сохранить как (Save As) или Открыть (Open).Flags
Набор битовых флажков, который вы может использовать, чтобы инициализировать диалоговое окно. Когда блок диалога возвращает значение, он устанавливает эти флажки, чтобы обозначить ввод данных от пользователя. Этот член может быть комбинацией следующих флажков.| Флажок | Назначение |
| OFN_ALLOWMULTISELECT | Определяет, что окно со
списком Имя файла (File
Name) дает возможность
многочисленного выбора. Если вы к тому
же установите флажок OFN_EXPLORER,
диалоговое окно использует
пользовательский интерфейс в стиле
Проводника; или же, оно использует
пользовательский интерфейс старого
стиля.
Если пользователь выбирает больше чем один файл, буфер lpstrFile возвращает путь к текущему каталогу, сопровождаемый именами выбранных файлов. Член nFileOffset является смещением, в байтах или символах, от первого имени файла, а член nFileExtension не используется. В диалоговых окнах в стиле Проводника, каталог и строки имени файла отделяются значением ПУСТО (NULL), с дополнительным символом ПУСТО (NULL) после последнего имени файла. Этот формат позволяет диалоговому окну в стиле Проводника возвращать длинные имена файлов, которые включают в себя пробелы. В диалоговых окнах старого стиля каталог и строки имен файлов отделяются пробелами, а функция использует короткие имена для имен файлов с пробелами. Вы можете использовать функцию FindFirstFile, чтобы делать преобразования между длинными и короткими именами файла. Если вы определяете пользовательский шаблон для блока диалога старого стиля, определение окна списка Имя файла (File Name) должно содержать значение LBS_EXTENDEDSEL. |
| OFN_CREATEPROMPT | Если пользователь определяет файл, который не существует, этот флажок заставляет диалоговое окно запросить пользователя о разрешении создать файл. Если пользователь выбирает создание файла, блок диалога закрывается, а функция возвращает заданное имя; в противном случае, диалоговое окно остается открытым. Если Вы используете этот флажок с флажком OFN_ALLOWMULTISELECT, диалоговое окно дает возможность пользователю задавать только один несуществующий файл. |
| OFN_DONTADDTORECENT | Windows 2000/XP: Препятствует системе добавлять связь с выбранным файлом в каталоге файловой системы, который содержит список последних по времени использования пользователем документов. Чтобы получить местоположение этого каталога, вызовите функцию SHGetSpecialFolderLocation с флажком CSIDL_RECENT. |
| OFN_ENABLEHOOK | Подключает функцию фильтр (hook) - процедуры событий, в члене структуры lpfnHook. |
| OFN_ENABLEINCLUDENOTIFY | Заставляет диалоговое окно отправлять уведомительные сообщения CDN_INCLUDEITEM вашей фильтр (hook) - процедуре событий OFNHookProc, когда пользователь открывает папку. Диалоговое окно отправляет уведомление о каждом элементе в недавно открытой папке. Эти сообщения дают возможность Вам управлять выводом элементов на экран в списке элементов папки диалогового окна. |
| OFN_ENABLESIZING | Windows 2000/XP, Windows 98/Me: Включает диалоговое окно в стиле Проводника, размеры которого изменяются при помощи использования или мыши или клавиатуры. По умолчанию, диалоговые окна Открыть (Open) и Сохранить как (Save As) в стиле Проводника дают возможность диалоговому окну изменять размеры независимо от того, устанавливается ли этот флажок. Этот флажок необходим, только в том случае, если Вы предусматриваете фильтр (hook) - процедуру событий или пользовательский шаблон. Диалоговому окну старого стиля не разрешается изменять размеры. |
| OFN_ENABLETEMPLATE | Обозначает то, что член lpTemplateName указывает на имя ресурса шаблона блока диалога в модуле, идентифицированном членом hInstance. Если установлен флажок OFN_EXPLORER, система использует определяемый шаблон, чтобы создать диалоговое окно, которое является дочерним для заданного по умолчанию блока диалога в стиле Проводника. Если флажок OFN_EXPLORER не установлен, система использует шаблон, чтобы создать диалоговое окно старого стиля, которое заменяет заданный по умолчанию блок диалога. |
| OFN_ENABLETEMPLATEHANDLE | Указывает на то, что член hInstance идентифицирует блок данных, который содержит предварительно загруженный шаблон диалогового окна. Система игнорирует член lpTemplateName, если этот флажок установлен. Если установлен флажок OFN_EXPLORER, система использует определяемый шаблон, чтобы создать блок диалога, который является дочерним для заданного по умолчанию диалогового окна в стиле Проводника. Если флажок OFN_EXPLORER не установлен, система использует шаблон, чтобы создать блок диалога старого стиля, которое заменяет заданное по умолчанию диалоговое окно. |
| OFN_EXPLORER | Обозначает, что любые
настройки, сделанные в диалоговом окне Открыть
(Open) или
Сохранить как (Save As)
используют новые методы настройки в
стиле Проводника. Для получения
дополнительной информации, см. статьи Фильтр-процедуры
(hooks)
для стиля Проводника
и Пользовательские
шаблоны для стиля Проводника.
По умолчанию, диалоговые окна Открыть (Open) и Сохранить как (Save As) используют пользовательский интерфейс в стиле Проводника независимо от того, установлен ли этот флажок. Этот флажок необходим, только в том случае, если вы предусматриваете фильтр (hook) - процедуру или пользовательский шаблон или устанавливаете флажок OFN_ALLOWMULTISELECT. Если вы хотите иметь пользовательский интерфейс старого стиля, не включайте флажок OFN_EXPLORER и предусмотрите замену шаблоном или фильтр (hook) - процедурой старого стиля. Если вы хотите иметь старый стиль, но не нуждаетесь в пользовательском шаблоне или фильтр (hook) - процедуре, просто подключите фильтр (hook) - процедуру, которая всегда возвращает значение ЛОЖЬ (FALSE). |
| OFN_EXTENSIONDIFFERENT | Определяет, что пользователь ввел с клавиатуры расширение имени файла, которое отличается от расширения, заданного при помощи lpstrDefExt. Функция не использует этот флажок, если lpstrDefExt имеет значение ПУСТО (NULL). |
| OFN_FILEMUSTEXIST | Определяет, что пользователь может вводить с клавиатуры имена только существующих файлов в поле ввода Имя файла (File Name). Если этот флажок определен, а пользователь вводит недопустимое имя, процедура диалогового окна показывает на экране предупреждение в окне сообщений. Если этот флажок определен, используется также и флажок OFN_PATHMUSTEXIST. |
| OFN_FORCESHOWHIDDEN | Windows 2000/XP: Заставляет показывать системные и скрытые файлы, в соответствии с этим пользовательская установка показывать или не показывать скрытые файлы отменяется. Однако, файл, который отмечен как и системный и скрытый, не показывается. |
| OFN_HIDEREADONLY | Скрывается окошко флажка Только для чтения (Read Only). |
| OFN_LONGNAMES | В диалоговых окнах старого стиля этот флажок заставляет блок диалога использовать длинные имена файлов. Если этот флажок не установлен или, если также установлен и флажок OFN_ALLOWMULTISELECT, диалоговое окно старого стиля для имен файлов с пробелами использует короткие имена файлов (формат 8.3). Диалоговое окно в стиле Проводника игнорирует этот флажок и всегда показывает длинные имена файлов. |
| OFN_NOCHANGEDIR | Восстанавливает
текущий каталог в первоначальном
значении, если пользователь изменил
каталог при поиске файлов.
Windows NT 4.0/2000/XP: Этот флажок неэффективен для функции GetOpenFileName. |
| OFN_NODEREFERENCELINKS | Предписывает диалоговому окну возвратить путь и имя файла выбранного ярлыка (.LNK) файла. Если это значение не определено, блок диалога возвращает путь и имя файла, вызываемого ярлыком. |
| OFN_NOLONGNAMES | В диалоговых окнах старого стиля этот флаг заставляет блок диалога использовать короткие имена файлов (формат 8.3). Диалоговые окна в стиле Проводника игнорируют этот флажок и всегда показывают длинные имена файлов. |
| OFN_NONETWORKBUTTON | Скрывает и отключает кнопку Сеть (Network). |
| OFN_NOREADONLYRETURN | Определяет, что возвращенное значение файла не имеет отметки в окошке флажка Только для чтения (Read Only) и он не в каталоге защищенном от записи. |
| OFN_NOTESTFILECREATE | Определяет, что перед закрытием диалогового окна файл не создается. Этот флажок должен быть определен, если прикладная программа сохраняет файл на создаваемой без модификации совместно используемой сети. Когда прикладная программа определяет этот флажок, библиотека не проверяет защиту от записи, переполнение диска, открытие доступа к диску или сетевую защиту. Прикладные программы используя этот флажок должны с большой осторожностью исполнять системный файл, потому что файл не может быть вновь открыт, как только он закроется. |
| OFN_NOVALIDATE | Определяет, что стандартные диалоговые окна позволяют запрещенные символы в возвращаемом имени файла. Обычно, вызывающая программа использует фильтр (hook) - процедуру, которая проверяет имя файла при помощи использования сообщения FILEOKSTRING. Если текстовое поле в окне редактирования пустое или ничего не содержит, кроме пробелов, списки файлов и каталоги модифицируются. Если текстовое поле в окне редактирования содержит что-нибудь еще, члены nFileOffset и nFileExtension устанавливаются в значения, созданные при синтаксическом анализе текста. Заданное по умолчанию расширение в текст не добавляется , и при этом текст не скопируется в буфер, определенный членом lpstrFileTitle. Если это значение, определенное при помощи члена nFileOffset, меньше чем нуль, имя файла ошибочное. Или же, имя файла правильное и члены nFileExtension и nFileOffset могут быть использованы, как будто флажок OFN_NOVALIDATE не был установлен. |
| OFN_OVERWRITEPROMPT | Если выбранный файл уже существует, заставляет диалоговое окно Сохранить как (Save As) создать окно сообщений. Пользователь должен подтвердить, переписывать ли заново файл. |
| OFN_PATHMUSTEXIST | Определяет, что пользователь может вводить с клавиатуры только допустимые пути и имена файла. Если этот флажок используется, а пользователь вводит с клавиатуры ошибочный путь и имя файла в поле ввода Имя файла (File Name), функция диалогового окна показывает на экране в окне сообщений предупреждение. |
| OFN_READONLY | При создании диалогового окна заставляет окошко флажка Только для чтения (Read Only) изначально быть выбранным. Этот флажок указывает состояние окошка флажка Только для чтения (Read Only), когда блок диалога закрывается. |
| OFN_SHAREAWARE | Определяет, что если вызов функции OpenFile не выполняет задачу из-за сетевой ошибки совместного доступа, ошибка игнорируется, а диалоговое окно возвращает выбранное имя файла. Если этот флажок не установлен, блок диалога сообщает вашей фильтр (hook) - процедуре, когда происходит сетевая ошибка совместного доступа, имя файла, определенное пользователем. Если вы установили флажок OFN_EXPLORER, диалоговое окно отправляет сообщение CDN_SHAREVIOLATION фильтр (hook) - процедуре. Если вы не установили OFN_EXPLORER, блок диалога отправляет зарегистрированное сообщение SHAREVISTRING фильтр (hook) - процедуре. |
| OFN_SHOWHELP | Заставляет диалоговое окно показать на экране кнопку Справка (Help). Член hwndOwner должен определить окно, принимающее зарегистрированные сообщения HELPMSGSTRING, которые блок диалога отправляет, когда пользователь щелкает по кнопке Справка (Help). Диалоговое окно в стиле Проводника отправляет вашей фильтр (hook) - процедуре уведомляющее сообщение CDN_HELP, когда пользователь щелкает по кнопке Справка (Help). |
nFileOffset
Определяет отсчитываемое от нуля, в TCHARs, смещение от начала пути до имени файла в строке, указанной элементом lpstrFile. Для версии ANSI - это число байтов; для версии Unicode - это число символов. Например, если lpstrFile указывает на следующую строку, "c:\dir1\dir2\file.ext", этот член содержит значение 13, чтобы обозначить смещение строки "file.ext". Если пользователь выбирает больше, чем один файл, nFileOffset - смещение до первого имени файла.nFileExtension
Определяет отсчитываемое от нуля, в TCHARs, смещение от начала пути до расширения имени файла в строке, указанной элементом lpstrFile. Для версии ANSI - это число байтов; для версии Unicode - это число символов. Например, если lpstrFile указывает на следующую строку, "c:\dir1\dir2\file.ext", этот член содержит значение 18. Если пользователь не вводил с клавиатуры расширение и lpstrDefExt имеет значение ПУСТО (NULL), этот член определяет смещение, которое завершается символом нуля. Если пользователь ввел с клавиатуры "." в качестве последнего символа в имени файла, этот член определяется как нуль.lpstrDefExt
Указатель на буфер, который содержит заданное по умолчанию расширение. Функции GetOpenFileName и GetSaveFileName это расширение добавляют в конец имени файла, если пользователь не выполнил ввода расширения с клавиатуры. Эта строка может быть любой длины, но добавляются только первые три символа. Строка не должна содержать точку (.). Если этот элемент имеет значение ПУСТО (NULL), а пользователь не выполняет ввода расширения с клавиатуры , в конец имени файла никакого расширения не добавляется.lCustData
Определяет заданные программой данные, которые система пересылает фильтр (hook) - процедуре, идентифицированной членом lpfnHook. Когда система отправляет сообщение WM_INITDIALOG фильтр (hook) - процедуре, параметр сообщения lParam - указатель на структуру OPENFILENAME, определяемую, когда создавалось диалоговое окно. Фильтр-процедура (hook) может использовать этот указатель, чтобы получить значение элемента lCustData.lpfnHook
Указатель на фильтр (hook) - процедуру. Этот член игнорируется, если член Flags не включает в себя флажок OFN_ENABLEHOOK.Если флажок OFN_EXPLORER не установлен в члене Flags, lpfnHook - указатель на фильтр (hook) - процедуру OFNHookProcOldStyle, которая принимает сообщения, предназначенные для диалогового окна. Фильтр-процедура (hook) возвращает значение ЛОЖЬ (FALSE), чтобы переслать сообщение заданной по умолчанию процедуре диалогового окна, или значение ИСТИНА (TRUE), чтобы сбросить сообщение.
Если флажок OFN_EXPLORER установлен, lpfnHook - указатель на фильтр (hook) - процедуру OFNHookProc. Фильтр-процедура (hook) получает уведомляющие сообщения, отправленные из диалогового окна. Фильтр-процедура (hook) к тому же получает сообщения и для любых дополнительных органов управления, которые вы определили, устанавливая шаблон дочернего блока диалога. Фильтр-процедура (hook) не получает сообщения, предназначенные для заданных по умолчанию стандартных органов управления диалогового окна.
lpTemplateName
Указатель на строку с символом нуля в конце, которая именует ресурс шаблона блока диалога в модуле, идентифицированном членом hInstance. Для пронумерованных ресурсов диалогового окна, это может быть значение, возвращенное макрокомандой MAKEINTRESOURCE. Этот член игнорируется, если в члене Flags не установлен флажок OFN_ENABLETEMPLATE. Если установлен флажок OFN_EXPLORER, система использует заданный шаблон, чтобы создать диалоговое окно, которое является дочерним для заданного по умолчанию диалогового окна в стиле Проводника. Если флажок OFN_EXPLORER не установлен, система использует шаблон, чтобы создать блок диалога старого стиля, которое заменяет заданное по умолчанию диалоговое окно.pvReserved
Зарезервирован. Должен устанавливаться в 0.dwReserved
Зарезервирован. Должен устанавливаться в 0.FlagsEx
Windows 2000/XP: Установка битов флажка, которые Вы можете использовать, чтобы инициализировать диалоговое окно. В настоящее время, этот член структуры может быть нулем или нижеследующим флажком.| Флажок | Назначение |
| OFN_EX_NOPLACESBAR | Если этот флажок устанавливается, панель мест не показывается на экране. Если этот флажок не установлен, диалоговые окна в стиле Проводника включают панель мест, содержащую изображения обычно используемых папок, типа Фавориты (Favorites) и Рабочий стол (Desktop). |
Замечания
По причинам совместимости, Панель мест ( Places Bar) скрывается, если член структуры Flags установлен в OFN_ENABLEHOOK, а lStructSize - OPENFILENAME_SIZE_VERSION_400.
Смотри также
Обзор Библиотека стандартных диалоговых окон, Структуры, используемые библиотекой стандартных диалоговых окон, GetOpenFileName, GetSaveFileName, SHGetSpecialFolderLocation
|
Размещение и совместимость OPENFILENAME |
|
|
Windows. NET Server |
Да |
|
Windows XP |
Да |
|
Windows 2000 |
Да |
|
Windows NT |
Да версии 3.1 и выше |
|
Windows Me |
Да |
|
Windows 98 |
Да |
|
Windows 95 |
Да |
|
Заголовочный файл |
|
|
- объявлено в |
Commdlg.h |
|
- включено в |
Windows.h |
|
Unicode |
Нет |
|
Замечания по платформе |
Не имеется |