Класс QStandardPaths
Класс QStandardPaths предоставляет методы для доступа к стандартным путям. Подробнее...
| Заголовок: | #include <QStandardPaths> |
| CMake: | find_package(Qt6 COMPONENTS Core REQUIRED) target_link_libraries(mytarget PRIVATE Qt6::Core) |
| qmake: | QT += core |
| С версии: | 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::AppLocalDataLocation |
9 |
Возвращает путь к локальным настройкам в операционной системе Windows. На всех других платформах возвращает то же значение, что и AppDataLocation. Это значение перечисления было добавлено в Qt 5.4. |
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 это возвращает путь для общих данных. Это значение перечисления было добавлено в Qt 5.4. |
QStandardPaths::AppConfigLocation |
18 |
Возвращает расположение папки, где следует записывать конфигурационные файлы пользователя. Это папка, специфичная для приложения, и возвращаемый путь никогда не пустой. Это значение перечисления было добавлено в Qt 5.5. |
В следующей таблице приведены примеры путей на разных операционных системах. Первый путь — это путь для записи (если не указано иное). Другие дополнительные пути, если таковые имеются, представляют собой не-записываемые местоположения.
| Тип пути | macOS | Windows |
|---|---|---|
| DesktopLocation | "~/Desktop" | "C:/Пользователи/<ПОЛЬЗОВАТЕЛЬ>/Рабочий стол" |
| DocumentsLocation | "~/Документы" | "C:/Пользователи/<ПОЛЬЗОВАТЕЛЬ>/Документы" |
| FontsLocation | "/System/Library/Fonts" (не для записи) | "C:/Windows/Fonts" (не для записи) |
| ApplicationsLocation | "/Applications" (не для записи) | "C:/Пользователи/<ПОЛЬЗОВАТЕЛЬ>/AppData/Roaming/Microsoft/Windows/Пуск/Программы" |
| MusicLocation | "~/Музыка" | "C:/Пользователи/<ПОЛЬЗОВАТЕЛЬ>/Музыка" |
| MoviesLocation | "~/Фильмы" | "C:/Пользователи/<ПОЛЬЗОВАТЕЛЬ>/Видео" |
| PicturesLocation | "~/Изображения" | "C:/Пользователи/<ПОЛЬЗОВАТЕЛЬ>/Изображения" |
| TempLocation | случайно генерируется ОС | "C:/Пользователи/<ПОЛЬЗОВАТЕЛЬ>/AppData/Local/Временные файлы" |
| HomeLocation | "~" | "C:/Пользователи/<ПОЛЬЗОВАТЕЛЬ>" |
| AppLocalDataLocation | "~/Библиотека/Поддержка приложений/<НАЗВАНИЕ_ПРИЛОЖЕНИЯ>", "/Библиотека/Поддержка приложений/<НАЗВАНИЕ_ПРИЛОЖЕНИЯ>". "<ПУТЬ_К_ПРИЛОЖЕНИЮ>/../Ресурсы" | "C:/Пользователи/<ПОЛЬЗОВАТЕЛЬ>/AppData/Local/<НАЗВАНИЕ_ПРИЛОЖЕНИЯ>", "C:/Общие данные/<НАЗВАНИЕ_ПРИЛОЖЕНИЯ>", "<ПУТЬ_К_ПРИЛОЖЕНИЮ>", "<ПУТЬ_К_ПРИЛОЖЕНИЮ>/данные", "<ПУТЬ_К_ПРИЛОЖЕНИЮ>/данные/<НАЗВАНИЕ_ПРИЛОЖЕНИЯ>" |
| CacheLocation | "~/Библиотека/Кэши/<НАЗВАНИЕ_ПРИЛОЖЕНИЯ>", "/Библиотека/Кэши/<НАЗВАНИЕ_ПРИЛОЖЕНИЯ>" | "C:/Пользователи/<ПОЛЬЗОВАТЕЛЬ>/AppData/Local/<НАЗВАНИЕ_ПРИЛОЖЕНИЯ>/кэш" |
| GenericDataLocation | "~/Библиотека/Поддержка приложений", "/Библиотека/Поддержка приложений" | "C:/Пользователи/<ПОЛЬЗОВАТЕЛЬ>/AppData/Local", "C:/Общие данные", "<ПУТЬ_К_ПРИЛОЖЕНИЮ>", "<ПУТЬ_К_ПРИЛОЖЕНИЮ>/данные" |
| RuntimeLocation | "~/Библиотека/Поддержка приложений" | "C:/Пользователи/<ПОЛЬЗОВАТЕЛЬ>" |
| ConfigLocation | "~/Библиотека/Настройки" | "C:/Пользователи/<ПОЛЬЗОВАТЕЛЬ>/AppData/Local/<НАЗВАНИЕ_ПРИЛОЖЕНИЯ>", "C:/Общие данные/<НАЗВАНИЕ_ПРИЛОЖЕНИЯ>" |
| GenericConfigLocation | "~/Библиотека/Настройки" | "C:/Пользователи/<ПОЛЬЗОВАТЕЛЬ>/AppData/Local", "C:/Общие данные" |
| DownloadLocation | "~/Загрузки" | "C:/Пользователи/<ПОЛЬЗОВАТЕЛЬ>/Документы" |
| GenericCacheLocation | "~/Библиотека/Кэши", "/Библиотека/Кэши" | "C:/Пользователи/<ПОЛЬЗОВАТЕЛЬ>/AppData/Local/кэш" |
| AppDataLocation | "~/Библиотека/Поддержка приложений/<НАЗВАНИЕ_ПРИЛОЖЕНИЯ>", "/Библиотека/Поддержка приложений/<НАЗВАНИЕ_ПРИЛОЖЕНИЯ>". "<ПУТЬ_К_ПРИЛОЖЕНИЮ>/../Ресурсы" | "C:/Пользователи/<ПОЛЬЗОВАТЕЛЬ>/AppData/Roaming/<НАЗВАНИЕ_ПРИЛОЖЕНИЯ>", "C:/Общие данные/<НАЗВАНИЕ_ПРИЛОЖЕНИЯ>", "<ПУТЬ_К_ПРИЛОЖЕНИЮ>", "<ПУТЬ_К_ПРИЛОЖЕНИЮ>/данные", "<ПУТЬ_К_ПРИЛОЖЕНИЮ>/данные/<НАЗВАНИЕ_ПРИЛОЖЕНИЯ>" |
| AppConfigLocation | "~/Библиотека/Настройки/<НАЗВАНИЕ_ПРИЛОЖЕНИЯ>" | "C:/Пользователи/<ПОЛЬЗОВАТЕЛЬ>/AppData/Local/<НАЗВАНИЕ_ПРИЛОЖЕНИЯ>", "C:/Общие данные/<НАЗВАНИЕ_ПРИЛОЖЕНИЯ>" |
| Тип пути | 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 | "~" |
| AppLocalDataLocation | "~/.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>" |
| AppConfigLocation | "~/.config/<APPNAME>", "/etc/xdg/<APPNAME>" |
| Тип пути | Android | iOS |
|---|---|---|
| DesktopLocation | "<APPROOT>/files" | "<APPROOT>/Документы/Рабочий стол" |
| DocumentsLocation | "<USER>/Документы", "<USER>/<APPNAME>/Документы" | "<APPROOT>/Документы" |
| FontsLocation | "/system/fonts" (недоступно для записи) | "<APPROOT>/Library/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" | определяется системой |
| AppLocalDataLocation | "<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>/Library/Preferences" |
| GenericConfigLocation | "<APPROOT>/files/settings" (нет общих настроек) | "<APPROOT>/Library/Preferences" |
| 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>/Library/Preferences/<APPNAME>" |
В таблице выше, <APPNAME> обычно представляет название организации, приложения или их сочетание, или уникальное имя, сгенерированное при упаковке. Аналогично, <APPROOT> - это место установки данного приложения (часто песочница). <APPDIR> - это каталог, содержащий исполняемый файл приложения.
Не следует полагаться на указанные выше пути, поскольку они могут изменяться в зависимости от конфигурации ОС, региональных настроек или в будущих версиях Qt.
Примечание: На Android приложения с открытыми файлами во внешней памяти (<USER> расположения) будут закрыты, если внешняя память будет отмонтирована.
Примечание: На Android 6.0 (API 23) или более поздних версиях необходимо запросить разрешение "WRITE_EXTERNAL_STORAGE" во время выполнения при использовании QStandardPaths::writableLocation или QStandardPaths::standardLocations.
Примечание: На Android для чтения/записи в GenericDataLocation необходимо разрешение READ_EXTERNAL_STORAGE/WRITE_EXTERNAL_STORAGE.
Примечание: На 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, AppDataLocation, 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-6.1/qstandardpaths.html
