Класс QFileSelector

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

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

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

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

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

• 1 свойство унаследовано от QObject
• 1 открытый слот унаследован от QObject
• 2 сигнала унаследовано от QObject
• 11 статических открытых членов унаследовано от 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 предоставляет удобную альтернативу написанию такого boilerplate-кода, и в последнем случае он позволяет вам начать использовать платформозависимую конфигурацию без перекомпиляции. 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 = Q_NULLPTR)

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

Если указан, он будет иметь заданного QObject parent.

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().