There are a number of ways to integrate QML into QWidget-based UI applications, depending on the characteristics of your existing UI code.

Integrating with a QWidget-based UI

If you have an existing QWidget-based UI, QML widgets can be integrated into it using QDeclarativeView. QDeclarativeView is a subclass of QWidget so you can add it to your user interface like any other QWidget. Use QDeclarativeView::setSource() to load a QML file into the view, then add the view to your UI:

QDeclarativeView *qmlView = new QDeclarativeView;
qmlView->setSource(QUrl::fromLocalFile("myqml.qml"));

QWidget *widget = myExistingWidget();
QVBoxLayout *layout = new QVBoxLayout(widget);
layout->addWidget(qmlView);

The one drawback to this approach is that QDeclarativeView is slower to initialize and uses more memory than a QWidget, and creating large numbers of QDeclarativeView objects may lead to performance degradation. If this is the case, it may be better to rewrite your widgets in QML, and load the widgets from a main QML widget instead of using QDeclarativeView.

Keep in mind that QWidgets were designed for a different type of user interface than QML, so it is not always a good idea to port a QWidget-based application to QML. QWidgets are a better choice if your UI is comprised of a small number of complex and static elements, and QML is a better choice if your UI is comprised of a large number of simple and dynamic elements.

Integrating with a QGraphicsView-based UI

Adding QML widgets to a QGraphicsScene

If you have an existing UI based on the Graphics View Framework, you can integrate QML widgets directly into your QGraphicsScene. Use QDeclarativeComponent to create a QGraphicsObject from a QML file, and place the graphics object into your scene using QGraphicsScene::addItem(), or reparent it to an item already in the QGraphicsScene.

For example:

QGraphicsScene* scene = myExistingGraphicsScene();
QDeclarativeEngine *engine = new QDeclarativeEngine;
QDeclarativeComponent component(engine, QUrl::fromLocalFile("myqml.qml"));
QGraphicsObject *object =
    qobject_cast<QGraphicsObject *>(component.create());
scene->addItem(object);

The following QGraphicsView options are recommended for optimal performance of QML UIs:

• QGraphicsView::setOptimizationFlags(QGraphicsView::DontSavePainterState)
• QGraphicsView::setViewportUpdateMode(QGraphicsView::BoundingRectViewportUpdate)
• QGraphicsScene::setItemIndexMethod(QGraphicsScene::NoIndex)

Loading QGraphicsWidget objects in QML

An alternative approach is to expose your existing QGraphicsWidget objects to QML and construct your scene in QML instead. See the graphics layouts example which shows how to expose Qt's graphics layout classes to QML in order to use QGraphicsWidget with classes like QGraphicsLinearLayout and QGraphicsGridLayout.

To expose your existing QGraphicsWidget classes to QML, use qmlRegisterType(). See Extending QML Functionalities using C++ for further information on how to use C++ types in QML.