From 59854d10e8f1154b30655b6d244aef103ee11c46 Mon Sep 17 00:00:00 2001 From: Alan Alpert Date: Thu, 3 Nov 2011 10:09:38 +1000 Subject: [PATCH] Cursory docs for QQuickCanvas and QQuickView Change-Id: I6955164715b07fc11a00466b5a5a1818d97fb9b5 Reviewed-by: Martin Jones --- src/declarative/items/qquickcanvas.cpp | 34 ++++++++- src/declarative/items/qquickview.cpp | 132 +++++++++++++++++++++++++++++++- 2 files changed, 163 insertions(+), 3 deletions(-) diff --git a/src/declarative/items/qquickcanvas.cpp b/src/declarative/items/qquickcanvas.cpp index 861b11f..163dc88 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 cd3ae4f..80d3a89 100644 --- a/src/declarative/items/qquickview.cpp +++ b/src/declarative/items/qquickview.cpp @@ -54,8 +54,6 @@ #include -// 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(&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 QQuickView::errors() const { Q_D(const QQuickView); @@ -178,6 +285,21 @@ QList QQuickView::errors() const return QList(); } +/*! + \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); -- 1.7.2.5