Класс QFileSelector

Класс QFileSelector предоставляет удобный способ выбора вариантов файлов. Подробнее...

• Список всех членов, включая унаследованные

Открытые функции

Подробное описание

QFileSelector — удобный инструмент для выбора вариантов файлов на основе характеристик платформы или устройства. Это позволяет разрабатывать и развертывать один код, содержащий все различные варианты, проще в некоторых ситуациях, таких как когда правильный вариант не может быть определен на этапе развертывания.

Использование QFileSelector

Если вы всегда используете один и тот же файл, вам не нужно использовать QFileSelector.

Рассмотрим следующий пример использования, где вы хотите использовать разные файлы настроек в разных языковых локалях. Вы можете выбирать код между локалями так:

    QString defaultsBasePath = "data/";
    QString defaultsPath = defaultsBasePath + "defaults.conf";
    QString localizedPath = defaultsBasePath
            + QString("%1/defaults.conf").arg(QLocale().name());
    if (QFile::exists(localizedPath))
        defaultsPath = localizedPath;
    QFile defaults(defaultsPath);

Аналогично, если вы хотите выбрать другой файл данных на основе целевой платформы, ваш код может выглядеть примерно так:

    QString defaultsPath = "data/defaults.conf";
#if defined(Q_OS_ANDROID)
    defaultsPath = "data/android/defaults.conf";
#elif defined(Q_OS_IOS)
    defaultsPath = "data/ios/defaults.conf";
#endif
    QFile defaults(defaultsPath);

QFileSelector предоставляет удобную альтернативу написанию такого шаблонизированного кода, а в последнем случае позволяет начать использовать платформоспецифические настройки без перекомпиляции. QFileSelector также позволяет цеплять несколько селекторов удобным способом, например, выбирая другой файл только при определенных комбинациях платформы и локали. Например, для выбора на основе платформы и/или локали код выглядит следующим образом:

    QFileSelector selector;
    QFile defaultsFile(selector.select("data/defaults.conf"));

Файлы, которые нужно выбрать, размещаются в каталогах, имеющих имя с '+' и именем селектора. В приведенном выше примере вы можете иметь платформенные конфигурации, размещенные в следующих расположениях:

    data/defaults.conf
    data/+android/defaults.conf
    data/+ios/+en_GB/defaults.conf

Для поиска выбранных файлов QFileSelector ищет в той же директории, что и базовый файл. Если есть какие-либо каталоги вида +<selector> с активным селектором, QFileSelector отдаст предпочтение файлу с тем же именем из этого каталога по сравнению с базовым файлом. Эти каталоги могут быть вложены для проверки по множеству селекторов, например:

    images/background.png
    images/+android/+en_GB/background.png

С этими файлами вы бы выбрали другой файл на платформе Android, но только если локаль была en_GB.

Для обработки ошибок в случае отсутствия допустимых селекторов рекомендуется иметь по умолчанию или файл обработки ошибок в базовом расположении файла, даже если вы ожидаете, что селекторы будут присутствовать для всех развертываний.

В будущей версии некоторые из них могут быть помечены как статические на этапе развертывания и перемещены во время развертывания как оптимизация. Поскольку селекторы имеют стоимость производительности, рекомендуется избегать их использования в ситуациях, связанных с критическими для производительности кодами.

Добавление селекторов

Обычно доступны следующие селекторы:

• платформа, любое из следующих строк, соответствующих платформе, на которой работает приложение (не исчерпывающий список): android, ios, osx, darwin, mac, macos, linux, qnx, unix, windows. В Linux, если это возможно определить, также указывается имя дистрибутива, например, debian, fedora или opensuse.
• локаль, такая же, как QLocale().name().

Дополнительные селекторы будут добавлены из переменной среды QT_FILE_SELECTORS, которая при установке должна быть набором селекторов, разделенных запятыми. Обратите внимание, что эта переменная будет прочитана только один раз; селекторы могут не обновляться, если переменная изменяется во время работы приложения. Начальный набор селекторов оценивается только один раз, при первом использовании.

Вы также можете добавить дополнительные селекторы во время выполнения для пользовательского поведения. Они будут использоваться в любых последующих вызовах select(). Если список дополнительных селекторов был изменен, вызовы select() будут использовать новый список и могут возвращать разные результаты.

Разрешение конфликтов при применении нескольких селекторов

Когда несколько селекторов могут быть применены к одному файлу, выбирается первый соответствующий селектор. Порядок проверки селекторов:

1. Селекторы, заданные с помощью setExtraSelectors(), в порядке их расположения в списке
2. Селекторы в переменной среды QT_FILE_SELECTORS, слева направо
3. Локаль
4. Платформа

Вот пример, связанный с несколькими селекторами, которые одновременно соответствуют одному файлу. Он использует селекторы платформы, а также дополнительный селектор с именем «admin», устанавливаемый приложением в зависимости от учетных данных пользователя. Пример отсортирован таким образом, что наиболее соответствующий файл будет выбран, если все селекторы присутствуют:

    images/background.png
    images/+linux/background.png
    images/+windows/background.png
    images/+admin/background.png
    images/+admin/+linux/background.png

Поскольку дополнительные селекторы проверяются до платформы, +admin/background.png будет выбран в Windows, когда селектор «admin» установлен, и +windows/background.png будет выбран в Windows, когда селектор «admin» не установлен. В Linux +admin/+linux/background.png будет выбран, когда селектор «admin» установлен, и +linux/background.png — когда он не установлен.

Документация по функциям-членам

QFileSelector::QFileSelector(QObject *parent = nullptr)

Создает экземпляр QFileSelector. Этот экземпляр будет иметь те же статические селекторы, что и другие экземпляры QFileSelector, но свой собственный набор дополнительных селекторов.

Если указан, он будет иметь заданный QObject parent.

[virtual] QFileSelector::~QFileSelector()

Уничтожает этот экземпляр селектора.

QStringList QFileSelector::allSelectors() const

Возвращает полный, упорядоченный список селекторов, используемых данным экземпляром.

QStringList QFileSelector::extraSelectors() const

Возвращает список дополнительных селекторов, которые были добавлены программно в данный экземпляр.

См. также setExtraSelectors().

QString QFileSelector::select(const QString &filePath) const

Эта функция возвращает выбранную версию пути, основанную на условиях во время выполнения. Если нет файлов для выбора, возвращает исходный filePath.

Если исходный файл не существует, возвращается исходный filePath. Это означает, что у вас должен быть базовый файл для обратной связи, вы не можете иметь только файлы в подкаталогах для выбора.

См. обзор класса для алгоритма выбора.

QUrl QFileSelector::select(const QUrl &filePath) const

Это удобная версия select, работающая с объектами QUrl. Если схема не file или qrc, filePath возвращается немедленно. В противном случае выбор применяется к пути filePath, и возвращается QUrl с выбранным путем и другими частями QUrl, такими же, как у filePath.

См. обзор класса для алгоритма выбора.

void QFileSelector::setExtraSelectors(const QStringList &list)

Устанавливает list дополнительных селекторов, которые были добавлены программно в данный экземпляр.

Эти селекторы имеют приоритет над любыми, которые были автоматически выбраны.

См. также extraSelectors().