Openfilename

typedef struct tagOFN { // ofn

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;

Переменные

0. lStructSize — определяет размер структуры в байтах.

1. hwndOwner — определяет окно, владеющее данным диалоговым окном. В данном аргументе может передаваться любой корректный дескриптор окна или нулевое значение, если данное диалоговое окно не имеет владельца.

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

3. Если установлен флаг OFN_EXPLORER, система использует указанный шаблон для создания диалогового окна, являющегося дочерним окном используемого по умолчанию диалогового окна стиля Explorer. Если флаг OFN_EXPLORER не установлен, система использует указанный шаблон для создания диалогового окна стандартного стиля, заменяющего используемое по умолчанию диалоговое окно.

4. lpstrFilter — указатель на буфер, содержащий заканчивающуюся нулём строку фильтра. Последняя строка в фильтре должна заканчиваться двумя нулевыми символами.

5. Первая строка каждой пары содержит строку описания фильтра (например, "Текстовые файлы"), а вторая строка — определяет шаблон фильтра (например, "*.txt"). При указании нескольких шаблонов файлов в одной строке они разделяются точкой с запятой (например, "*.txt;*.doc;*.bak"). В строке шаблона могут использоваться все символы, которые могут использоваться в имени файла и символ звёздочки (*). Строка шаблона не может содержать символов пробела (хотя длинное имя файла может).

6. Система не изменяет порядок фильтров при их выводе. В раскрывающемся списке Тип файла: они располагаются в том же порядке, что и в переменной lpstrFilter.

7. Если переменная lpstrFilter имеет нулевое значение, то в раскрывающемся списке Тип файла: отсутствуют фильтры.

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

9. Если данная переменная имеет нулевое значение, диалоговое окно не сохраняет установленный пользователем фильтр.

10. Если данная переменная имеет ненулевое значение, то переменная nMaxCustFilter должна содержать размер буфера lpstrCustomFilter в байтах (версия ANSI) или в 16-битовых символах (версия Unicode).

11. nMaxCustFilter — определяет размер буфера, на который указывает переменная lpstrCustomFilter, в байтах или символах. Размер этого буфера не может быть менее 40 символов. Если переменная lpstrCustomFilter имеет нулевое значение или указывает на нулевую строку, значение переменной nMaxCustFilter игнорируется.

12. nFilterIndex — определяет индекс выделенного фильтра в раскрывающемся списке Тип файла:. Буфер, на который указывает переменная lpstrFilter, содержит пары строк, определяющие фильтр. Первая пара имеет индекс 1, вторая пара — 2 и т.д. Нулевое значение индекса указывает на использование пользовательского фильтра, определённого в переменной lpstrCustomFilter. Инициализация данной переменной перед вызовом диалогового окна позволяет установить шаблон фильтра, используемый при его открытии. После выделения пользователем файла в переменную nFilterIndex заносится индекс фильтра отображаемого в текстовом поле в раскрывающемся списке Тип файла:.

13. Если как переменная nFilterIndex, так и переменная lpstrCustomFilter имеют нулевое значение, система использует первый фильтр в буфере lpstrFilter. Если все три эти переменные имеют нулевое значение, то системе не использует фильтры и не выводит никаких фалов в список файлов диалогового окна.

14. lpstrFile — указатель на буфер, содержащий имя файла, используемое для инициализации текстового поля Имя файла:. Если это текстовое поле не нуждается в инициализации, то первый символ данного буфера должен содержать нулевое значение. Если функции GetOpenFileName или GetSaveFileName успешно завершают свою работу, этот буфер содержит идентификатор диска, путь, имя файла и расширение выделенного файла.

15. Если установлен флаг OFN_ALLOWMULTISELECT и пользователь выделил несколько файлов, буфер содержит текущий директорий, за которым следуют имена выделенных файлов. Для диалоговых окон стиля Explorer строки директория и имени файла разделяются нулевым символом, а после последнего имени файла помещается дополнительный нулевой символ. В диалоговых окнах стандартного стиля строки разделяются пробелами, а для длинных имён, содержащих пробелы, используются их короткие имена. Для преобразования длинных имён в короткие может использоваться функция FindFirsFile.

16. Если размер буфера недостаточен для размещения информации, функция возвращает нулевое значение, а функция CommDlgExtendedError возвращает значение FNERR_BUFFERTOOSMALL. В этом случае первые два байта буфера, на который указывает переменная lpstrFile, содержат требуемый размер буфера в байтах или символах.

17. nMaxFile — определяет размер буфера, на который указывает переменная lpstrFile, в байтах (версия ANSI) или в 16-битовых символах (версия Unicode). Функции GetOpenFileName и GetSaveFileName возвращаёт значение FALSE, если размер буфера недостаточен для хранения информации. Буфер должен иметь размер как минимум 256 символов.

18. lpstrFileTitle — указатель на буфер, в который будет записано имя файла и расширение (без информации о пути) для выделенного файла. Эта переменная может иметь нулевое значение.

19. nMaxFileTitle — определяет размер буфера, на который указывает переменная lpstrFileTitle, в байтах (версия ANSI) или в 16-битовых символах (версия Unicode). Значение этой переменной игнорируется, если переменная lpstrFileTitle будет иметь нулевое значение.

20. lpstrInitialDir — указатель на строку, определяющую исходный директорий.

21. В Windows NT 5.0 и более поздних версиях и в Windows 98 и более поздних версиях в том случае, когда переменная lpstrInitialDir имеет нулевое значение и текущий директорий содержит хотя бы один файл указанного типа, в качестве исходного директория выбирается текущий директорий.

22. Если переменная lpstrInitialDir имеет нулевое значение и текущий директорий не содержит ни одного файла указанного типа, в качестве исходного директория выбирается директорий персональных файлов данного пользователя. Для задания директория персональных файлов данного пользователя в качестве текущего директория в переменную lpstrInitialDir следует занести путь, возвращённый функцией SHGetSpecialFolderLocation с установленным флагом CSIDL_PERSONAL.

23. Для более ранних версий Windows и Windows NT в том случае, когда переменная lpstrInitialDir имеет нулевое значение, в качестве исходного директория выбирается текущий директорий.

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

25. Flags — битовые флаги, определяющие режим открытия диалогового окна. После закрытия диалогового окна состояние данных флагов определяет выбор пользователя. Определены следующие значения:

• OFN_ALLOWMULTISELECT — разрешает режим множественного выделения файлов. Если установлен флаг OFN_EXPLORER, диалоговое окно использует пользовательский интерфейс стиля Explorer. В противном случае используется стандартный стиль диалогового окна.

Если пользователь выделил несколько файлов, в буфере, на который указывает переменная lpstrFile, возвращается путь в текущий директорий, за которым следуют имена выделенных файлов. В переменной nFileOffset содержится смещение первого имени файла в байтах или символах, а переменная nFileExtension не используется. Для диалоговых окон стиля Explorer строки директория и имени файла разделяются нулевым символом, а после последнего имени файла помещается дополнительный нулевой символ. Этот формат позволяет таким диалоговым окнам возвращать длинные имена файлов, включающие в себя пробелы. В диалоговых окнах стандартного стиля строки разделяются пробелами, а для длинных имён, содержащих пробелы, используются их короткие имена. Для преобразования длинных имён в короткие может использоваться функция FindFirsFile.

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

• OFN_CREATEPROMPT — если пользователь несуществующий файл, при установке данного флага выводится запрос на создание нового файла. Если пользователь разрешает создать новый файл, диалоговое окно закрывается и возвращает указанное имя файла. В противном случае диалоговое окно остаётся открытым, позволяя пользователю задать другое имя файла. Если одновременно с этим флагом установлен флаг OFN_ALLOWMULTISELECT, диалоговое окно позволяет пользователю указать только одно имя несуществующего файла.

• OFN_ENABLEHOOK — разрешает использовать функцию обратного вызова, определённую в переменной lpfnHook.

• OFN_ENABLESIZING — в Windows NT 5.0 и Windows 98 разрешает изменение размера диалоговых окон Сохранение файла и Открытие файла, имеющих стиль Explorer, с использованием мыши или клавиатуры. По умолчанию диалоговые окна Сохранение файла и Открытие файла, имеющие стиль Explorer, могут изменять свой размер независимо от состояния данного флага. Состояние флага OFN_ENABLESIZING анализируется при использовании функции обратного вызова или пользовательского шаблона. Диалоговые окна стандартного стиля не могут изменять своих размеров.

• OFN_ENABLETEMPLATE — указывает на то, что в переменной lpTemplateName содержится указатель на имя ресурса шаблона диалогового окна в модуле, определяемом значением переменной hInstance.

Если установлен флаг OFN_EXPLORER, система использует указанный шаблон для создания диалогового окна, являющегося дочерним окном используемого по умолчанию диалогового окна стиля Explorer. Если флаг OFN_EXPLORER не установлен, система использует шаблон для создания диалогового окна стандартного стиля, заменяющего диалоговое окно, используемое по умолчанию.

• OFN_ENABLETEMPLATEHANDLE — указывает на то, что значение переменной hInstance определяет блок данных, содержащий предварительно загруженный шаблон диалогового окна. Если данный флаг установлен, система игнорирует значение переменной lpTemplateName.

Если установлен флаг OFN_EXPLORER, система использует указанный шаблон для создания диалогового окна, являющегося дочерним окном используемого по умолчанию диалогового окна стиля Explorer. Если флаг OFN_EXPLORER не установлен, система использует шаблон для создания диалогового окна стандартного стиля, заменяющего диалоговое окно, используемое по умолчанию.

• OFN_EXPLORER — указывает на то, что все изменения, внесённые пользователем в диалоговые окна Сохранение файла и Открытие файла, используют новый метод настройки метод стиля Explorer.

По умолчанию диалоговые окна Сохранение файла и Открытие файла используют пользовательский интерфейс стиля Explorer независимо от состояния данного флага. Состояние флага OFN_EXPLORER анализируется при использовании функции обратного вызова или пользовательского шаблона, а также в том случае, если установлен флаг OFN_ALLOWMULTISELECT.

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

• OFN_EXTENSIONDIFFERENT — указывает на то, что введённое пользователем расширение файла отличается от расширения, записанного в переменной lpstrDefExt. Функция не использует этот флаг, если переменная lpstrDefExt имеет нулевое значение.

• OFN_FILEMUSTEXIST — указывает на то, что пользователем может вводить в текстовое поле Имя файла: только имена существующих файлов. Если установлен данный флаг и пользователь ввёл имя несуществующего файла, процедура диалогового окна выводит окно сообщения. Совместно с данным флагом устанавливается флаг OFN_PATHMUSTEXIST.

• 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.

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

Если переменная nFileOffset имеет значение меньшее нуля, то использовано некорректное имя файла. В противном случае используемое имя файла корректно и значения переменных nFileExtension и nFileOffset могут использоваться как будто бы флаг OFN_NOVALIDATE не был установлен.

• OFN_OVERWRITEPROMPT — диалоговое окно Сохранение файла выводит окно сообщения в том случае, если выделенный файл уже существует. Пользователь должен подтвердить своё намерение переписать этот файл.

• OFN_PATHMUSTEXIST — указывает на то, что пользователь может вводить только существующие пути и имена файлов. Если установлен данный флаг и пользователь ввёл в текстовое поле Имя файла: несуществующий путь или новое имя файла, функция диалогового окна выводит окно сообщения.

• OFN_READONLY — при создании окна устанавливается флажок Только чтение. Этот флаг сохраняет состояние флажка Только чтение закрываемого диалогового окна.

• OFN_SHAREAWARE — вызов функции OpenFile завершился с ошибкой вследствие нарушения режима разделения сетевых ресурсов, эта ошибка была проигнорирована и диалоговое окно возвратило выделенное имя файла.

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

• OFN_SHOWHELP — в диалоговом окне выводится кнопка Справка. В переменной hwndOwner должно быть определено окно, получающее зарегистрированное сообщение HELPMSGSTRING, посылаемое диалоговым окном при нажатии пользователем кнопки Справка.

Диалоговое окно стиля Explorer при нажатии пользователем кнопки Справка посылает функции обратного вызова извещение CDN_HELP.

0. nFileOffset — определяет смещение в байтах (версия ANSI) или в 16-битовых символах (версия Unicode) с начала строки пути до первого символа имени файла в строке, на которую указывает переменная lpstrFile. Например, если переменная lpstrFile указывает на строку "c:\dir_1\dir_2\file.ext", то в данной переменной содержится число 15, указывающее смещение строки "file.ext".

1. Если пользователь выделил более одного файла, в переменной nFileOffset содержится смещение первого имени файла.

2. nFileExtension — определяет смещение в байтах (версия ANSI) или в 16-битовых символах (версия Unicode) с начала строки пути до первого символа расширения файла в строке, на которую указывает переменная lpstrFile. Например, если переменная lpstrFile указывает на строку "c:\dir_1\dir_2\file.ext", то в данной переменной содержится число 20. Если пользователь не указал расширение и переменная lpstrDefExt имеет нулевое значение, эта переменная определяет смещение до завершающего строку нулевого символа. Если последним введённым пользователем символом имени файла является разделяющая точка ("."), эта переменная содержит нулевое значение.

3. lpstrDefExt — указатель на буфер, содержащий расширение, используемое по умолчанию. Функции GetOpenFileName и GetSaveFileName добавляют это расширение к имени файла, введённому пользователем без расширения. Эта строка может иметь любую длину, но к имени файла добавляются только первые три символа данной строки. Это налагает определённые ограничения на работу с длинными именами файлов, для которых длина расширения файла не ограничена. Строка, на которую указывает переменная lpstrDefExt, не должна содержать точки (.). Если данная переменная имеет нулевое значение, и пользователь не ввёл расширение файла, то к введённому файлу не добавляется никакого расширения.

4. lCustData — пользовательская информация, передаваемая системой функции обратного вызова, определённой в переменной lpfnHook. Когда система посылает функции обратного вызова сообщение WM_INITDIALOG, в его аргументе lParam содержится указатель на объект структуры OPENFILENAME, указанный при создании диалогового окна. Функция обратного вызова может использовать этот указатель для доступа к переменной lCustData.

5. lpfnHook — указатель на функцию обратного вызова. Значение данной переменной игнорируется, если в переменной Flags не установлен флаг OFN_ENABLEHOOK.

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

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

8. lpTemplateName — указатель на заканчивающуюся нулём строку, содержащую имя ресурса шаблона диалогового окна в модуле, определённом в переменной hInstance. Для перечислимых ресурсов диалогового окна в данной переменной может содержаться значение, возвращаемое макросом MAKEINTRESOURCE. Значение данной переменной игнорируется, если в переменной Flags не установлен флаг OFN_ENABLETEMPLATE.

9. Если установлен флаг OFN_EXPLORER, система использует указанный шаблон для создания диалогового окна, являющегося дочерним окном используемого по умолчанию диалогового окна стиля Explorer. Если флаг OFN_EXPLORER не установлен, система использует указанный шаблон для создания диалогового окна стандартного стиля, заменяющего используемое по умолчанию диалоговое окно.

Примечание

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

Описание данной структуры содержится в файле заголовка commdlg.h

RECT

typedef struct _RECT {

LONG left;

LONG top;

LONG right;

LONG bottom;

} RECT;

Переменные

0. left — определяет горизонтальную координату верхнего левого угла прямоугольника.

1. top — определяет вертикальную координату верхнего левого угла прямоугольника.

2. right — определяет горизонтальную координату нижнего правого угла прямоугольника.

3. bottom — определяет вертикальную координату нижнего правого угла прямоугольника.

Примечание

Объект структуры RECT определяет координаты верхнего левого и нижнего правого углов прямоугольника.

Когда объект структуры передаётся в качестве аргумента функции FillRect, его крайний правый столбец и нижняя строка не заполняются.

Описание данной структуры содержится в файле заголовка windef.h.