Класс QFileSelector

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

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

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

• 32 открытых функции унаследованы от QObject

Статические открытые члены

• 10 статических открытых членов унаследованы от QObject

Дополнительные унаследованные члены

• 1 свойство унаследовано от QObject
• 1 открытый слот унаследован от QObject
• 2 сигнала унаследованы от QObject
• 9 защищенных функций унаследованы от QObject

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

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