4.36.3.5 - Структура 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
Набор битовых флажков, который вы может использовать, чтобы инициализировать диалоговое окно. Когда блок диалога возвращает значение, он устанавливает эти флажки, чтобы обозначить ввод данных от пользователя. Этот элемент может быть комбинацией следующих флажков:

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 
Unicode				WinNT
Замечания по платформе		Не имеется

Предыдущий Шаг | Следующий Шаг | Оглавление
Автор Владимир Соковиков - 20.04.2002