Структура OPENFILENAMEA (commdlg.h)

[Начиная с Windows Vista, общие диалоговые окна "Открыть" и "Сохранить как" заменены диалоговым окном "Общий элемент". Мы рекомендуем использовать API общих диалоговых окон вместо этих диалоговых окон из библиотеки общих диалоговых окон.]

Содержит сведения, используемые функциями GetOpenFileName и GetSaveFileName для инициализации диалогового окна "Открыть" или "Сохранить как ". После того как пользователь закроет диалоговое окно, система возвращает сведения о выборе пользователя в этой структуре.

Синтаксис

typedef struct tagOFNA {
  DWORD         lStructSize;
  HWND          hwndOwner;
  HINSTANCE     hInstance;
  LPCSTR        lpstrFilter;
  LPSTR         lpstrCustomFilter;
  DWORD         nMaxCustFilter;
  DWORD         nFilterIndex;
  LPSTR         lpstrFile;
  DWORD         nMaxFile;
  LPSTR         lpstrFileTitle;
  DWORD         nMaxFileTitle;
  LPCSTR        lpstrInitialDir;
  LPCSTR        lpstrTitle;
  DWORD         Flags;
  WORD          nFileOffset;
  WORD          nFileExtension;
  LPCSTR        lpstrDefExt;
  LPARAM        lCustData;
  LPOFNHOOKPROC lpfnHook;
  LPCSTR        lpTemplateName;
  LPEDITMENU    lpEditInfo;
  LPCSTR        lpstrPrompt;
  void          *pvReserved;
  DWORD         dwReserved;
  DWORD         FlagsEx;
} OPENFILENAMEA, *LPOPENFILENAMEA;

Члены

lStructSize

Тип: DWORD

Длина структуры в байтах. Используйте sizeof (OPENFILENAME) для этого параметра.

hwndOwner

Тип: HWND

Дескриптор окна, которому принадлежит диалоговое окно. Это может быть любой допустимый дескриптор окна или значение NULL , если у диалогового окна нет владельца.

hInstance

Тип: HINSTANCE

Если флаг OFN_ENABLETEMPLATEHANDLE задан в элементе Flags , hInstance — это дескриптор объекта памяти, содержащего шаблон диалогового окна. Если установлен флаг OFN_ENABLETEMPLATE , hInstance — это дескриптор модуля, который содержит шаблон диалогового окна с именем члена lpTemplateName . Если ни один из флагов не задан, этот элемент игнорируется. Если установлен флаг OFN_EXPLORER, система использует указанный шаблон для создания диалогового окна, которое является дочерним по отношению к диалоговому окку Обозреватель по умолчанию. Если флаг OFN_EXPLORER не задан, система использует шаблон для создания диалогового окна старого стиля, заменяющего диалоговое окно по умолчанию.

lpstrFilter

Тип: LPCTSTR

Буфер, содержащий пары строк фильтра, завершаемых значением NULL. Последняя строка в буфере должна заканчиваться двумя символами NULL .

Первая строка в каждой паре является отображаемой строкой, описывающей фильтр (например, "Текстовые файлы"), а вторая строка задает шаблон фильтра (например, ".TXT"). Чтобы указать несколько шаблонов фильтров для одной отображаемой строки, используйте точку с запятой для разделения шаблонов (например, ".TXT;.DOC;. BAK"). Строка шаблона может быть сочетанием допустимых символов имени файла и подстановочного знака звездочки (*). Не включайте пробелы в строку шаблона.

Система не изменяет порядок фильтров. Они отображаются в поле со списком Типы файлов в порядке, указанном в lpstrFilter.

Если lpstrFilter имеет значение NULL, в диалоговом окне не отображаются фильтры.

В случае ярлыка, если фильтр не задан, GetOpenFileName и GetSaveFileName извлекают имя LNK-файла, а не его целевой объект. Это поведение аналогично установке флага OFN_NODEREFERENCELINKS в элементе Flags . Чтобы получить целевой объект ярлыка без фильтрации, используйте строку "All Files\0*.*\0\0".

lpstrCustomFilter

Тип: LPTSTR

Статический буфер, содержащий пару строк фильтра, завершаемых значением NULL, для сохранения шаблона фильтра, выбранного пользователем. Первая строка — это отображаемая строка, описывающая пользовательский фильтр, а вторая строка — шаблон фильтра, выбранный пользователем. При первом создании диалогового окна приложением указывается первая строка, которая может быть любой непустой строкой. Когда пользователь выбирает файл, диалоговое окно копирует текущий шаблон фильтра во вторую строку. Сохраненный шаблон фильтра может быть одним из шаблонов, указанных в буфере lpstrFilter , или шаблоном фильтра, введенным пользователем. Система использует строки для инициализации пользовательского фильтра файлов при следующем создании диалогового окна. Если элемент nFilterIndex равен нулю, диалоговое окно использует настраиваемый фильтр.

Если этот элемент имеет значение NULL, диалоговое окно не сохраняет пользовательские шаблоны фильтров.

