1 files changed, 111 insertions, 0 deletions
diff --git a/doc/src/declarative/integrating.qdoc b/doc/src/declarative/integrating.qdoc
new file mode 100644
index 0000000000..c2f55f5267
--- /dev/null
+++ b/doc/src/declarative/integrating.qdoc
@@ -0,0 +1,111 @@
+/****************************************************************************
+**
+** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the Technology Preview License Agreement accompanying
+** this package.
+**
+** GNU Free Documentation License
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of this
+** file.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+\page qml-integration.html
+\ingroup qml-features
+\previouspage {Using QML Bindings in C++ Applications}
+\nextpage {Dynamic Object Management in QML}{Dynamic Object Management}
+\contentspage QML Features
+\title Integrating QML Code with Existing Qt UI Code
+
+There are a number of ways to integrate QML into QWidget-based UI applications,
+depending on the characteristics of your existing UI code.
+
+
+\section1 Integrating with a \l{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:
+
+\code
+QDeclarativeView *qmlView = new QDeclarativeView;
+qmlView->setSource(QUrl::fromLocalFile("myqml.qml"));
+
+QWidget *widget = myExistingWidget();
+QVBoxLayout *layout = new QVBoxLayout(widget);
+layout->addWidget(qmlView);
+\endcode
+
+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.
+
+
+\section1 Integrating with a QGraphicsView-based UI
+
+\section2 Adding QML widgets to a QGraphicsScene
+
+If you have an existing UI based on the \l{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 \l{QGraphicsScene::addItem()}, or
+reparent it to an item already in the \l{QGraphicsScene}.
+
+For example:
+
+\code
+QGraphicsScene* scene = myExistingGraphicsScene();
+QDeclarativeEngine *engine = new QDeclarativeEngine;
+QDeclarativeComponent component(engine, QUrl::fromLocalFile("myqml.qml"));
+QGraphicsObject *object =
+    qobject_cast<QGraphicsObject *>(component.create());
+scene->addItem(object);
+\endcode
+
+The following QGraphicsView options are recommended for optimal performance
+of QML UIs:
+
+\list
+\o QGraphicsView::setOptimizationFlags(QGraphicsView::DontSavePainterState)
+\o QGraphicsView::setViewportUpdateMode(QGraphicsView::BoundingRectViewportUpdate)
+\o QGraphicsScene::setItemIndexMethod(QGraphicsScene::NoIndex)
+\endlist
+
+\section2 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 \l {declarative-cppextensions-qgraphicslayouts.html}{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 \l {qmlRegisterType()}.
+See \l{Extending QML Functionalities using C++} for further information on
+how to use C++ types in QML.
+
+*/