doc/src/qtquick1/integrating.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
   4 ** Contact: http://www.qt-project.org/
   5 **
   6 ** This file is part of the documentation of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:FDL$
   9 ** GNU Free Documentation License
  10 ** Alternatively, this file may be used under the terms of the GNU Free
  11 ** Documentation License version 1.3 as published by the Free Software
  12 ** Foundation and appearing in the file included in the packaging of
  13 ** this file.
  14 **
  15 ** Other Usage
  16 ** Alternatively, this file may be used in accordance with the terms
  17 ** and conditions contained in a signed written agreement between you
  18 ** and Nokia.
  19 **
  20 **
  21 **
  22 **
  23 **
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28 /*!
  29 \page qml-integration.html
  30 \inqmlmodule QtQuick 1
  31 \ingroup qml-features
  32 \previouspage {Using QML Bindings in C++ Applications}
  33 \nextpage {Dynamic Object Management in QML}{Dynamic Object Management}
  34 \contentspage QML Features
  35 \title Integrating QML Code with Existing Qt UI Code
  36
  37 There are a number of ways to integrate QML into QWidget-based UI applications,
  38 depending on the characteristics of your existing UI code.
  39
  40
  41 \section1 Integrating with a \l{QWidget}-based UI
  42
  43 If you have an existing QWidget-based UI, QML widgets can be integrated into
  44 it using QDeclarativeView. QDeclarativeView is a subclass of QWidget so you
  45 can add it to your user interface like any other QWidget. Use
  46 QDeclarativeView::setSource() to load a QML file into the view, then add the
  47 view to your UI:
  48
  49 \code
  50 QDeclarativeView *qmlView = new QDeclarativeView;
  51 qmlView->setSource(QUrl::fromLocalFile("myqml.qml"));
  52
  53 QWidget *widget = myExistingWidget();
  54 QVBoxLayout *layout = new QVBoxLayout(widget);
  55 layout->addWidget(qmlView);
  56 \endcode
  57
  58 The one drawback to this approach is that QDeclarativeView is slower to initialize
  59 and uses more memory than a QWidget, and creating large numbers of QDeclarativeView
  60 objects may lead to performance degradation. If this is the case, it may be
  61 better to rewrite your widgets in QML, and load the widgets from a main QML widget
  62 instead of using QDeclarativeView.
  63
  64 Keep in mind that QWidgets were designed for a different type of user interface
  65 than QML, so it is not always a good idea to port a QWidget-based application to
  66 QML. QWidgets are a better choice if your UI is comprised of a small number of
  67 complex and static elements, and QML is a better choice if your UI is comprised of a large number
  68 of simple and dynamic elements.
  69
  70
  71 \section1 Integrating with a QGraphicsView-based UI
  72
  73 \section2 Adding QML widgets to a QGraphicsScene
  74
  75 If you have an existing UI based on the \l{Graphics View Framework},
  76 you can integrate QML widgets directly into your QGraphicsScene. Use
  77 QDeclarativeComponent to create a QGraphicsObject from a QML file, and
  78 place the graphics object into your scene using \l{QGraphicsScene::addItem()}, or
  79 reparent it to an item already in the \l{QGraphicsScene}.
  80
  81 For example:
  82
  83 \code
  84 QGraphicsScene* scene = myExistingGraphicsScene();
  85 QDeclarativeEngine *engine = new QDeclarativeEngine;
  86 QDeclarativeComponent component(engine, QUrl::fromLocalFile("myqml.qml"));
  87 QGraphicsObject *object =
  88     qobject_cast<QGraphicsObject *>(component.create());
  89 scene->addItem(object);
  90 \endcode
  91
  92 The following QGraphicsView options are recommended for optimal performance
  93 of QML UIs:
  94
  95 \list
  96 \o QGraphicsView::setOptimizationFlags(QGraphicsView::DontSavePainterState)
  97 \o QGraphicsView::setViewportUpdateMode(QGraphicsView::BoundingRectViewportUpdate)
  98 \o QGraphicsScene::setItemIndexMethod(QGraphicsScene::NoIndex)
  99 \endlist
 100
 101 \section2 Loading QGraphicsWidget objects in QML
 102
 103 An alternative approach is to expose your existing QGraphicsWidget objects to
 104 QML and construct your scene in QML instead. See the \l {declarative-cppextensions-qgraphicslayouts.html}{graphics layouts example}
 105 which shows how to expose Qt's graphics layout classes to QML in order
 106 to use QGraphicsWidget with classes like QGraphicsLinearLayout and QGraphicsGridLayout.
 107
 108 To expose your existing QGraphicsWidget classes to QML, use \l {qmlRegisterType()}.
 109 See \l{Extending QML Functionalities using C++} for further information on
 110 how to use C++ types in QML.
 111
 112 */