Класс QStandardPaths
Класс QStandardPaths предоставляет методы для доступа к стандартным путям. Подробнее...
| Заголовок: | #include <QStandardPaths> |
| qmake: | QT += core |
| С тех пор: | Qt 5.0 |
Публичные типы
| Перечисление | LocateOption { LocateFile, LocateDirectory } |
| Флаги | LocateOptions |
| Перечисление | StandardLocation { DesktopLocation, DocumentsLocation, FontsLocation, ApplicationsLocation, ..., 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 предоставляет методы для доступа к стандартным путям.
Этот класс содержит функции для запроса стандартных расположений в локальной файловой системе для общих задач, таких как каталоги, относящиеся к пользователю, или каталоги конфигурации для всей системы.
Документация типов членов
перечисление 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", "<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 | "~/.шрифты" |
| ApplicationsLocation | "~/.local/share/приложения", "/usr/local/share/приложения", "/usr/share/приложения" |
| 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/шрифты" (не доступно для записи) | "<APPROOT>/Library/Шрифты" |
| ApplicationsLocation | не поддерживается (каталог недоступен для чтения) | не поддерживается |
| MusicLocation | "<USER>/Музыка", "<USER>/<APPNAME>/Музыка" | "<APPROOT>/Документы/Музыка" |
| MoviesLocation | "<USER>/Фильмы", "<USER>/<APPNAME>/Фильмы" | "<APPROOT>/Документы/Фильмы" |
| PicturesLocation | "<USER>/Изображения", "<USER>/<APPNAME>/Изображения" | "<APPROOT>/Документы/Изображения", "assets-library://" |
| TempLocation | "<APPROOT>/кеш" | "<APPROOT>/tmp" |
| HomeLocation | "<APPROOT>/files" | "<APPROOT>" (не доступно для записи) |
| DataLocation | "<APPROOT>/files", "<USER>/<APPNAME>/files" | "<APPROOT>/Library/Application Support" |
| CacheLocation | "<APPROOT>/кеш", "<USER>/<APPNAME>/кеш" | "<APPROOT>/Library/Кэши" |
| GenericDataLocation | "<USER>" | "<APPROOT>/Документы" |
| RuntimeLocation | "<APPROOT>/кеш" | не поддерживается |
| ConfigLocation | "<APPROOT>/files/настройки" | "<APPROOT>/Library/Настройки" |
| GenericConfigLocation | "<APPROOT>/files/настройки" (нет общих настроек) | "<APPROOT>/Library/Настройки" |
| DownloadLocation | "<USER>/Загрузки", "<USER>/<APPNAME>/Загрузки" | "<APPROOT>/Документы/Загрузки" |
| GenericCacheLocation | "<APPROOT>/кеш" (нет общего кэша) | "<APPROOT>/Library/Кэши" |
| AppDataLocation | "<APPROOT>/files", "<USER>/<APPNAME>/files" | "<APPROOT>/Library/Application Support" |
| AppConfigLocation | "<APPROOT>/files/настройки" | "<APPROOT>/Library/Настройки/<APPNAME>" |
| 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(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). Если такой файл или каталог не найден, возвращается пустая строка.
[static] QStringList QStandardPaths::locateAll(QStandardPaths::StandardLocation type, const QString &fileName, QStandardPaths::LocateOptions options = LocateFile)
Попытка найти все файлы или каталоги с именем fileName в стандартных расположениях для type.
Флаг options позволяет указать, нужно ли искать файлы или каталоги.
Возвращает список всех найденных файлов.
[static] void QStandardPaths::setTestModeEnabled(bool testMode)
Если testMode истинно, это включает специальный «режим тестирования» в 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/Настройки.
В Windows, всё попадает в каталог «qttest» в «Данные приложения».
[static] QStringList QStandardPaths::standardLocations(QStandardPaths::StandardLocation type)
Возвращает все каталоги, в которых хранятся файлы типа type.
Список каталогов отсортирован по приоритету сверху вниз, начиная с writableLocation(), если его можно определить. Этот список пуст, если для типа type не определены каталоги.
См. также 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/archives/qt-5.11/qstandardpaths.html
