Класс QQuickImageProvider

Класс QQuickImageProvider предоставляет интерфейс для поддержки растровых изображений и потоковых запросов к изображениям в QML. Подробнее...

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

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

Переопределенные открытые функции

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

QQuickImageProvider используется для обеспечения расширенных функций загрузки изображений в приложениях QML. Он позволяет загружать изображения в QML:

• Используя QPixmap, а не реальные файлы изображений
• Асинхронно в отдельном потоке

Чтобы указать, что изображение должно загружаться поставщиком изображений, используйте схему "image:" для URL-источника изображения, за которой следуют идентификаторы поставщика изображений и запрашиваемого изображения. Например:

Image { source: "image://myimageprovider/image.png" }

Это указывает, что изображение должно загружаться поставщиком изображений с именем "myimageprovider", и изображение для загрузки имеет имя "image.png". Движок QML вызывает соответствующий поставщик изображений в соответствии с поставщиками, которые были зарегистрированы с помощью QQmlEngine::addImageProvider().

Обратите внимание, что идентификаторы регистронезависимы, но остальная часть URL-адреса будет передаваться с сохранением регистра. Например, приведенный ниже фрагмент по-прежнему будет указывать, что изображение загружается поставщиком изображений с именем "myimageprovider", но он будет запрашивать другое изображение, чем приведенный выше фрагмент ("Image.png" вместо "image.png").

Image { source: "image://MyImageProvider/Image.png" }

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

Пример

Вот два изображения. Их source значения указывают, что они должны загружаться поставщиком изображений с именем "colors", и изображения для загрузки — "yellow" и "red" соответственно:

Column {
    Image { source: "image://colors/yellow" }
    Image { source: "image://colors/red" }
}

При загрузке этих изображений QML ищет соответствующий поставщик изображений и вызывает его метод requestImage() или requestPixmap() (в зависимости от его imageType()) для загрузки изображения. Метод вызывается со значением параметра id, установленным на "yellow" для первого изображения и "red" для второго.

Вот реализация поставщика изображений, который может загружать изображения, запрашиваемые вышеуказанным QML. Эта реализация динамически генерирует QPixmap изображения, заполненные запрошенным цветом:

class ColorImageProvider : public QQuickImageProvider
{
public:
    ColorImageProvider()
               : QQuickImageProvider(QQuickImageProvider::Pixmap)
    {
    }

    QPixmap requestPixmap(const QString &id, QSize *size, const QSize &requestedSize) override
    {
       int width = 100;
       int height = 50;

       if (size)
          *size = QSize(width, height);
       QPixmap pixmap(requestedSize.width() > 0 ? requestedSize.width() : width,
                      requestedSize.height() > 0 ? requestedSize.height() : height);
       pixmap.fill(QColor(id).rgba());
       return pixmap;
    }
};

Чтобы сделать этот поставщик доступным для QML, он регистрируется в движке QML с идентификатором "colors":

int main(int argc, char *argv[])
{

    QQuickView view;
    QQmlEngine *engine = view.engine();
    engine->addImageProvider(QLatin1String("colors"), new ColorImageProvider);
    view.setSource(QUrl::fromLocalFile(QStringLiteral("imageprovider-example.qml")));
    view.show();
    return app.exec();
}

Теперь изображения могут быть успешно загружены в QML:

См. Пример поставщика изображений для полной реализации. Обратите внимание, что пример регистрирует поставщика через плагин, а не регистрирует его в функции приложения main() как показано выше.

Асинхронная загрузка изображений

Поставщики изображений, поддерживающие QImage или загрузку текстур, автоматически включают поддержку асинхронной загрузки изображений. Чтобы включить асинхронную загрузку для источника изображения, установите свойство asynchronous в true для соответствующего объекта Image или BorderImage. При включении этого параметра запрос изображения к поставщику выполняется в потоке низкого приоритета, что позволяет выполнять загрузку изображений в фоновом режиме и уменьшить влияние на пользовательский интерфейс.

