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

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

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

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

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

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