Win32 API. Справочник по стандартному диалоговому окну
Страница 25. Структура OPENFILENAME
Страница 25 из 59

Структура OPENFILENAME

Структура OPENFILENAME содержит информацию, которую используют функции GetOpenFileName и GetSaveFileName, чтобы инициализировать стандартное диалоговое окно Открыть (Open) или Сохранить как… (Save As). После того как пользователь закроет диалоговое окно, система возвращает информацию о выборе пользователя в эту структуру.

Синтаксис

typedef struct tagOFN 
{ 
DWORD lStructSize;
HWND hwndOwner;
HINSTANCE hInstance;
LPCTSTR lpstrFilter;
LPTSTR lpstrCustomFilter;
DWORD nMaxCustFilter;
DWORD nFilterIndex;
LPTSTR lpstrFile;
DWORD nMaxFile;
LPTSTR lpstrFileTitle;
DWORD nMaxFileTitle;
LPCTSTR lpstrInitialDir;
LPCTSTR lpstrTitle;
DWORD Flags;
WORD nFileOffset;
WORD nFileExtension;
LPCTSTR lpstrDefExt;
DWORD lCustData;
LPOFNHOOKPROC lpfnHook;
LPCTSTR lpTemplateName;
} OPENFILENAME;

Элементы
lStructSize
Определяет длину структуры в байтах.
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 должно определить размер, в байтах (версия ANSI) или символах (версия Уникода), буфера lpstrCustomFilter.
nMaxCustFilter
Определяет размер, в байтах или символах, буфера, идентифицированного элементом lpstrCustomFilter. Этот буфер должен быть, по крайней мере, длиной 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, чтобы преобразовывать длинные и короткие имена файлов.
Если буфер слишком маленький, функция возвращает значение ЛОЖЬ (FALSE), а функция CommDlgExtendedError возвращает значение FNERR_BUFFERTOOSMALL. В данном случае, первые два байта буфера lpstrFile содержат требуемый размер, в байтах или символах.
nMaxFile
Определяет размер буфера, в байтах (версия ANSI) или символах (версия Уникода), указанного элементом lpstrFile. Функции GetOpenFileName и GetSaveFileName возвращают значение ЛОЖЬ (FALSE), если буфер слишком маленький, чтобы содержать информацию о файле. Буфер должен быть по крайней мере длиной 256 символов.
lpstrFileTitle
Указатель на буфер, который принимает имя файла и расширение (без информации о пути) выбранного файла. Этот элемент может быть значением ПУСТО (NULL).
nMaxFileTitle
Определяет размер буфера, в байтах (версия ANSI) или символы (версия Уникода), указанного элементом lpstrFileTitle. Этот элемент игнорируется, если lpstrFileTitle имеет значение ПУСТО (NULL).
lpstrInitialDir
Указатель на строку, которая определяет начальный каталог файлов. Если этот элемент имеет значение ПУСТО (NULL), система использует текущий каталог как исходный каталог.
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_ENABLEHOOK - Разрешает работу фильтр - процедуры, определяемой в элементе lpfnHook.
  • OFN_ENABLETEMPLATE - Обозначает то, что элемент lpTemplateName указывает на название ресурса шаблона блока диалога в модуле, идентифицированном элементом hInstance. Если установлен флажок OFN_EXPLORER, система использует определяемый шаблон, чтобы создать диалоговое окно, которое является дочерним для заданного по умолчанию блока диалога в стиле Проводника. Если флажок OFN_EXPLORER не установлен, система использует шаблон, чтобы создать диалоговое окно старого стиля, которое заменяет заданный по умолчанию блок диалога.
  • OFN_ENABLETEMPLATEHANDLE - Указывает на то, что элемент hInstance идентифицирует блок данных, который содержит предварительно загруженный шаблон диалогового окна. Система игнорирует элемент lpTemplateName, если этот флажок установлен. Если установлен флажок OFN_EXPLORER, система использует определяемый шаблон, чтобы создать блок диалога, который является дочерним для заданного по умолчанию диалогового окна в стиле Проводника. Если флажок OFN_EXPLORER не установлен, система использует шаблон, чтобы создать блок диалога старого стиля, которое заменяет заданное по умолчанию диалоговое окно.
  • OFN_EXPLORER - Обозначает, что любые настройки, сделанные в диалоговом окне Открыть (Open) или Сохранить как (Save As) используют новые методы настройки в стиле Проводника. Для получения дополнительной информации, см. статьи обзора Библиотеки стандартного диалогового окна " Фильтр (hook) - процедуры в стиле Проводника " и "Пользовательские шаблоны в стиле Проводника". По умолчанию, диалоговые окна Открыть (Open) и Сохранить как (Save As) используют пользовательский интерфейс в стиле Проводника независимо от того, установлен ли этот флажок. Этот флажок необходим, только в том случае, если вы предоставляете фильтр (hook) - процедуру или пользовательский шаблон или устанавливаете флажок OFN_ALLOWMULTISELECT. Если вы хотите иметь пользовательский интерфейс старого стиля, не включайте флажок OFN_EXPLORER и обеспечте замену шаблоном или фильтр (hook) - процедурой старого стиля. Если вы хотите иметь старый стиль, но не нуждаетесь в пользовательском шаблоне или фильтр (hook) - процедуре, просто предоставьте фильтр (hook) - процедуру, которая всегда возвращает значение ЛОЖЬ (FALSE).
  • OFN_EXTENSIONDIFFERENT - Определяет, что пользователь ввел с клавиатуры расширение имени файла, которое отличается от расширения, заданного при помощи lpstrDefExt. Функция не использует этот флажок, если lpstrDefExt имеет значение ПУСТО (NULL).
  • OFN_FILEMUSTEXIST - Определяет, что пользователь может вводить с клавиатуры только имена файлов существующих в поле ввода Имя файл (File Name). Если этот флажок определен, а пользователь вводит недопустимое название, процедура диалогового окна показывает на экране предупреждение в окне сообщений. Если этот флажок определен, флажок OFN_PATHMUSTEXIST также используется.
  • OFN_HIDEREADONLY - Скрывает отмечаемое "галочкой" окошко Только для чтения (Read Only).
  • OFN_LONGNAMES - В диалоговых окнах старого стиля этот флажок заставляет блок диалога использовать длинные имена файлов. Если этот фложок не определен или, если флажок OFN_ALLOWMULTISELECT также установлен, диалоговое окно старого стиля для названий файлов с пробелами использует короткие имена файлов (формат 8.3). Диалоговое окно в стиле Проводника игнорирует этот флажок и всегда показывает длинные имена файлов.
  • OFN_NOCHANGEDIR - Восстанавливает текущий каталог в первоначальном значении, если пользователь изменил каталог при поиске файлов.
  • 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
