Cursory docs for QQuickCanvas and QQuickView

Change-Id: I6955164715b07fc11a00466b5a5a1818d97fb9b5
Reviewed-by: Martin Jones <martin.jones@nokia.com>

2 files changed, 163 insertions, 3 deletions

diff --git a/src/declarative/items/qquickcanvas.cpp b/src/declarative/items/qquickcanvas.cpp
index 861b11ff36..163dc8838c 100644
--- a/src/declarative/items/qquickcanvas.cpp
+++ b/src/declarative/items/qquickcanvas.cpp
@@ -789,6 +789,9 @@ void QQuickCanvasPrivate::updateInputMethodData()
     qApp->inputPanel()->setInputItem(inputItem);
 }
 
+/*!
+  Queries the Input Method.
+*/
 QVariant QQuickCanvas::inputMethodQuery(Qt::InputMethodQuery query) const
 {
     Q_D(const QQuickCanvas);
@@ -824,6 +827,19 @@ void QQuickCanvasPrivate::cleanup(QSGNode *n)
 }
 
 
+/*!
+    \class QQuickCanvas
+    \since QtQuick 2.0
+    \brief The QQuickCanvas class provides the canvas for displaying a graphical QML scene
+
+    QQuickCanvas provides the graphical scene management needed to interact with and display
+    a scene of QQuickItems.
+
+    A QQuickCanvas always has a single invisible root item. To add items to this canvas,
+    reparent the items to the root item or to an existing item in the scene.
+
+    For easily displaying a scene from a QML file, see \l{QQuickView}.
+*/
 QQuickCanvas::QQuickCanvas(QWindow *parent)
     : QWindow(*(new QQuickCanvasPrivate), parent)
 {
@@ -859,6 +875,12 @@ QQuickCanvas::~QQuickCanvas()
     d->cleanupNodes();
 }
 
+/*!
+  Returns the invisible root item of the scene.
+
+  A QQuickCanvas always has a single invisible root item. To add items to this canvas,
+  reparent the items to the root item or to an existing item in the scene.
+*/
 QQuickItem *QQuickCanvas::rootItem() const
 {
     Q_D(const QQuickCanvas);
@@ -866,6 +888,9 @@ QQuickItem *QQuickCanvas::rootItem() const
     return d->rootItem;
 }
 
+/*!
+  Returns the item which currently has active focus.
+*/
 QQuickItem *QQuickCanvas::activeFocusItem() const
 {
     Q_D(const QQuickCanvas);
@@ -873,6 +898,9 @@ QQuickItem *QQuickCanvas::activeFocusItem() const
     return d->activeFocusItem;
 }
 
