Класс 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().