Определяет отсчитываемое от нуля смещение от начала пути до имени файла в строке, указанной элементом lpstrFile. Например, если lpstrFile указывает на следующуюя строку, "c:\dir1\dir2\file.ext", этот элемент содержит значение 13, чтобы обозначить смещение строки "file.ext".
nFileExtension
Определяет отсчитываемое от нуля смещение от начала пути до расширения имени файла в строке, указанной элементом lpstrFile. Например, если 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, lpfnHookhook) - процедуру OFNHookProcOldStyle, которая принимает сообщения, предназначенные для диалогового окна. Фильтр (hook) - процедура возвращает значение ЛОЖЬ (FALSE), чтобы переслать сообщение заданной по умолчанию процедуре диалогового окна, или значение ИСТИНА (TRUE), чтобы cбросить сообщение.
Если флажок OFN_EXPLORER установлен, lpfnHook - указатель на фильтр (hook) - процедуру OFNHookProc. Фильтр (hook) - процедура получает уведомительные сообщения, переданные из диалогового окна. Фильтр (hook) - процедура к тому же получает сообщения для любых дополнительных элементов управления, которые вы определили, устанавливая шаблон дочернего блока диалога. Фильтр (hook) - процедура не получает сообщения, предназначенные для заданных по умолчанию стандартных элементов управления диалогового окна.
lpTemplateName
Указатель на строку с символом нуля в конце, которя именует ресурс шаблона блока диалога в модуле, идентифицированном элементом hInstance. Для пронумерованных ресурсов диалогового окна, это может быть значение, возвращенное макрокомандой MAKEINTRESOURCE. Этот элемент игнорируется, если в элементе Flags не установлен флажок OFN_ENABLETEMPLATE.
Если флажок OFN_EXPLORER установлен, система использует заданный шаблон, чтобы создать диалоговое окно, которое является дочерним для заданного по умолчанию диалогового окна в стиле Проводника. Если флажок OFN_EXPLORER не установлен, система использует шаблон, чтобы создать блок диалога старого стиля, которое заменяет заданное по умолчанию диалоговое окно.

Смотри также
GetOpenFileName, GetSaveFileName

Размещение и совместимость OPENFILENAME

Windows NTДа 
Win95Да 
Win32sДа 
Импортируемая библиотека- 
Заголовочный файлcommdlg.h 
UnicodeWinNT
Замечания по платформеНе имеется
 
« Предыдущая статья   Следующая статья »