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

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

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

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