+/*!
+  Returns the item which currently has the mouse grab.
+*/
 QQuickItem *QQuickCanvas::mouseGrabberItem() const
 {
     Q_D(const QQuickCanvas);
@@ -1518,6 +1546,9 @@ bool QQuickCanvasPrivate::sendFilteredMouseEvent(QQuickItem *target, QQuickItem
     return false;
 }
 
+/*!
+    Propagates an event to a QQuickItem on the canvas
+*/
 bool QQuickCanvas::sendEvent(QQuickItem *item, QEvent *e)
 {
     Q_D(QQuickCanvas);
@@ -1944,7 +1975,8 @@ QImage QQuickCanvas::grabFrameBuffer()
 
 /*!
     Returns an incubation controller that splices incubation between frames
-    for this canvas.  QQuickView automatically installs this controller for you.
+    for this canvas. QQuickView automatically installs this controller for you,
+    otherwise you will need to install it yourself using \l{QDeclarativeEngine::setIncubationController}
 
     The controller is owned by the canvas and will be destroyed when the canvas
     is deleted.
diff --git a/src/declarative/items/qquickview.cpp b/src/declarative/items/qquickview.cpp
index cd3ae4f1c0..80d3a896d2 100644
--- a/src/declarative/items/qquickview.cpp
+++ b/src/declarative/items/qquickview.cpp
@@ -54,8 +54,6 @@
 #include <QtCore/qbasictimer.h>
 
 
-// XXX todo - This whole class should probably be merged with QDeclarativeView for
-// maximum seamlessness
 QT_BEGIN_NAMESPACE
 
 DEFINE_BOOL_CONFIG_OPTION(frameRateDebug, QML_SHOW_FRAMERATE)
@@ -117,6 +115,48 @@ void QQuickViewPrivate::itemGeometryChanged(QQuickItem *resizeItem, const QRectF
     QQuickItemChangeListener::itemGeometryChanged(resizeItem, newGeometry, oldGeometry);
 }
 
+/*!
+    \class QQuickView
+    \since QtQuick 2.0
+    \brief The QQuickView class provides a window for displaying a Qt Quick user interface.
+
+    This is a convenience subclass of QQuickCanvas 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 QDeclarativeComponent and place them in a manually setup QQuickCanvas.
+
+    Typical usage:
+
+    \code
+    QQuickView *view = new QQuickView;
+    view->setSource(QUrl::fromLocalFile("myqmlfile.qml"));
+    view->show();
+    \endcode
+
+    To receive errors related to loading and executing QML with QQuickView,
+    you can connect to the statusChanged() signal and monitor for QQuickView::Error.
+    The errors are available via QQuickView::errors().
+
+    \sa {Using QML Bindings in C++ Applications}
+*/
+
+
+/*! \fn void QQuickView::sceneResized(QSize size)
+  This signal is emitted when the view is resized to \a size.
+*/
+
+/*! \fn void QQuickView::statusChanged(QQuickView::Status status)
+    This signal is emitted when the component's current \a status changes.
+*/
+
+/*! \fn void QQuickView::initialSizeChanged(QSize size)
+  \internal
+*/
+
+/*!
+  \fn QQuickView::QQuickView(QWindow *parent)
+
+  Constructs a QQuickView with the given \a parent.
+*/
 QQuickView::QQuickView(QWindow *parent, Qt::WindowFlags f)
 : QQuickCanvas(*(new QQuickViewPrivate), parent)
 {
@@ -124,6 +164,11 @@ QQuickView::QQuickView(QWindow *parent, Qt::WindowFlags f)
     d_func()->init();
 }
 
+/*!
+  \fn QQuickView::QQuickView(const QUrl &source, QWidget *parent)
+
+  Constructs a QQuickView with the given QML \a source and \a parent.
+*/
 QQuickView::QQuickView(const QUrl &source, QWindow *parent, Qt::WindowFlags f)
 : QQuickCanvas(*(new QQuickViewPrivate), parent)
 {
@@ -136,6 +181,24 @@ QQuickView::~QQuickView()
 {
 }
 
+/*! \property QQuickView::source
+  \brief The URL of the source of the QML component.
+
+  Changing this property causes the QML component to be reloaded.
+
+    Ensure that the URL provided is full and correct, in particular, use
+    \l QUrl::fromLocalFile() when loading a file from the local filesystem.
+ */
+
+/*!
+    Sets the source to the \a url, loads the QML component and instantiates it.
+
+    Ensure that the URL provided is full and correct, in particular, use
+    \l QUrl::fromLocalFile() when loading a file from the local filesystem.
+
+    Calling this methods multiple times with the same url will result
+    in the QML being reloaded.
+ */
 void QQuickView::setSource(const QUrl& url)
 {
     Q_D(QQuickView);
@@ -143,24 +206,64 @@ void QQuickView::setSource(const QUrl& url)
     d->execute();
 }
 
+/*!
+  Returns the source URL, if set.
+
+  \sa setSource()
+ */
 QUrl QQuickView::source() const
 {
     Q_D(const QQuickView);
     return d->source;
 }
 
+/*!
+  Returns a pointer to the QDeclarativeEngine used for instantiating
+  QML Components.
+ */
 QDeclarativeEngine* QQuickView::engine() const
 {
     Q_D(const QQuickView);
     return const_cast<QDeclarativeEngine *>(&d->engine);
 }
 
+/*!
+  This function returns the root of the context hierarchy.  Each QML
+  component is instantiated in a QDeclarativeContext.  QDeclarativeContext's are
+  essential for passing data to QML components.  In QML, contexts are
+  arranged hierarchically and this hierarchy is managed by the
+  QDeclarativeEngine.
+ */
 QDeclarativeContext* QQuickView::rootContext() const
 {
     Q_D(const QQuickView);
     return d->engine.rootContext();
 }
 
+/*!
+    \enum QQuickView::Status
+    Specifies the loading status of the QQuickView.
+
+    \value Null This QQuickView has no source set.
+    \value Ready This QQuickView has loaded and created the QML component.
+    \value Loading This QQuickView is loading network data.
+    \value Error One or more errors has occurred. Call errors() to retrieve a list
+           of errors.
+*/
+
+/*! \enum QQuickView::ResizeMode
+
+  This enum specifies how to resize the view.
+
+  \value SizeViewToRootObject The view resizes with the root item in the QML.
+  \value SizeRootObjectToView The view will automatically resize the root item to the size of the view.
+*/
+
+/*!
+    \property QQuickView::status
+    The component's current \l{QQuickView::Status} {status}.
+*/
+
 QQuickView::Status QQuickView::status() const
 {
     Q_D(const QQuickView);
@@ -170,6 +273,10 @@ QQuickView::Status QQuickView::status() const
     return QQuickView::Status(d->component->status());
 }
 
+/*!
+    Return the list of errors that occurred during the last compile or create
+    operation.  When the status is not Error, an empty list is returned.
+*/
 QList<QDeclarativeError> QQuickView::errors() const
 {
     Q_D(const QQuickView);
@@ -178,6 +285,21 @@ QList<QDeclarativeError> QQuickView::errors() const
     return QList<QDeclarativeError>();
 }
 
+/*!
+    \property QQuickView::resizeMode
+    \brief whether the view should resize the canvas contents
+
+    If this property is set to SizeViewToRootObject (the default), the view
+    resizes with the root item in the QML.
+
+    If this property is set to SizeRootObjectToView, the view will
+    automatically resize the root item.
+
+    Regardless of this property, the sizeHint of the view
+    is the initial size of the root item. Note though that
+    since QML may load dynamically, that size may change.
+*/
+
 void QQuickView::setResizeMode(ResizeMode mode)
 {
     Q_D(QQuickView);
@@ -350,12 +472,18 @@ QSize QQuickView::sizeHint() const
     }
 }
 
+/*!
+  Returns the initial size of the root object
+*/
 QSize QQuickView::initialSize() const
 {
     Q_D(const QQuickView);
     return d->initialSize;
 }
 
+/*!
+  Returns the view's root \l {QQuickItem} {item}.
+ */
 QQuickItem *QQuickView::rootObject() const
 {
     Q_D(const QQuickView);