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.


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.


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


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 1.1

EmbeddedConfig {
    qdaApiKey: "paste-your-api-key-here"
    venueId: "Qt_Demo_Evaluation_Venue1"

EmbeddedAd {
    mediaWidth: 1920
    mediaHeight: 1080
    playMode: QtDigitalAdvertising.OnRequest
    displayMode: QtDigitalAdvertising.Singleshot

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.


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

Note: Setting a source URL will result in the QML component being instantiated, even if the URL is unchanged from the current value.

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("displayMode", 1); // QtDigitalAdvertising.Loop

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(advertisementEnded()), this, SLOT(onAdvEnded())); // clazy:exclude=old-style-connect

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:


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



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


Transparent Clear Color

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

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("displayMode", 1); // QtDigitalAdvertising.Loop

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

© 2023 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.