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