Widgets

Qt Digital Advertising is designed as a Qt Quick plugin however a Qt Widgets solution is available by using the QQuickWidget class.

In this chapter we will guide you, step by step, how to embed Qt Quick advertisements into Qt Widgets applications.

Example

To make it even easier for you to get ideas how our plugin can be used in Qt Widgets applications, we have recreated our Qt Quick example from scratch as Qt Widgets application.

Qt Widgets example is analogous to the Embedded example. For more information, please see Examples.

Disclaimer

Since the solution presented in this chapter relies heavily on the QQuickWidget, please refer to the limitations that are imposed by using this class.

Walkthrough

In the following sections we will provide a detailed walkthrough of an example created for Qt Widgets applications.

First of all, to use the QQuickWidget class, quickwidgets module have to be enabled (e.g. qmake's QT += quickwidgets).

After enabling quickwidgets module, QQuickWidget object can be instantiated:

advWidget = new QQuickWidget();

To instantiate QML object, it's definition has to be provided as a separate QML file, for example:

import QtQuick 2.0
import QtDigitalAdvertising 2.0

BannerAd{
    adUnitId: "/6499/example/banner"
    bannerType: BannerAd.BANNER
}

As you can see, the provided QML code is very simple, as simple as JSON configuration file.

Having the QML file ready, a QML object can be instantiated by setting the source on the QQuickWidget object. Ensure that the URL provided is full and correct.

advWidget->setSource(QUrl::fromLocalFile(":/adv.qml"));

At this point the advertisement item should be fully functional. To learn how to interact with this item, please see following sections.

Optional Features

QML Item

The instantiated QML item is obtainable via QQuickWidget::rootObject().

Returned item pointer can be used as an object reference for various features like: manipulating properties, invoking methods, connecting slots/signals.

For more information, please refer to the following sections.

QML Properties

It is possible to manipulate the instantiated QML item properties via C++ as designed in the Qt Quick.

To make it possible QQuickItem header has to be included first:

#include <QQuickItem>

Then a property of the item can be changed, for example:

advWidget->rootObject()->setProperty("bannerType", 1);

This way the QML item property called displayMode will be set to Loop.

QML Methods

It is possible to invoke the instantiated QML item methods via C++ as designed in the Qt Quick.

To make it possible QMetaObject header has to be included first.

Then a QML method can be invoked, for example:

QMetaObject::invokeMethod(advWidget->rootObject(), sceneIndex == MainScene ? "stop" : "play");

This way the QML item will call play or pause method.

QML Signals

It is possible to connect to the instantiated QML item signals via C++ as designed in the Qt Quick.

To make it possible old connection syntax has to be used, for example:

connect(advWidget->rootObject(), SIGNAL(loaded()), this, SLOT(onLoaded()));

This way whenever the QML item will emit signal about the end of an ad, a onAdvEnded slot will be called.

Resize Mode

QML item size can be managed via Qt Widgets layouts etc., to make it possible set following resize mode:

advWidget->setResizeMode(QQuickWidget::SizeRootObjectToView);

This way the QML item size will be managed by the view (layout); otherwise the size will be based on the QML code.

Caveats

OpenGL

Since QQuickWidget relies heavily on the OpenGL, graphics API has to be sometimes explicitly set to the OpenGL.

QQuickWindow::setGraphicsApi(QSGRendererInterface::OpenGL);

Transparent Clear Color

Due to the QQuickWidget limitations, setting the ad item transparent clear color is quite tricky.

advWidget->setClearColor(Qt::transparent);
advWidget->setAttribute(Qt::WA_AlwaysStackOnTop, sceneIndex != FullScene && sceneIndex != InlineScene);
advWidget->setAttribute(Qt::WA_TranslucentBackground, sceneIndex != FullScene && sceneIndex != InlineScene);

This way for scenes other than fullscreen and inline, the ad item will have transparent clear color.

Transparent clear color requires to set always on top flag or set up the item in a separate window.

For more information, please see limitations of QQuickWidget.

Enum Values

Since Qt Digital Advertising is a QML plugin only, there are no relevant enumerations available for C++, but numeric values can be used instead, e.g.:

advWidget->rootObject()->setProperty("bannerType", 1);

Please refer to the QML Types Reference to get to know numeric values for the plugin enumerations (first enum value starts from zero).