From ba3f33401c97c5517abe19f4ea6f6307e4374c6c Mon Sep 17 00:00:00 2001 From: Michael Brasser Date: Fri, 16 Apr 2010 14:54:19 +1000 Subject: More class documentation fixes for declarative. --- src/declarative/qml/qdeclarativecontext.cpp | 7 ++- src/declarative/qml/qdeclarativeerror.cpp | 51 +++++++++++++++------- .../qml/qdeclarativeextensionplugin.cpp | 11 ++++- src/declarative/qml/qdeclarativeimageprovider.cpp | 22 +++++++--- src/declarative/qml/qdeclarativeimageprovider.h | 2 +- src/declarative/qml/qdeclarativelist.cpp | 15 ++++--- src/declarative/qml/qdeclarativeproperty.cpp | 1 + 7 files changed, 77 insertions(+), 32 deletions(-) diff --git a/src/declarative/qml/qdeclarativecontext.cpp b/src/declarative/qml/qdeclarativecontext.cpp index 6657fea..5288923 100644 --- a/src/declarative/qml/qdeclarativecontext.cpp +++ b/src/declarative/qml/qdeclarativecontext.cpp @@ -114,7 +114,7 @@ QDeclarativeContextPrivate::QDeclarativeContextPrivate() \endcode All properties added explicitly by QDeclarativeContext::setContextProperty() take - precedence over context object's properties. + precedence over the context object's properties. Contexts form a hierarchy. The root of this heirarchy is the QDeclarativeEngine's \l {QDeclarativeEngine::rootContext()}{root context}. A component instance can @@ -140,6 +140,11 @@ QDeclarativeContextPrivate::QDeclarativeContextPrivate() While QML objects instantiated in a context are not strictly owned by that context, their bindings are. If a context is destroyed, the property bindings of outstanding QML objects will stop evaluating. + + \note Setting the context object or adding new context properties after an object + has been created in that context is an expensive operation (essentially forcing all bindings + to reevaluate). Thus whenever possible you should complete "setup" of the context + before using it to create any objects. */ /*! \internal */ diff --git a/src/declarative/qml/qdeclarativeerror.cpp b/src/declarative/qml/qdeclarativeerror.cpp index 7e8aac0..17e91e3 100644 --- a/src/declarative/qml/qdeclarativeerror.cpp +++ b/src/declarative/qml/qdeclarativeerror.cpp @@ -49,8 +49,27 @@ QT_BEGIN_NAMESPACE /*! \class QDeclarativeError - \since 4.7 - \brief The QDeclarativeError class encapsulates a QML error + \since 4.7 + \brief The QDeclarativeError class encapsulates a QML error. + + QDeclarativeError includes a textual description of the error, as well + as location information (the file, line, and column). The toString() + method creates a single-line, human-readable string containing all of + this information, for example: + \code + file:///home/user/test.qml:7:8: Invalid property assignment: double expected + \endcode + + You can use qDebug() or qWarning() to output errors to the console. This method + will attempt to open the file indicated by the error + and include additional contextual information. + \code + file:///home/user/test.qml:7:8: Invalid property assignment: double expected + y: "hello" + ^ + \endcode + + \sa QDeclarativeView::errors(), QDeclarativeComponent::errors() */ class QDeclarativeErrorPrivate { @@ -69,7 +88,7 @@ QDeclarativeErrorPrivate::QDeclarativeErrorPrivate() } /*! - Create an empty error object. + Creates an empty error object. */ QDeclarativeError::QDeclarativeError() : d(0) @@ -77,7 +96,7 @@ QDeclarativeError::QDeclarativeError() } /*! - Create a copy of \a other. + Creates a copy of \a other. */ QDeclarativeError::QDeclarativeError(const QDeclarativeError &other) : d(0) @@ -86,7 +105,7 @@ QDeclarativeError::QDeclarativeError(const QDeclarativeError &other) } /*! - Assign \a other to this error object. + Assigns \a other to this error object. */ QDeclarativeError &QDeclarativeError::operator=(const QDeclarativeError &other) { @@ -112,7 +131,7 @@ QDeclarativeError::~QDeclarativeError() } /*! - Return true if this error is valid, otherwise false. + Returns true if this error is valid, otherwise false. */ bool QDeclarativeError::isValid() const { @@ -120,7 +139,7 @@ bool QDeclarativeError::isValid() const } /*! - Return the url for the file that caused this error. + Returns the url for the file that caused this error. */ QUrl QDeclarativeError::url() const { @@ -129,7 +148,7 @@ QUrl QDeclarativeError::url() const } /*! - Set the \a url for the file that caused this error. + Sets the \a url for the file that caused this error. */ void QDeclarativeError::setUrl(const QUrl &url) { @@ -138,7 +157,7 @@ void QDeclarativeError::setUrl(const QUrl &url) } /*! - Return the error description. + Returns the error description. */ QString QDeclarativeError::description() const { @@ -147,7 +166,7 @@ QString QDeclarativeError::description() const } /*! - Set the error \a description. + Sets the error \a description. */ void QDeclarativeError::setDescription(const QString &description) { @@ -156,7 +175,7 @@ void QDeclarativeError::setDescription(const QString &description) } /*! - Return the error line number. + Returns the error line number. */ int QDeclarativeError::line() const { @@ -165,7 +184,7 @@ int QDeclarativeError::line() const } /*! - Set the error \a line number. + Sets the error \a line number. */ void QDeclarativeError::setLine(int line) { @@ -174,7 +193,7 @@ void QDeclarativeError::setLine(int line) } /*! - Return the error column number. + Returns the error column number. */ int QDeclarativeError::column() const { @@ -183,7 +202,7 @@ int QDeclarativeError::column() const } /*! - Set the error \a column number. + Sets the error \a column number. */ void QDeclarativeError::setColumn(int column) { @@ -192,7 +211,7 @@ void QDeclarativeError::setColumn(int column) } /*! - Return the error as a human readable string. + Returns the error as a human readable string. */ QString QDeclarativeError::toString() const { @@ -210,7 +229,7 @@ QString QDeclarativeError::toString() const \relates QDeclarativeError \fn QDebug operator<<(QDebug debug, const QDeclarativeError &error) - Output a human readable version of \a error to \a debug. + Outputs a human readable version of \a error to \a debug. */ QDebug operator<<(QDebug debug, const QDeclarativeError &error) diff --git a/src/declarative/qml/qdeclarativeextensionplugin.cpp b/src/declarative/qml/qdeclarativeextensionplugin.cpp index 762c642d..863bfc4 100644 --- a/src/declarative/qml/qdeclarativeextensionplugin.cpp +++ b/src/declarative/qml/qdeclarativeextensionplugin.cpp @@ -59,6 +59,11 @@ QT_BEGIN_NAMESPACE function, and exporting the class using the Q_EXPORT_PLUGIN2() macro. + QML extension plugins can be used to provide either application-specific or + library-like plugins. Library plugins should limit themselves to registering types, + as any manipulation of the engine's root context may cause conflicts + or other issues in the library user's code. + See \l {Extending QML in C++} for details how to write a QML extension plugin. See \l {How to Create Qt Plugins} for general Qt plugin documentation. @@ -85,7 +90,7 @@ QDeclarativeExtensionPlugin::QDeclarativeExtensionPlugin(QObject *parent) } /*! - Destructor. + Destroys the plugin. */ QDeclarativeExtensionPlugin::~QDeclarativeExtensionPlugin() { @@ -94,7 +99,9 @@ QDeclarativeExtensionPlugin::~QDeclarativeExtensionPlugin() /*! \fn void QDeclarativeExtensionPlugin::initializeEngine(QDeclarativeEngine *engine, const char *uri) - Initializes the extension from the \a uri using the \a engine. + Initializes the extension from the \a uri using the \a engine. Here an application + plugin might, for example, expose some data or objects to QML, + as context properties on the engine's root context. */ void QDeclarativeExtensionPlugin::initializeEngine(QDeclarativeEngine *engine, const char *uri) diff --git a/src/declarative/qml/qdeclarativeimageprovider.cpp b/src/declarative/qml/qdeclarativeimageprovider.cpp index b992b9f..4be3472 100644 --- a/src/declarative/qml/qdeclarativeimageprovider.cpp +++ b/src/declarative/qml/qdeclarativeimageprovider.cpp @@ -45,31 +45,39 @@ QT_BEGIN_NAMESPACE /*! \class QDeclarativeImageProvider - \brief The QDeclarativeImageProvider class provides an interface for threaded image requests. + \since 4.7 + \brief The QDeclarativeImageProvider class provides an interface for threaded image requests in QML. - Note: the request() method may be called by multiple threads, so ensure the + QDeclarativeImageProvider can be used by a QDeclarativeEngine to provide images to QML asynchronously. + The image request will be run in a low priority thread, allowing potentially costly image + loading to be done in the background, without affecting the performance of the UI. + + See the QDeclarativeEngine::addImageProvider() documentation for an + example of how a custom QDeclarativeImageProvider can be constructed and used. + + \note the request() method may be called by multiple threads, so ensure the implementation of this method is reentrant. \sa QDeclarativeEngine::addImageProvider() */ /*! - The destructor is virtual. + Destroys the image provider. */ QDeclarativeImageProvider::~QDeclarativeImageProvider() { } /*! - \fn QImage QDeclarativeImageProvider::request(const QString &id, QSize *size, const QSize& requested_size) + \fn QImage QDeclarativeImageProvider::request(const QString &id, QSize *size, const QSize& requestedSize) Implement this method to return the image with \a id. - If \a requested_size is a valid size, resize the image to that size before returning. + If \a requestedSize is a valid size, the image returned should be of that size. - In any case, \a size must be set to the (original) size of the image. + In all cases, \a size must be set to the original size of the image. - Note: this method may be called by multiple threads, so ensure the + \note this method may be called by multiple threads, so ensure the implementation of this method is reentrant. */ diff --git a/src/declarative/qml/qdeclarativeimageprovider.h b/src/declarative/qml/qdeclarativeimageprovider.h index 50b73fe..cc9c9af 100644 --- a/src/declarative/qml/qdeclarativeimageprovider.h +++ b/src/declarative/qml/qdeclarativeimageprovider.h @@ -54,7 +54,7 @@ class Q_DECLARATIVE_EXPORT QDeclarativeImageProvider { public: virtual ~QDeclarativeImageProvider(); - virtual QImage request(const QString &id, QSize *size, const QSize& requested_size) = 0; + virtual QImage request(const QString &id, QSize *size, const QSize& requestedSize) = 0; }; QT_END_NAMESPACE diff --git a/src/declarative/qml/qdeclarativelist.cpp b/src/declarative/qml/qdeclarativelist.cpp index 45b8cd7..31ef4c2 100644 --- a/src/declarative/qml/qdeclarativelist.cpp +++ b/src/declarative/qml/qdeclarativelist.cpp @@ -87,9 +87,10 @@ void QDeclarativeListReferencePrivate::release() /*! \class QDeclarativeListReference +\since 4.7 \brief The QDeclarativeListReference class allows the manipulation of QDeclarativeListProperty properties. -QDeclarativeListReference allows programs to read from, and assign values to a QML list property in a +QDeclarativeListReference allows C++ programs to read from, and assign values to a QML list property in a simple and type safe way. A QDeclarativeListReference can be created by passing an object and property name or through a QDeclarativeProperty instance. These two are equivalant: @@ -304,6 +305,7 @@ int QDeclarativeListReference::count() const /*! \class QDeclarativeListProperty +\since 4.7 \brief The QDeclarativeListProperty class allows applications to explose list-like properties to QML. @@ -313,10 +315,10 @@ The use of a list property from QML looks like this: \code FruitBasket { fruit: [ - Apple {}, - Orange{}, - Banana {} - ] + Apple {}, + Orange{}, + Banana{} + ] } \endcode @@ -336,6 +338,9 @@ Q_PROPERTY(QDeclarativeListProperty fruit READ fruit); QML list properties are typesafe - in this case \c {Fruit} is a QObject type that \c {Apple}, \c {Orange} and \c {Banana} all derive from. + +\note QDeclarativeListProperty can only be used for lists of QObject-derived object pointers. + */ /*! diff --git a/src/declarative/qml/qdeclarativeproperty.cpp b/src/declarative/qml/qdeclarativeproperty.cpp index afd0d84..3881d0a 100644 --- a/src/declarative/qml/qdeclarativeproperty.cpp +++ b/src/declarative/qml/qdeclarativeproperty.cpp @@ -64,6 +64,7 @@ QT_BEGIN_NAMESPACE /*! \class QDeclarativeProperty +\since 4.7 \brief The QDeclarativeProperty class abstracts accessing properties on objects created from QML. As QML uses Qt's meta-type system all of the existing QMetaObject classes can be used to introspect -- cgit v0.12