Если этот элемент не равен NULL, значение элемента nMaxCustFilter должно указывать размер буфера lpstrCustomFilter в символах.

nMaxCustFilter

Тип: DWORD

Размер (в символах) буфера, определяемого lpstrCustomFilter. Длина этого буфера должна составлять не менее 40 символов. Этот элемент игнорируется, если lpstrCustomFilter имеет значение NULL или указывает на строку 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. Этот элемент игнорируется, если lpstrFileTitle имеет значение NULL.

lpstrInitialDir

Тип: LPCTSTR

Исходный каталог. Алгоритм выбора начального каталога зависит от разных платформ.

Windows 7:

1. Если значение lpstrInitialDir совпадает с значением, переданным при первом использовании приложением диалогового окна Открыть или Сохранить как , в качестве начального каталога используется путь, недавно выбранный пользователем.
2. В противном случае, если lpstrFile содержит путь, этот путь является начальным каталогом.
3. В противном случае, если lpstrInitialDir не равно NULL, он указывает исходный каталог.
4. Если lpstrInitialDir имеет значение NULL и текущий каталог содержит файлы указанных типов фильтров, начальным каталогом будет текущий каталог.
5. В противном случае начальным каталогом будет каталог личных файлов текущего пользователя.
6. В противном случае начальным каталогом будет папка "Рабочий стол".

1. Если lpstrFile содержит путь, он является начальным каталогом.
2. В противном случае lpstrInitialDir указывает исходный каталог.
3. В противном случае, если приложение ранее использовало диалоговое окно Открыть или Сохранить как , в качестве начального каталога выбирается последний использованный путь. Однако если приложение не запускается в течение длительного времени, сохраненный выбранный путь удаляется.
4. Если lpstrInitialDir имеет значение NULL и текущий каталог содержит файлы указанных типов фильтров, начальным каталогом будет текущий каталог.
5. В противном случае начальным каталогом будет каталог личных файлов текущего пользователя.
6. В противном случае начальным каталогом будет папка "Рабочий стол".

lpstrTitle

Тип: LPCTSTR

Строка, помещаемая в заголовок диалогового окна. Если этот элемент имеет значение NULL, система использует заголовок по умолчанию (то есть сохранить как или открыть).

Flags

Тип: DWORD

Набор битовых флагов, который можно использовать для инициализации диалогового окна. Когда диалоговое окно возвращается, оно устанавливает эти флаги для указания входных данных пользователя. Этот элемент может быть сочетанием следующих флагов.

nFileOffset

Тип: WORD

Отсчитываемое от нуля смещение в символах от начала пути до имени файла в строке, на которую указывает lpstrFile. Для версии ANSI это число байтов; Для версии Юникода это число символов. Например, если lpstrFile указывает на следующую строку c:\dir1\dir2\file.ext, этот элемент содержит значение 13, указывающее смещение строки file.ext. Если пользователь выбирает несколько файлов, nFileOffset — это смещение имени первого файла.

nFileExtension

Тип: WORD

Отсчитываемое от нуля смещение в символах от начала пути до расширения имени файла в строке, на которую указывает lpstrFile. Для версии ANSI это число байтов; Для версии Юникода это число символов. Обычно расширением имени файла является подстрока, которая следует за последним вхождением символа точки ("."). Например, 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

Указатель на процедуру перехватчика. Этот элемент игнорируется, если элемент Flags не содержит флаг OFN_ENABLEHOOK .

Если флаг OFN_EXPLORER не задан в элементе Flags , lpfnHook является указателем на процедуру перехватчика OFNHookProcOldStyle , которая получает сообщения, предназначенные для диалогового окна. Процедура перехватчика возвращает значение FALSE , чтобы передать сообщение в процедуру диалогового окна по умолчанию, или TRUE , чтобы отменить сообщение.

Если задано OFN_EXPLORER , lpfnHook является указателем на процедуру перехватчика OFNHookProc . Процедура перехватчика получает уведомления, отправляемые из диалогового окна. Процедура перехватчика также получает сообщения для всех дополнительных элементов управления, определенных путем указания дочернего шаблона диалогового окна. Процедура перехватчика не получает сообщения, предназначенные для стандартных элементов управления диалогового окна по умолчанию.

lpTemplateName

Тип: LPCTSTR

Имя ресурса шаблона диалогового окна в модуле, определяемого элементом hInstance . Для нумерованных ресурсов диалогового окна это может быть значение, возвращаемое макросом MAKEINTRESOURCE . Этот элемент игнорируется, если в элементе Flags не установлен флаг 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

Набор битовых флагов, который можно использовать для инициализации диалогового окна. В настоящее время этот элемент может быть равен нулю или следующему флагу.

Комментарии

В целях совместимости панель мест скрыта, если для параметра Flags задано значение OFN_ENABLEHOOK а параметр lStructSize — OPENFILENAME_SIZE_VERSION_400.

Требования

См. также раздел

Общая библиотека диалоговых окон

Основные понятия

GetOpenFileName

GetSaveFileName

Другие ресурсы

Справочные материалы

SHGetSpecialFolderLocation