Класс QFileSelector

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

Этот класс был введён в Qt 5.2.

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

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

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

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 ищет в том же каталоге, что и базовый файл. Если существуют каталоги вида +<селектор> с активным селектором, 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().