Класс QFileSelector

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

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

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

• 31 открытых функций, унаследованных от 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_BLACKBERRY)
    defaultsPath = "data/blackberry/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/+blackberry/defaults.conf
data/+ios/+en_GB/defaults.conf

Чтобы найти выбранные файлы, QFileSelector ищет в той же директории, что и базовый файл. Если есть какие-либо директории вида +<selector> с активным селектором, QFileSelector отдаст предпочтение файлу с тем же именем из этой директории, а не базовому файлу. Эти директории могут быть вложены для проверки по нескольким селекторам, например:

images/background.png
images/+android/+en_GB/background.png
images/+blackberry/+en_GB/background.png

С этими файлами вы бы выбрали другой файл на платформах Android и Blackberry, но только если локаль была en_GB.

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

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

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

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

• платформа, любой из следующих строк, которые соответствуют платформе, на которой работает приложение (список не исчерпывающий): android, blackberry, ios, osx, darwin, mac, linux, wince, 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().