doc/src/declarative/integrating.qdoc

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