Класс QStandardPaths
Класс QStandardPaths предоставляет методы для доступа к стандартным путям. Подробнее...
| Заголовок: | #include <QStandardPaths> |
| qmake: | QT += core |
| С момента: | Qt 5.0 |
Этот класс был представлен в 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::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:/Пользователи/<ПОЛЬЗОВАТЕЛЬ>/Рабочий стол" |
| 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:/Пользователи/<ПОЛЬЗОВАТЕЛЬ>" |
| DataLocation | "~/Библиотека/Поддержка приложений/<НАЗВАНИЕ_ПРИЛОЖЕНИЯ>", "/Библиотека/Поддержка приложений/<НАЗВАНИЕ_ПРИЛОЖЕНИЯ>". "<ПУТЬ_К_ПРИЛОЖЕНИЮ>/../Ресурсы" | "C:/Пользователи/<ПОЛЬЗОВАТЕЛЬ>/AppData/Local/<НАЗВАНИЕ_ПРИЛОЖЕНИЯ>", "C:/ProgramData/<НАЗВАНИЕ_ПРИЛОЖЕНИЯ>", "<ПУТЬ_К_ПРИЛОЖЕНИЮ>", "<ПУТЬ_К_ПРИЛОЖЕНИЮ>/данные", "<ПУТЬ_К_ПРИЛОЖЕНИЮ>/данные/<НАЗВАНИЕ_ПРИЛОЖЕНИЯ>" |
| CacheLocation | "~/Библиотека/Кэши/<НАЗВАНИЕ_ПРИЛОЖЕНИЯ>", "/Библиотека/Кэши/<НАЗВАНИЕ_ПРИЛОЖЕНИЯ>" | "C:/Пользователи/<ПОЛЬЗОВАТЕЛЬ>/AppData/Local/<НАЗВАНИЕ_ПРИЛОЖЕНИЯ>/кэш" |
| GenericDataLocation | "~/Библиотека/Поддержка приложений", "/Библиотека/Поддержка приложений" | "C:/Пользователи/<ПОЛЬЗОВАТЕЛЬ>/AppData/Local", "C:/ProgramData", "<ПУТЬ_К_ПРИЛОЖЕНИЮ>", "<ПУТЬ_К_ПРИЛОЖЕНИЮ>/данные" |
| RuntimeLocation | "~/Библиотека/Поддержка приложений" | "C:/Пользователи/<ПОЛЬЗОВАТЕЛЬ>" |
| ConfigLocation | "~/Библиотека/Настройки" | "C:/Пользователи/<ПОЛЬЗОВАТЕЛЬ>/AppData/Local/<НАЗВАНИЕ_ПРИЛОЖЕНИЯ>", "C:/ProgramData/<НАЗВАНИЕ_ПРИЛОЖЕНИЯ>" |
| GenericConfigLocation | "~/Библиотека/Настройки" | "C:/Пользователи/<ПОЛЬЗОВАТЕЛЬ>/AppData/Local", "C:/ProgramData" |
| DownloadLocation | "~/Загрузки" | "C:/Пользователи/<ПОЛЬЗОВАТЕЛЬ>/Документы" |
| GenericCacheLocation | "~/Библиотека/Кэши", "/Библиотека/Кэши" | "C:/Пользователи/<ПОЛЬЗОВАТЕЛЬ>/AppData/Local/кэш" |
| AppDataLocation | "~/Библиотека/Поддержка приложений/<НАЗВАНИЕ_ПРИЛОЖЕНИЯ>", "/Библиотека/Поддержка приложений/<НАЗВАНИЕ_ПРИЛОЖЕНИЯ>". "<ПУТЬ_К_ПРИЛОЖЕНИЮ>/../Ресурсы" | "C:/Пользователи/<ПОЛЬЗОВАТЕЛЬ>/AppData/Roaming/<НАЗВАНИЕ_ПРИЛОЖЕНИЯ>", "C:/ProgramData/<НАЗВАНИЕ_ПРИЛОЖЕНИЯ>", "<ПУТЬ_К_ПРИЛОЖЕНИЮ>", "<ПУТЬ_К_ПРИЛОЖЕНИЮ>/данные", "<ПУТЬ_К_ПРИЛОЖЕНИЮ>/данные/<НАЗВАНИЕ_ПРИЛОЖЕНИЯ>" |
| AppLocalDataLocation | "~/Библиотека/Поддержка приложений/<НАЗВАНИЕ_ПРИЛОЖЕНИЯ>", "/Библиотека/Поддержка приложений/<НАЗВАНИЕ_ПРИЛОЖЕНИЯ>". "<ПУТЬ_К_ПРИЛОЖЕНИЮ>/../Ресурсы" | "C:/Пользователи/<ПОЛЬЗОВАТЕЛЬ>/AppData/Local/<НАЗВАНИЕ_ПРИЛОЖЕНИЯ>", "C:/ProgramData/<НАЗВАНИЕ_ПРИЛОЖЕНИЯ>", "<ПУТЬ_К_ПРИЛОЖЕНИЮ>", "<ПУТЬ_К_ПРИЛОЖЕНИЮ>/данные", "<ПУТЬ_К_ПРИЛОЖЕНИЮ>/данные/<НАЗВАНИЕ_ПРИЛОЖЕНИЯ>" |
| AppConfigLocation | "~/Библиотека/Настройки/<НАЗВАНИЕ_ПРИЛОЖЕНИЯ>" | "C:/Пользователи/<ПОЛЬЗОВАТЕЛЬ>/AppData/Local/<НАЗВАНИЕ_ПРИЛОЖЕНИЯ>", "C:/ProgramData/<НАЗВАНИЕ_ПРИЛОЖЕНИЯ>" |
| Тип пути | 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/Preferences/<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 равно 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» в Application Data.
[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-5.13/qstandardpaths.html
