Класс QStandardPaths
Класс QStandardPaths предоставляет методы для доступа к стандартным путям. Подробнее...
| Заголовок: | #include <QStandardPaths> |
| qmake: | QT += core |
| С момента: | Qt 5.0 |
Открытые типы
| перечисление | LocateOption { LocateFile, LocateDirectory } |
| флаги | LocateOptions |
| перечисление | StandardLocation { DesktopLocation, DocumentsLocation, FontsLocation, ApplicationsLocation, ..., AppConfigLocation } |
Статические открытые члены
| QString | displayName(StandardLocation type) |
| QString | findExecutable(const QString &executableName, const QStringList &paths = QStringList()) |
| QString | locate(StandardLocation type, const QString &fileName, LocateOptions options = LocateFile) |
| QStringList | locateAll(StandardLocation type, const QString &fileName, LocateOptions options = LocateFile) |
| void | setTestModeEnabled(bool testMode) |
| QStringList | standardLocations(StandardLocation type) |
| QString | writableLocation(StandardLocation type) |
Подробное описание
Класс QStandardPaths предоставляет методы для доступа к стандартным путям.
Этот класс содержит функции для запроса стандартных расположений на локальной файловой системе для общих задач, таких как каталоги, относящиеся к пользователю, или системные каталоги конфигурации.
Документация по типам членов
перечисление 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::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" |
| 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" |
| AppLocalDataLocation | "~/Library/Application Support/<APPNAME>", "/Library/Application Support/<APPNAME>". "<APPDIR>/../Resources" | "C:/Users/<USER>/AppData/Local/<APPNAME>", "C:/ProgramData/<APPNAME>", "<APPDIR>", "<APPDIR>/data" |
| AppConfigLocation | "~/Library/Preferences/<APPNAME>" | "C:/Users/<USER>/AppData/Local/<APPNAME>", "C:/ProgramData/<APPNAME>" |
| Тип пути | Blackberry | Linux |
|---|---|---|
| DesktopLocation | "<APPROOT>/data" | "~/Рабочий стол" |
| DocumentsLocation | "<APPROOT>/shared/documents" | "~/Документы" |
| FontsLocation | "/base/usr/fonts" (не доступно для записи) | "~/.fonts" |
| ApplicationsLocation | не поддерживается (каталог недоступен для чтения) | "~/.local/share/applications", "/usr/local/share/applications", "/usr/share/applications" |
| MusicLocation | "<APPROOT>/shared/music" | "~/Музыка" |
| MoviesLocation | "<APPROOT>/shared/videos" | "~/Видео" |
| PicturesLocation | "<APPROOT>/shared/photos" | "~/Изображения" |
| TempLocation | "/var/tmp" | "/tmp" |
| HomeLocation | "<APPROOT>/data" | "~" |
| DataLocation | "<APPROOT>/data", "<APPROOT>/app/native/assets" | "~/.local/share/<APPNAME>", "/usr/local/share/<APPNAME>", "/usr/share/<APPNAME>" |
| CacheLocation | "<APPROOT>/data/Cache" | "~/.cache/<APPNAME>" |
| GenericDataLocation | "<APPROOT>/shared/misc" | "~/.local/share", "/usr/local/share", "/usr/share" |
| RuntimeLocation | "/var/tmp" | "/run/user/<USER>" |
| ConfigLocation | "<APPROOT>/data/Settings" | "~/.config", "/etc/xdg" |
| GenericConfigLocation | "<APPROOT>/data/Settings" | "~/.config", "/etc/xdg" |
| DownloadLocation | "<APPROOT>/shared/downloads" | "~/Загрузки" |
| GenericCacheLocation | "<APPROOT>/data/Cache" (нет общего кэша) | "~/.cache" |
| AppDataLocation | "<APPROOT>/data", "<APPROOT>/app/native/assets" | "~/.local/share/<APPNAME>", "/usr/local/share/<APPNAME>", "/usr/share/<APPNAME>" |
| AppLocalDataLocation | "<APPROOT>/data", "<APPROOT>/app/native/assets" | "~/.local/share/<APPNAME>", "/usr/local/share/<APPNAME>", "/usr/share/<APPNAME>" |
| AppConfigLocation | "<APPROOT>/data/Settings" | "~/.config/<APPNAME>", "/etc/xdg/<APPNAME>" |
| Тип пути | Android | iOS |
|---|---|---|
| DesktopLocation | "<APPROOT>/files" | "<APPROOT>/<APPDIR>" (не доступно для записи) |
| DocumentsLocation | "<USER>/Документы", "<USER>/<APPNAME>/Документы" | "<APPROOT>/Документы" |
| FontsLocation | "/system/fonts" (не доступно для записи) | "<APPROOT>/Документы/.fonts" |
| 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" | "<APPROOT>/<APPDIR>" (не доступно для записи) |
| DataLocation | "<APPROOT>/files", "<USER>/<APPNAME>/files" | "<APPROOT>/Library/Application Support" |
| CacheLocation | "<APPROOT>/cache", "<USER>/<APPNAME>/cache" | "<APPROOT>/Library/Caches" |
| GenericDataLocation | "<USER>" | "<APPROOT>/Документы" |
| RuntimeLocation | "<APPROOT>/cache" | не поддерживается |
| ConfigLocation | "<APPROOT>/files/settings" | "<APPROOT>/Документы" |
| GenericConfigLocation | "<APPROOT>/files/settings" (нет общего настроек) | "<APPROOT>/Документы" |
| DownloadLocation | "<USER>/Загрузки", "<USER>/<APPNAME>/Загрузки" | "<APPROOT>/Документы/Загрузки" |
| GenericCacheLocation | "<APPROOT>/cache" (нет общего кэша) | "<APPROOT>/Library/Caches" |
| AppDataLocation | "<APPROOT>/files", "<USER>/<APPNAME>/files" | "<APPROOT>/Library/Application Support" |
| AppConfigLocation | "<APPROOT>/files/settings" | "<APPROOT>/Документы" |
| AppLocalDataLocation | "<APPROOT>/files", "<USER>/<APPNAME>/files" | "<APPROOT>/Library/Application Support" |
В таблице выше, <APPNAME> обычно является названием организации, названием приложения или тем и другим, или уникальным именем, сгенерированным при упаковке. Аналогично, <APPROOT> — это место, где установлено это приложение (часто виртуальная среда). <APPDIR> — это каталог, содержащий исполняемый файл приложения.
Не следует полагаться на указанные выше пути, поскольку они могут изменяться в зависимости от конфигурации ОС, языка или могут измениться в будущих версиях Qt.
Примечание: На Android приложения с открытыми файлами во внешней памяти (<USER> расположения) будут завершены, если внешняя память будет отключена.
Примечание: На iOS, если вы передадите QStandardPaths::standardLocations(QStandardPaths::PicturesLocation).last() в качестве аргумента в QFileDialog::setDirectory(), будет использоваться встроенный диалог выбора изображения для доступа к фотоальбому пользователя. Имя файла, возвращаемое значение, может быть загружено с помощью QFile и связанных API. Эта функция была добавлена в Qt 5.5.
См. также writableLocation(), standardLocations(), displayName(), locate(), и locateAll().
Документация функций-членов
[static] QString QStandardPaths::displayName(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(StandardLocation type, const QString &fileName, LocateOptions options = LocateFile)
Пытается найти файл или каталог с именем fileName в стандартных расположениях для type.
Возвращается полный путь к первому найденному файлу или каталогу (в зависимости от options). Если такой файл или каталог не найден, возвращается пустая строка.
[static] QStringList QStandardPaths::locateAll(StandardLocation type, const QString &fileName, LocateOptions options = LocateFile)
Пытается найти все файлы или каталоги с именем fileName в стандартных расположениях для type.
Флаг options позволяет указать, искать ли файлы или каталоги.
Возвращает список всех найденных файлов.
[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" в каталоге данных приложения.
[static] QStringList QStandardPaths::standardLocations(StandardLocation type)
Возвращает все каталоги, где находятся файлы типа type.
Список каталогов отсортирован по приоритету, начиная с writableLocation() если он может быть определён. Этот список пуст, если для типа type не определено никаких расположений.
См. также writableLocation().
[static] QString QStandardPaths::writableLocation(StandardLocation type)
Возвращает каталог, в который следует записывать файлы типа type, или пустую строку, если расположение определить нельзя.
Примечание: Возвращаемое расположение хранения может быть каталогом, который не существует; т.е., его может потребоваться создать системе или пользователю.
© The Qt Company Ltd
Licensed under the GNU Free Documentation License, Version 1.3.
https://doc.qt.io/archives/qt-5.6/qstandardpaths.html