Чтобы принудительно выполнить асинхронную загрузку изображения, даже для источников изображений, для которых свойство asynchronous не установлено в true, вы можете передать флаг QQmlImageProviderBase::ForceAsynchronousImageLoading в конструктор поставщика изображений. Это гарантирует, что все запросы на изображение для поставщика обрабатываются в отдельном потоке.

Асинхронная загрузка для поставщиков изображений, предоставляющих QPixmap, поддерживается только на платформах, имеющих функцию ThreadedPixmaps. На платформах, где пиксельные карты могут создаваться только в основном потоке (т. е. ThreadedPixmaps не поддерживается), если asynchronous установлен на true, значение игнорируется, и изображение загружается синхронно.

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

Кэширование изображений

Изображения, возвращаемые QQuickImageProvider, автоматически кэшируются, аналогично любому загружаемому движком QML изображению. Когда изображение с префиксом "image://" загружается из кэша, requestImage() и requestPixmap() не будут вызываться для соответствующего поставщика изображений. Если изображение должно всегда извлекаться от поставщика изображений и не должно кэшироваться вообще, установите свойство cache в false для соответствующего объекта Image или BorderImage.

См. также QQmlEngine::addImageProvider().

Документация по функциям членов

QQuickImageProvider::QQuickImageProvider(QQmlImageProviderBase::ImageType type, QQmlImageProviderBase::Flags flags = Flags())

Создает поставщик изображений, который будет предоставлять изображения заданного типа type и вести себя в соответствии с заданными flags.

[override virtual] QQuickImageProvider::~QQuickImageProvider()

Удаляет QQuickImageProvider

Примечание: Деструктор вашего производного класса должен быть потокобезопасным.

[override virtual] QQmlImageProviderBase::Flags QQuickImageProvider::flags() const

Реализует: QQmlImageProviderBase::flags() const.

Возвращает флаги, установленные для этого поставщика.

[override virtual] QQmlImageProviderBase::ImageType QQuickImageProvider::imageType() const

Реализует: QQmlImageProviderBase::imageType() const.

Возвращает тип изображения, поддерживаемый этим поставщиком.

[virtual] QImage QQuickImageProvider::requestImage(const QString &id, QSize *size, const QSize &requestedSize)

Реализуйте этот метод для возврата изображения с id. По умолчанию возвращает пустое изображение.

id — запрашиваемый источник изображения, из которого удалены схема "image:" и идентификатор поставщика. Например, если изображение source было "image://myprovider/icons/home", заданное id будет "icons/home".

requestedSize соответствует Image::sourceSize, запрашиваемому элементом Image. Если requestedSize — допустимый размер, возвращаемое изображение должно иметь этот размер.

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

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

[virtual] QPixmap QQuickImageProvider::requestPixmap(const QString &id, QSize *size, const QSize &requestedSize)

Реализуйте этот метод для возврата пиктограммы с id. По умолчанию возвращается пустая пиктограмма.

id — это запрашиваемый источник изображения, из которого удалены схема «image:» и идентификатор провайдера. Например, если изображение source было «image://myprovider/icons/home», заданное id будет «icons/home».

requestedSize соответствует Image::sourceSize, запрошенному элементом Image. Если requestedSize является корректным размером, возвращаемое изображение должно иметь этот размер.

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

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

[virtual] QQuickTextureFactory *QQuickImageProvider::requestTexture(const QString &id, QSize *size, const QSize &requestedSize)

Реализуйте этот метод для возврата текстуры с id. По умолчанию возвращается nullptr.

id — это запрашиваемый источник изображения, из которого удалены схема «image:» и идентификатор провайдера. Например, если изображение source было «image://myprovider/icons/home», заданное id будет «icons/home».

requestedSize соответствует Image::sourceSize, запрошенному элементом Image. Если requestedSize является корректным размером, возвращаемое изображение должно иметь этот размер.

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

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