Класс 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 { ПапкаРабочегоСтола, ПапкаДокументов, ПапкаШрифтов, ПапкаПриложений, ПапкаМузыка, …, ПапкаНастроекПриложения } |
Статические публичные члены
| 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, объединенных по OR.
Перечисление 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 | "~/.шрифты", "~/.local/share/шрифты", "/usr/local/share/шрифты", "/usr/share/шрифты" |
| ApplicationsLocation | "~/.local/share/приложения", "/usr/local/share/приложения", "/usr/share/приложения" |
| 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/шрифты" (не для записи) | "<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>/файлы" | определено системой |
| AppLocalDataLocation | "<APPROOT>/файлы", "<USER>/<APPNAME>/файлы" | "<APPROOT>/Library/Поддержка приложения" |
| CacheLocation | "<APPROOT>/кеш", "<USER>/<APPNAME>/кеш" | "<APPROOT>/Library/Кэши" |
| GenericDataLocation | "<USER>" | "<APPROOT>/Документы" |
| RuntimeLocation | "<APPROOT>/кеш" | не поддерживается |
| ConfigLocation | "<APPROOT>/файлы/настройки" | "<APPROOT>/Library/Предпочтения" |
| GenericConfigLocation | "<APPROOT>/файлы/настройки" (нет общих настроек) | "<APPROOT>/Library/Предпочтения" |
| DownloadLocation | "<USER>/Загрузки", "<USER>/<APPNAME>/Загрузки" | "<APPROOT>/Документы/Загрузки" |
| GenericCacheLocation | "<APPROOT>/кеш" (нет общего кэша) | "<APPROOT>/Library/Кэши" |
| AppDataLocation | "<APPROOT>/файлы", "<USER>/<APPNAME>/файлы" | "<APPROOT>/Library/Поддержка приложения" |
| AppConfigLocation | "<APPROOT>/файлы/настройки" | "<APPROOT>/Library/Предпочтения/<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() в случае его определения. Этот список пуст, если для типа 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/qt-6.2/qstandardpaths.html
