Приложения

Приложение А. Функции, константы и структуры RDS

А.5. Сервисные функции и макросы RDS

А.5.5. Вызов стандартных диалогов

А.5.5.3. rdsCallFileDialog – вызов диалога выбора файла

Функция rdsCallFileDialog открывает стандартный диалог выбора файла.

  RDSSTR RDSCALL rdsCallFileDialogA( // UTF8
    RDSCSTR InitialFile,  // Исходное имя файла или папки (UTF8)
    DWORD Flags,          // Флаги диалога (RDS_CFD_*)
    RDSCSTR Filter,       // Фильтры имен файлов (UTF8)
    RDSCSTR DefExt,       // Расширение по умолчанию (UTF8)
    RDSCSTR Title         // Заголовок диалога (UTF8)
  );
  RDSWSTR RDSCALL rdsCallFileDialogW( // UTF16
    RDSWCSTR InitialFile, // Исходное имя файла или папки (UTF16)
    DWORD Flags,          // Флаги диалога (RDS_CFD_*)
    RDSWCSTR Filter,      // Фильтры имен файлов (UTF16)
    RDSWCSTR DefExt,      // Расширение по умолчанию (UTF16)
    RDSWCSTR Title        // Заголовок диалога (UTF16)
  );
  // Функция-псевдоним
  RDSXSTR RDSCALL rdsCallFileDialog( // Кодировка по умолчанию
    RDSXCSTR InitialFile, // Исходное имя файла или папки (кодировка по умолчанию)
    DWORD Flags,          // Флаги диалога (RDS_CFD_*)
    RDSXCSTR Filter,      // Фильтры имен файлов (кодировка по умолчанию)
    RDSXCSTR DefExt,      // Расширение по умолчанию (кодировка по умолчанию)
    RDSXCSTR Title        // Заголовок диалога (кодировка по умолчанию)
  );

Тип указателя на эту функцию

RDS_SSDwSSS (для UTF8) или RDS_WsWsDwWsWsWs (для UTF16)

Параметры

InitialFile (RDSCSTR, RDSWCSTR, RDSXCSTR)

Указатель на строку с путем к исходному файлу, который будет выбран в диалоге на момент его открытия. Если последний символ этой строки – обратная косая черта, она будет трактоваться как путь к исходной папке, которая должна отображаться в диалоге (имя файла при этом будет пустым). Если в этом параметре передано значение NULL или указатель на пустую строку, исходно в диалоге будет отображаться папка с загруженной в данный момент схемой, а имя файла будет пустым.

Flags (DWORD)

Битовые флаги, определяющие поведение диалога:

RDS_CFD_OPEN	Показать диалог открытия файла (не может использоваться вместе с флагом RDS_CFD_SAVE).
RDS_CFD_SAVE	Показать диалог сохранения файла (не может использоваться вместе с флагом RDS_CFD_OPEN).
RDS_CFD_CREATEPROMPT	Для диалога сохранения: пользователь должен подтвердить создание нового файла, если введено имя несуществующего файла.
RDS_CFD_OVERWRITEPROMPT	Для диалога сохранения: пользователь должен подтвердить перезапись файла, если введено имя существующего файла.
RDS_CFD_MUSTEXIST	Для диалога открытия: пользователю запрещено выбирать несуществующие файлы.
RDS_CFD_ABSPATH	В возвращаемом функцией пути к файлу стандартные пути RDS не будут заменены на их символические обозначения.

Filter (RDSCSTR, RDSWCSTR, RDSXCSTR)

Указатель на строку с фильтрами имен файлов для диалога, или NULL, если в диалоге всегда нужно отображать все файлы. Каждый фильтр состоит из названия, видимого пользователем в списке фильтров, и шаблона имени файла с использованием обычных метасимволов «*» и «?» (можно указать несколько шаблонов, разделив их точкой с запятой). Название и шаблон разделяются символом вертикальной черты «|». Фильтры в строке отделяются друг от друга символов перевода строки «\n» (код 10). Например, передача в параметре Filter строки «Текстовые файлы|*.txt;*.log\nВсе файлы|*.*» приведет к тому, что в выпадающем списке фильтров диалога будет два варианта: «Текстовые файлы» и «Все файлы». При выборе первого из них в диалоге будут отображаться только файлы с расширениями «txt» и «log», при выборе второго – все файлы.

DefExt (RDSCSTR, RDSWCSTR, RDSXCSTR)

Указатель на строку с расширением по умолчанию, которое нужно дать введенному пользователем вручную имени файла, если он не ввел расширение сам, или NULL, если расширение по умолчанию следует взять из самого первого фильтра в строке Filter (если она передана).

Title (RDSCSTR, RDSWCSTR, RDSXCSTR)

Указатель на строку с заголовком диалога, или NULL, если диалог должен иметь заголовок «Сохранить как» (при наличии в параметре Flags флага RDS_CFD_SAVE) или «Открыть» (при наличии флага RDS_CFD_OPEN).

Возвращаемое значение

Указатель на созданную в динамической памяти строку, содержащую путь к выбранному файлу, если пользователь нажал кнопку «OK». Если пользователь нажал кнопку «отмена» или просто закрыл окно диалога, возвращается NULL.

Примечания

Эта функция используется в тех случаях, когда нужно запросить у пользователя имя какого-либо файла для чтения (тогда указывается флаг RDS_CFD_OPEN) или для записи (тогда указывается флаг RDS_CFD_SAVE) данных. Если не указан ни один из этих флагов, считается, что указан RDS_CFD_OPEN.

Для запроса имен папок следует использовать функцию rdsCallDirDialog.

Динамическая строка, созданная функцией rdsCallFileDialog, должна быть обязательно освобождена функцией rdsFree.

Пример

Пример использования функции приведен в §3.3 руководства программиста.

См. также

rdsCallDirDialog, rdsFree.