Update QQuickWidget docs and changelog

Change-Id: I853295f31cf9367a8e11157c9ef0764174c614cf
Reviewed-by: Gunnar Sletta <gunnar.sletta@jollamobile.com>

2 files changed, 21 insertions, 5 deletions

diff --git a/dist/changes-5.3.0 b/dist/changes-5.3.0
index 5cda809d97..05550765d4 100644
--- a/dist/changes-5.3.0
+++ b/dist/changes-5.3.0
@@ -42,6 +42,12 @@ QtQml
 QtQuick
 ------
 
+- Introduced QQuickWidget. This is the equivalent of QQuickView in the
+  QWidget world. It allows easy and flexible embedding of QtQuick
+  scenes into widget-based application windows without the
+  restrictions imposed by QWidget::createWindowContainer().
+
+
 ****************************************************************************
 *                          Database Drivers                                *
 ****************************************************************************
diff --git a/src/quickwidgets/qquickwidget.cpp b/src/quickwidgets/qquickwidget.cpp
index da95e03e5f..ec4ce2f314 100644
--- a/src/quickwidgets/qquickwidget.cpp
+++ b/src/quickwidgets/qquickwidget.cpp
@@ -166,14 +166,14 @@ void QQuickWidgetPrivate::renderSceneGraph()
 
 /*!
     \class QQuickWidget
-    \since 5.0
-    \brief The QQuickWidget class provides a window for displaying a Qt Quick user interface.
+    \since 5.3
+    \brief The QQuickWidget class provides a widget for displaying a Qt Quick user interface.
 
     \inmodule QtQuick
 
-    This is a convenience subclass of QQuickWindow which
-    will automatically load and display a QML scene when given the URL of the main source file. Alternatively,
-    you can instantiate your own objects using QQmlComponent and place them in a manually setup QQuickWindow.
+    This is a convenience wrapper for QQuickWindow which will automatically load and display a QML
+    scene when given the URL of the main source file. Alternatively, you can instantiate your own
+    objects using QQmlComponent and place them in a manually setup QQuickWidget.
 
     Typical usage:
 
@@ -192,6 +192,16 @@ void QQuickWidgetPrivate::renderSceneGraph()
     size of the view.  Alternatively the resizeMode may be set to SizeRootObjectToView which
     will resize the view to the size of the root object.
 
+    \note QQuickWidget is an alternative to using QQuickView and QWidget::createWindowContainer().
+    The restrictions on stacking order do not apply, making QQuickWidget the more flexible
+    alternative behaving more like an ordinary widget. This comes at the expense of
+    performance. Unlike QQuickWindow and QQuickView, QQuickWidget involves rendering into OpenGL
+    framebuffer objects. This will naturally carry a minor performance hit.
+
+    \note Using QQuickWidget disables the threaded render loop on all platforms. This means that
+    some of the benefits of threaded rendering, for example Animator classes and vsync driven
+    animations, will not be available.
+
     \sa {qtqml-cppintegration-exposecppattributes.html}{Exposing Attributes of C++ Types to QML}
 */