From 22cd698e39970ded3fa4fd873195314015ce4b8c Mon Sep 17 00:00:00 2001 From: Alan Alpert Date: Fri, 8 Mar 2013 10:51:53 -0800 Subject: Document Q_REVISION macro better Previously it was only mentioned in properties.qdoc Task-number: QTBUG-18802 Change-Id: Iab23128c1567974154cdcce7412b2e1468bb846a Reviewed-by: Thiago Macieira --- .../snippets/code/src_corelib_kernel_qobject.cpp | 1 + .../doc/snippets/qmetaobject-revision/main.cpp | 72 ++++++++++++++++++++++ .../qmetaobject-revision/qmetaobject-revision.pro | 4 ++ .../doc/snippets/qmetaobject-revision/window.cpp | 66 ++++++++++++++++++++ .../doc/snippets/qmetaobject-revision/window.h | 63 +++++++++++++++++++ src/corelib/doc/src/objectmodel/properties.qdoc | 3 +- src/corelib/kernel/qmetaobject.cpp | 9 +-- src/corelib/kernel/qobject.cpp | 31 ++++++++++ 8 files changed, 244 insertions(+), 5 deletions(-) create mode 100644 src/corelib/doc/snippets/qmetaobject-revision/main.cpp create mode 100644 src/corelib/doc/snippets/qmetaobject-revision/qmetaobject-revision.pro create mode 100644 src/corelib/doc/snippets/qmetaobject-revision/window.cpp create mode 100644 src/corelib/doc/snippets/qmetaobject-revision/window.h (limited to 'src/corelib') diff --git a/src/corelib/doc/snippets/code/src_corelib_kernel_qobject.cpp b/src/corelib/doc/snippets/code/src_corelib_kernel_qobject.cpp index bafd3f8eb8..68df53e0da 100644 --- a/src/corelib/doc/snippets/code/src_corelib_kernel_qobject.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_kernel_qobject.cpp @@ -374,6 +374,7 @@ Q_PROPERTY(type name [WRITE setFunction] [RESET resetFunction] [NOTIFY notifySignal] + [REVISION int] [DESIGNABLE bool] [SCRIPTABLE bool] [STORED bool] diff --git a/src/corelib/doc/snippets/qmetaobject-revision/main.cpp b/src/corelib/doc/snippets/qmetaobject-revision/main.cpp new file mode 100644 index 0000000000..99a860b778 --- /dev/null +++ b/src/corelib/doc/snippets/qmetaobject-revision/main.cpp @@ -0,0 +1,72 @@ +/**************************************************************************** +** +** Copyright (C) 2013 Research In Motion. +** Contact: http://www.qt-project.org/legal +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Digia Plc and its Subsidiary(-ies) nor the names +** of its contributors may be used to endorse or promote products derived +** from this software without specific prior written permission. +** +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include +#include +#include +#include +#include +#include "window.h" + +void exposeMethod(const QMetaMethod &) +{ +} + +void exposeProperty(const QMetaProperty &) +{ +} + +int main(int argc, char *argv[]) +{ + QApplication app(argc, argv); +//! [Window class using revision] + Window window; + int expectedRevision = 0; + const QMetaObject *windowMetaObject = window.metaObject(); + for (int i=0; i < windowMetaObject->methodCount(); i++) + if (windowMetaObject->method(i).revision() <= expectedRevision) + exposeMethod(windowMetaObject->method(i)); + for (int i=0; i < windowMetaObject->propertyCount(); i++) + if (windowMetaObject->property(i).revision() <= expectedRevision) + exposeProperty(windowMetaObject->property(i)); +//! [Window class using revision] + window.show(); + return app.exec(); +} diff --git a/src/corelib/doc/snippets/qmetaobject-revision/qmetaobject-revision.pro b/src/corelib/doc/snippets/qmetaobject-revision/qmetaobject-revision.pro new file mode 100644 index 0000000000..ec9d7db658 --- /dev/null +++ b/src/corelib/doc/snippets/qmetaobject-revision/qmetaobject-revision.pro @@ -0,0 +1,4 @@ +QT += widgets +HEADERS = window.h +SOURCES = main.cpp \ + window.cpp diff --git a/src/corelib/doc/snippets/qmetaobject-revision/window.cpp b/src/corelib/doc/snippets/qmetaobject-revision/window.cpp new file mode 100644 index 0000000000..0315f831be --- /dev/null +++ b/src/corelib/doc/snippets/qmetaobject-revision/window.cpp @@ -0,0 +1,66 @@ +/**************************************************************************** +** +** Copyright (C) 2013 Research In Motion. +** Contact: http://www.qt-project.org/legal +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Digia Plc and its Subsidiary(-ies) nor the names +** of its contributors may be used to endorse or promote products derived +** from this software without specific prior written permission. +** +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include "window.h" + +Window::Window() +{ +} + +int Window::normalProperty() +{ + return 0; +} + +int Window::newProperty() +{ + return 1; +} + +void Window::normalMethod() +{ + show(); +} + +void Window::newMethod() +{ + // Can be hidden from users expecting the initial API + show(); +} diff --git a/src/corelib/doc/snippets/qmetaobject-revision/window.h b/src/corelib/doc/snippets/qmetaobject-revision/window.h new file mode 100644 index 0000000000..6e56f3dfef --- /dev/null +++ b/src/corelib/doc/snippets/qmetaobject-revision/window.h @@ -0,0 +1,63 @@ +/**************************************************************************** +** +** Copyright (C) 2013 Research In Motion. +** Contact: http://www.qt-project.org/legal +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Digia Plc and its Subsidiary(-ies) nor the names +** of its contributors may be used to endorse or promote products derived +** from this software without specific prior written permission. +** +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#ifndef WINDOW_H +#define WINDOW_H + +#include + +//! [Window class with revision] +class Window : public QWidget +{ + Q_OBJECT + Q_PROPERTY(int normalProperty READ normalProperty) + Q_PROPERTY(int newProperty READ newProperty REVISION 1) + +public: + Window(); + int normalProperty(); + int newProperty(); +public slots: + void normalMethod(); + Q_REVISION(1) void newMethod(); +}; +//! [Window class with revision] + +#endif diff --git a/src/corelib/doc/src/objectmodel/properties.qdoc b/src/corelib/doc/src/objectmodel/properties.qdoc index 721b98c0f7..65e23d9dc7 100644 --- a/src/corelib/doc/src/objectmodel/properties.qdoc +++ b/src/corelib/doc/src/objectmodel/properties.qdoc @@ -101,7 +101,8 @@ \li A \c REVISION number is optional. If included, it defines the property and its notifier signal to be used in a particular - revision of the API that is exposed to QML. + revision of the API (usually for exposure to QML). If not included, it + defaults to 0. \li The \c DESIGNABLE attribute indicates whether the property should be visible in the property editor of GUI design tool (e.g., diff --git a/src/corelib/kernel/qmetaobject.cpp b/src/corelib/kernel/qmetaobject.cpp index 4399349352..b581be821b 100644 --- a/src/corelib/kernel/qmetaobject.cpp +++ b/src/corelib/kernel/qmetaobject.cpp @@ -1904,9 +1904,9 @@ int QMetaMethod::methodIndex() const return QMetaMethodPrivate::get(this)->ownMethodIndex() + mobj->methodOffset(); } +// This method has been around for a while, but the documentation was marked \internal until 5.1 /*! - \internal - + \since 5.1 Returns the method revision if one was specified by Q_REVISION, otherwise returns 0. */ @@ -2550,7 +2550,7 @@ static QByteArray qualifiedName(const QMetaEnum &e) A property has a name() and a type(), as well as various attributes that specify its behavior: isReadable(), isWritable(), - isDesignable(), isScriptable(), and isStored(). + isDesignable(), isScriptable(), revision(), and isStored(). If the property is an enumeration, isEnumType() returns true; if the property is an enumeration that is also a flag (i.e. its values @@ -2994,8 +2994,9 @@ int QMetaProperty::notifySignalIndex() const } } +// This method has been around for a while, but the documentation was marked \internal until 5.1 /*! - \internal + \since 5.1 Returns the property revision if one was specified by REVISION, otherwise returns 0. diff --git a/src/corelib/kernel/qobject.cpp b/src/corelib/kernel/qobject.cpp index 583e580762..527a842d17 100644 --- a/src/corelib/kernel/qobject.cpp +++ b/src/corelib/kernel/qobject.cpp @@ -4102,6 +4102,37 @@ QDebug operator<<(QDebug dbg, const QObject *o) { be invoked using QMetaObject::invokeMethod(). */ +/*! + \macro Q_REVISION + \relates QObject + + Apply this macro to definitions of member functions to tag them with a + revision number in the meta-object system. The macro is written before + the return type, as shown in the following example: + + \snippet qmetaobject-revision/window.h Window class with revision + + This is useful when using the meta-object system to dynamically expose + objects to another API, as you can match the version expected by multiple + versions of the other API. Consider the following simplified example: + + \snippet qmetaobject-revision/main.cpp Window class using revision + + Using the same Window class as the previous example, the newProperty and + newMethod would only be exposed in this code when the expected version is + 1 or greater. + + Since all methods are considered to be in revision 0 if untagged, a tag + of Q_REVISION(0) is invalid and ignored. + + This tag is not used by the meta-object system itself. Currently this is only + used by the QtQml module. + + For a more generic string tag, see \l QMetaMethod::tag() + + \sa QMetaMethod::revision() +*/ + /*! \macro Q_SET_OBJECT_NAME(Object) \relates QObject -- cgit v1.2.3