Класс QStandardPaths
Класс QStandardPaths предоставляет методы для доступа к стандартным путям. Подробнее...
| Заголовок: | #include <QStandardPaths> |
| qmake: | QT += core |
| С тех пор: | Qt 5.0 |
Этот класс был представлен в Qt 5.0.
Типы публичного интерфейса
| перечисление | LocateOption { LocateFile, LocateDirectory } |
| флаги | LocateOptions |
| перечисление | StandardLocation { DesktopLocation, DocumentsLocation, FontsLocation, ApplicationsLocation, MusicLocation, …, AppConfigLocation } |
Статические публичные члены
| QString | displayName(QStandardPaths::StandardLocation type) |
| QString | findExecutable(const QString &executableName, const QStringList &paths = QStringList()) |
| QString | locate(QStandardPaths::StandardLocation type, const QString &fileName, QStandardPaths::LocateOptions options = LocateFile) |
| QStringList | locateAll(QStandardPaths::StandardLocation type, const QString &fileName, QStandardPaths::LocateOptions options = LocateFile) |
| void | setTestModeEnabled(bool testMode) |
| QStringList | standardLocations(QStandardPaths::StandardLocation type) |
| QString | writableLocation(QStandardPaths::StandardLocation type) |
Подробное описание
Этот класс содержит функции для запроса стандартных расположений на локальной файловой системе, для общих задач, таких как каталоги, относящиеся к конкретному пользователю, или системные каталоги конфигурации.
Документация типов членов
перечисление QStandardPaths::LocateOptionфлаги QStandardPaths::LocateOptions
Это перечисление описывает различные флаги, которые могут быть использованы для управления поведением QStandardPaths::locate и QStandardPaths::locateAll.
| Константа | Значение | Описание |
|---|---|---|
QStandardPaths::LocateFile |
0x0 |
возвращать только файлы |
QStandardPaths::LocateDirectory |
0x1 |
возвращать только каталоги |
Тип LocateOptions является псевдонимом для QFlags<LocateOption>. Он хранит логическое ИЛИ сочетание значений LocateOption.
перечисление QStandardPaths::StandardLocation
Это перечисление описывает различные расположения, которые могут быть запрошены с помощью методов, таких как QStandardPaths::writableLocation, QStandardPaths::standardLocations и QStandardPaths::displayName.
Некоторые из значений в этом перечислении представляют конфигурацию пользователя. Такие значения перечисления будут возвращать одинаковые пути в разных приложениях, поэтому они могут использоваться для обмена данными с другими приложениями. Другие значения специфичны для данного приложения. Каждое значение перечисления в таблице ниже описывает, является ли оно специфичным для приложения или общим.
Должно предполагаться, что каталоги, специфичные для приложения, недоступны для других приложений. Поэтому файлы, помещенные туда, могут быть недоступны для других приложений, даже если они запущены одним и тем же пользователем. С другой стороны, общие каталоги должны предполагаться доступными для всех приложений, запущенных этим пользователем, но всё же должны предполагаться недоступными для приложений других пользователей.
Обмен данными с другими пользователями не входит в область применения QStandardPaths.
| Константа | Значение | Описание |
|---|---|---|
QStandardPaths::DesktopLocation |
0 |
Возвращает каталог рабочего стола пользователя. Это общее значение. На системах без понятия о рабочем столе, это то же самое, что и QStandardPaths::HomeLocation. |
QStandardPaths::DocumentsLocation |
1 |
Возвращает каталог, содержащий файлы документов пользователя. Это общее значение. Возвращаемый путь никогда не пуст. |
QStandardPaths::FontsLocation |
2 |
Возвращает каталог, содержащий шрифты пользователя. Это общее значение. Обратите внимание, что установка шрифтов может потребовать дополнительных операций, специфичных для платформы. |
QStandardPaths::ApplicationsLocation |
3 |
Возвращает каталог, содержащий приложения пользователя (либо исполняемые файлы, пакеты приложений или ярлыки к ним). Это общее значение. Обратите внимание, что установка приложений может потребовать дополнительных операций, специфичных для платформы. Файлы, папки или ярлыки в этом каталоге зависят от платформы. |
QStandardPaths::MusicLocation |
4 |
Возвращает каталог, содержащий музыку пользователя или другие аудиофайлы. Это общее значение. Если каталог, специфичный для музыкальных файлов, не существует, возвращается разумное значение по умолчанию для хранения пользовательских документов. |
QStandardPaths::MoviesLocation |
5 |
Возвращает каталог, содержащий фильмы и видео пользователя. Это общее значение. Если каталог, специфичный для файлов фильмов, не существует, возвращается разумное значение по умолчанию для хранения пользовательских документов. |
QStandardPaths::PicturesLocation |
6 |
Возвращает каталог, содержащий изображения или фотографии пользователя. Это общее значение. Если каталог, специфичный для файлов изображений, не существует, возвращается разумное значение по умолчанию для хранения пользовательских документов. |
QStandardPaths::TempLocation |
7 |
Возвращает каталог, где можно хранить временные файлы. Возвращаемое значение может быть специфичным для приложения, общим для других приложений для этого пользователя или даже для всей системы. Возвращаемый путь никогда не пуст. |
QStandardPaths::HomeLocation |
8 |
Возвращает домашний каталог пользователя (то же самое, что и QDir::homePath()). В системах Unix это равно переменной среды HOME. Это значение может быть общим или специфичным для приложения, но возвращаемый путь никогда не пуст. |
QStandardPaths::DataLocation |
9 |
Возвращает то же значение, что и AppLocalDataLocation. Это значение перечисления устарело. Рекомендуется использовать AppDataLocation, так как на Windows рекомендуется использовать каталог roaming. |
QStandardPaths::CacheLocation |
10 |
Возвращает расположение каталога, куда следует записывать специфичные для пользователя неважные (кэшированные) данные. Это каталог, специфичный для приложения. Возвращаемый путь никогда не пуст. |
QStandardPaths::GenericCacheLocation |
15 |
Возвращает расположение каталога, куда следует записывать специфичные для пользователя неважные (кэшированные) данные, общие для приложений. Это общее значение. Обратите внимание, что возвращаемый путь может быть пустым, если система не имеет понятия о общем кэше. |
QStandardPaths::GenericDataLocation |
11 |
Возвращает расположение каталога, где можно хранить постоянные данные, общие для приложений. Это общее значение. Возвращаемый путь никогда не пуст. |
QStandardPaths::RuntimeLocation |
12 |
Возвращает расположение каталога, куда следует записывать файлы для межпроцессного взаимодействия, например, локальные сокеты Unix. Это общее значение. Возвращаемый путь может быть пустым на некоторых системах. |
QStandardPaths::ConfigLocation |
13 |
Возвращает расположение каталога, куда следует записывать конфигурационные файлы пользователя. Это может быть либо общее значение, либо специфичное для приложения, и возвращаемый путь никогда не пуст. |
QStandardPaths::DownloadLocation |
14 |
Возвращает каталог для загруженных пользователем файлов. Это общее значение. Если каталог, специфичный для загрузок, не существует, возвращается разумное значение по умолчанию для хранения пользовательских документов. |
QStandardPaths::GenericConfigLocation |
16 |
Возвращает расположение каталога, куда следует записывать общие конфигурационные файлы пользователя, используемые несколькими приложениями. Это общее значение, и возвращаемый путь никогда не пуст. |
QStandardPaths::AppDataLocation |
17 |
Возвращает расположение каталога, где можно хранить постоянные данные приложения. Это каталог, специфичный для приложения. Чтобы получить путь для хранения данных, которые нужно будет разделить с другими приложениями, используйте QStandardPaths::GenericDataLocation. Возвращаемый путь никогда не пуст. В операционной системе Windows возвращается путь roaming. Это значение перечисления было добавлено в Qt 5.4. |
QStandardPaths::AppLocalDataLocation |
DataLocation |
Возвращает путь к локальным настройкам в операционной системе Windows. На всех других платформах возвращает то же значение, что и AppDataLocation. Это значение перечисления было добавлено в Qt 5.4. |
QStandardPaths::AppConfigLocation |
18 |
Возвращает расположение каталога, куда следует записывать конфигурационные файлы пользователя. Это каталог, специфичный для приложения, и возвращаемый путь никогда не пуст. Это значение перечисления было добавлено в Qt 5.5. |
В следующей таблице приведены примеры путей в разных операционных системах. Первый путь — это путь для записи (если не указано иное). Другие дополнительные пути, если они есть, представляют не-записываемые расположения.
| Тип пути | macOS | Windows |
|---|---|---|
| DesktopLocation | "~/Desktop" | "C:/Users/<USER>/Desktop" |
| DocumentsLocation | "~/Documents" | "C:/Users/<USER>/Documents" |
| FontsLocation | "/System/Library/Fonts" (не для записи) | "C:/Windows/Fonts" (не для записи) |
| ApplicationsLocation | "/Applications" (не для записи) | "C:/Users/<USER>/AppData/Roaming/Microsoft/Windows/Start Menu/Programs" |
| MusicLocation | "~/Music" | "C:/Users/<USER>/Music" |
| MoviesLocation | "~/Movies" | "C:/Users/<USER>/Videos" |
| PicturesLocation | "~/Pictures" | "C:/Users/<USER>/Pictures" |
| TempLocation | случайный, сгенерированный ОС | "C:/Users/<USER>/AppData/Local/Temp" |
| HomeLocation | "~" | "C:/Users/<USER>" |
| DataLocation | "~/Library/Application Support/<APPNAME>", "/Library/Application Support/<APPNAME>". "<APPDIR>/../Resources" | "C:/Users/<USER>/AppData/Local/<APPNAME>", "C:/ProgramData/<APPNAME>", "<APPDIR>", "<APPDIR>/data", "<APPDIR>/data/<APPNAME>" |
| CacheLocation | "~/Library/Caches/<APPNAME>", "/Library/Caches/<APPNAME>" | "C:/Users/<USER>/AppData/Local/<APPNAME>/cache" |
| GenericDataLocation | "~/Library/Application Support", "/Library/Application Support" | "C:/Users/<USER>/AppData/Local", "C:/ProgramData", "<APPDIR>", "<APPDIR>/data" |
| RuntimeLocation | "~/Library/Application Support" | "C:/Users/<USER>" |
| ConfigLocation | "~/Library/Preferences" | "C:/Users/<USER>/AppData/Local/<APPNAME>", "C:/ProgramData/<APPNAME>" |
| GenericConfigLocation | "~/Library/Preferences" | "C:/Users/<USER>/AppData/Local", "C:/ProgramData" |
| DownloadLocation | "~/Downloads" | "C:/Users/<USER>/Documents" |
| GenericCacheLocation | "~/Library/Caches", "/Library/Caches" | "C:/Users/<USER>/AppData/Local/cache" |
| AppDataLocation | "~/Library/Application Support/<APPNAME>", "/Library/Application Support/<APPNAME>". "<APPDIR>/../Resources" | "C:/Users/<USER>/AppData/Roaming/<APPNAME>", "C:/ProgramData/<APPNAME>", "<APPDIR>", "<APPDIR>/data", "<APPDIR>/data/<APPNAME>" |
| AppLocalDataLocation | "~/Library/Application Support/<APPNAME>", "/Library/Application Support/<APPNAME>". "<APPDIR>/../Resources" | "C:/Users/<USER>/AppData/Local/<APPNAME>", "C:/ProgramData/<APPNAME>", "<APPDIR>", "<APPDIR>/data", "<APPDIR>/data/<APPNAME>" |
| AppConfigLocation | "~/Library/Preferences/<APPNAME>" | "C:/Users/<USER>/AppData/Local/<APPNAME>", "C:/ProgramData/<APPNAME>" |
| Тип пути | Linux |
|---|---|
| DesktopLocation | "~/Рабочий стол" |
| DocumentsLocation | "~/Документы" |
| FontsLocation | "~/.fonts", "~/.local/share/fonts", "/usr/local/share/fonts", "/usr/share/fonts" |
| ApplicationsLocation | "~/.local/share/applications", "/usr/local/share/applications", "/usr/share/applications" |
| MusicLocation | "~/Музыка" |
| MoviesLocation | "~/Видео" |
| PicturesLocation | "~/Изображения" |
| TempLocation | "/tmp" |
| HomeLocation | "~" |
| DataLocation | "~/.local/share/<APPNAME>", "/usr/local/share/<APPNAME>", "/usr/share/<APPNAME>" |
| CacheLocation | "~/.cache/<APPNAME>" |
| GenericDataLocation | "~/.local/share", "/usr/local/share", "/usr/share" |
| RuntimeLocation | "/run/user/<USER>" |
| ConfigLocation | "~/.config", "/etc/xdg" |
| GenericConfigLocation | "~/.config", "/etc/xdg" |
| DownloadLocation | "~/Загрузки" |
| GenericCacheLocation | "~/.cache" |
| AppDataLocation | "~/.local/share/<APPNAME>", "/usr/local/share/<APPNAME>", "/usr/share/<APPNAME>" |
| AppLocalDataLocation | "~/.local/share/<APPNAME>", "/usr/local/share/<APPNAME>", "/usr/share/<APPNAME>" |
| AppConfigLocation | "~/.config/<APPNAME>", "/etc/xdg/<APPNAME>" |
| Тип пути | Android | iOS |
|---|---|---|
| DesktopLocation | "<APPROOT>/files" | "<APPROOT>/Документы/Рабочий стол" |
| DocumentsLocation | "<USER>/Документы", "<USER>/<APPNAME>/Документы" | "<APPROOT>/Документы" |
| FontsLocation | "/system/fonts" (не доступно для записи) | "<APPROOT>/Library/Шрифты" |
| ApplicationsLocation | не поддерживается (каталог недоступен для чтения) | не поддерживается |
| MusicLocation | "<USER>/Музыка", "<USER>/<APPNAME>/Музыка" | "<APPROOT>/Документы/Музыка" |
| MoviesLocation | "<USER>/Фильмы", "<USER>/<APPNAME>/Фильмы" | "<APPROOT>/Документы/Фильмы" |
| PicturesLocation | "<USER>/Изображения", "<USER>/<APPNAME>/Изображения" | "<APPROOT>/Документы/Изображения", "assets-library://" |
| TempLocation | "<APPROOT>/cache" | "<APPROOT>/tmp" |
| HomeLocation | "<APPROOT>/files" | определяется системой |
| DataLocation | "<APPROOT>/files", "<USER>/<APPNAME>/files" | "<APPROOT>/Library/Application Support" |
| CacheLocation | "<APPROOT>/cache", "<USER>/<APPNAME>/cache" | "<APPROOT>/Library/Кэши" |
| GenericDataLocation | "<USER>" | "<APPROOT>/Документы" |
| RuntimeLocation | "<APPROOT>/cache" | не поддерживается |
| ConfigLocation | "<APPROOT>/files/настройки" | "<APPROOT>/Library/Preferences" |
| GenericConfigLocation | "<APPROOT>/files/настройки" (нет общих настроек) | "<APPROOT>/Library/Preferences" |
| DownloadLocation | "<USER>/Загрузки", "<USER>/<APPNAME>/Загрузки" | "<APPROOT>/Документы/Загрузки" |
| GenericCacheLocation | "<APPROOT>/cache" (нет общего кэша) | "<APPROOT>/Library/Кэши" |
| AppDataLocation | "<APPROOT>/files", "<USER>/<APPNAME>/files" | "<APPROOT>/Library/Application Support" |
| AppConfigLocation | "<APPROOT>/files/настройки" | "<APPROOT>/Library/Preferences/<APPNAME>" |
| AppLocalDataLocation | "<APPROOT>/files", "<USER>/<APPNAME>/files" | "<APPROOT>/Library/Application Support" |
В таблице выше, <APPNAME> обычно является именем организации, именем приложения или обоими, или уникальным именем, сгенерированным при упаковке. Аналогично, <APPROOT> — это место установки этого приложения (часто песочница). <APPDIR> — каталог, содержащий исполняемый файл приложения.
Не следует полагаться на указанные выше пути, так как они могут меняться в зависимости от конфигурации ОС, языка или могут измениться в будущих версиях Qt.
Примечание: В Android приложения с открытыми файлами во внешнем хранилище (<USER> места), будут завершены, если внешнее хранилище будет размонтировано.
Примечание: В Android 6.0 (API 23) или более поздних версиях необходимо запросить разрешение «WRITE_EXTERNAL_STORAGE» во время выполнения при использовании QStandardPaths::writableLocation или QStandardPaths::standardLocations.
Примечание: В iOS, если вы передадите QStandardPaths::standardLocations(QStandardPaths::PicturesLocation).last() в качестве аргумента в QFileDialog::setDirectory(), будет использовано собственное диалоговое окно выбора изображения для доступа к фотоальбому пользователя. Имя файла, возвращаемое значение, можно загрузить с помощью QFile и родственных API. Эта функция была добавлена в Qt 5.5.
См. также writableLocation(), standardLocations(), displayName(), locate(), и locateAll().
Документация по функциям-членам
[static] QString QStandardPaths::displayName(QStandardPaths::StandardLocation type)
Возвращает локализованное отображаемое имя для данного типа расположения type или пустую QString, если соответствующее расположение не найдено.
[static] QString QStandardPaths::findExecutable(const QString &executableName, const QStringList &paths = QStringList())
Ищет исполняемый файл с именем executableName в указанных paths или в системных путях, если paths пустой.
В большинстве операционных систем системный путь определяется переменной среды PATH. Каталоги для поиска исполняемого файла можно задать в аргументе paths. Для поиска как в своих путях, так и в системных путях, вызовите findExecutable дважды, один раз с заданными paths и один раз с пустыми paths. Символьные ссылки не разрешаются, чтобы сохранить поведение в случае исполняемых файлов, поведение которых зависит от имени, с которым они вызываются.
Примечание: В Windows обычно к исполняемым расширениям (из переменной среды PATHEXT) автоматически добавляются расширения. Например, вызов findExecutable("foo") ищет foo.exe или foo.bat если они есть.
Возвращает абсолютный путь к исполняемому файлу или пустую строку, если не найден.
[static] QString QStandardPaths::locate(QStandardPaths::StandardLocation type, const QString &fileName, QStandardPaths::LocateOptions options = LocateFile)
Ищет файл или каталог с именем fileName в стандартных расположениях для type.
Флаг options позволяет указать, искать ли файлы или каталоги. По умолчанию этот флаг установлен в значение LocateFile.
Возвращает абсолютный путь к первому найденному файлу или каталогу, иначе возвращает пустую строку.
[static] QStringList QStandardPaths::locateAll(QStandardPaths::StandardLocation type, const QString &fileName, QStandardPaths::LocateOptions options = LocateFile)
Находит все файлы или каталоги с именем fileName в стандартных расположениях для type.
Флаг options позволяет указать, искать ли файлы или каталоги. По умолчанию этот флаг установлен в значение LocateFile.
Возвращает список всех найденных файлов.
[static] void QStandardPaths::setTestModeEnabled(bool testMode)
Если testMode равно true, это включает специальный «режим тестирования» в QStandardPaths, который изменяет пути записи на указание тестовых каталогов. Это предотвращает чтение и запись в текущей конфигурации пользователя автоматическими тестами.
Это влияет на расположения, в которые тестовые программы могут записывать файлы: GenericDataLocation, DataLocation, ConfigLocation, GenericConfigLocation, AppConfigLocation, GenericCacheLocation, и CacheLocation. Другие расположения не затрагиваются.
В Unix, XDG_DATA_HOME устанавливается в ~/.qttest/share, XDG_CONFIG_HOME устанавливается в ~/.qttest/config, а XDG_CACHE_HOME устанавливается в ~/.qttest/cache.
В macOS данные попадают в ~/.qttest/Application Support, кэш — в ~/.qttest/Cache, а конфигурация — в ~/.qttest/Preferences.
В Windows всё попадает в каталог «qttest» в %APPDATA%.
[static] QStringList QStandardPaths::standardLocations(QStandardPaths::StandardLocation type)
Возвращает все каталоги, где находятся файлы типа type.
Список каталогов отсортирован по приоритету от высокого к низкому, начиная с writableLocation() при возможности определения. Этот список пуст, если для типа не определены места расположения.
См. также writableLocation().
[static] QString QStandardPaths::writableLocation(QStandardPaths::StandardLocation type)
Возвращает каталог, в который следует записывать файлы типа type, или пустую строку, если местоположение определить невозможно.
Примечание: Возвращённое место хранения может не существовать; то есть, его может потребоваться создать системе или пользователю.
© The Qt Company Ltd
Licensed under the GNU Free Documentation License, Version 1.3.
https://doc.qt.io/qt-5.15/qstandardpaths.html
