Document calling QObject methods from QML in Extending QML in C++ docs.

9 files changed, 431 insertions, 1 deletions

diff --git a/examples/declarative/cppextensions/referenceexamples/methods/birthdayparty.cpp b/examples/declarative/cppextensions/referenceexamples/methods/birthdayparty.cpp
new file mode 100644
index 0000000..801c7ba
--- /dev/null
+++ b/examples/declarative/cppextensions/referenceexamples/methods/birthdayparty.cpp
@@ -0,0 +1,80 @@
+/****************************************************************************
+**
+** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the examples 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 Nokia Corporation 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 "birthdayparty.h"
+
+BirthdayParty::BirthdayParty(QObject *parent)
+: QObject(parent), m_host(0)
+{
+}
+
+// ![0]
+Person *BirthdayParty::host() const
+{
+    return m_host;
+}
+
+void BirthdayParty::setHost(Person *c)
+{
+    m_host = c;
+}
+
+QDeclarativeListProperty<Person> BirthdayParty::guests() 
+{
+    return QDeclarativeListProperty<Person>(this, m_guests);
+}
+
+int BirthdayParty::guestCount() const
+{
+    return m_guests.count();
+}
+
+Person *BirthdayParty::guest(int index) const
+{
+    return m_guests.at(index);
+}
+
+void BirthdayParty::invite(const QString &name)
+{
+    Person *person = new Person(this);
+    person->setName(name);
+    m_guests.append(person);
+}
+// ![0]
+
diff --git a/examples/declarative/cppextensions/referenceexamples/methods/birthdayparty.h b/examples/declarative/cppextensions/referenceexamples/methods/birthdayparty.h
new file mode 100644
index 0000000..b89a30e
--- /dev/null
+++ b/examples/declarative/cppextensions/referenceexamples/methods/birthdayparty.h
@@ -0,0 +1,71 @@
+/****************************************************************************
+**
+** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the examples 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 Nokia Corporation 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 BIRTHDAYPARTY_H
+#define BIRTHDAYPARTY_H
+
+#include <QObject>
+#include <QDeclarativeListProperty>
+#include "person.h"
+
+class BirthdayParty : public QObject
+{
+    Q_OBJECT
+    Q_PROPERTY(Person *host READ host WRITE setHost)
+    Q_PROPERTY(QDeclarativeListProperty<Person> guests READ guests)
+public:
+    BirthdayParty(QObject *parent = 0);
+
+    Person *host() const;
+    void setHost(Person *);
+
+    QDeclarativeListProperty<Person> guests();
+    int guestCount() const;
+    Person *guest(int) const;
+
+// ![0]
+    Q_INVOKABLE void invite(const QString &name);
+// ![0]
+
+private:
+    Person *m_host;
+    QList<Person *> m_guests;
+};
+
+#endif // BIRTHDAYPARTY_H
diff --git a/examples/declarative/cppextensions/referenceexamples/methods/example.qml b/examples/declarative/cppextensions/referenceexamples/methods/example.qml
new file mode 100644
index 0000000..c4698a2
--- /dev/null
+++ b/examples/declarative/cppextensions/referenceexamples/methods/example.qml
@@ -0,0 +1,58 @@
+/****************************************************************************
+**
+** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the QtDeclarative module 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 Nokia Corporation 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$
+**
+****************************************************************************/
+
+import Qt 4.7
+import People 1.0
+
+// ![0]
+BirthdayParty {
+    host: Person {
+        name: "Bob Jones"
+        shoeSize: 12
+    }
+    guests: [
+        Person { name: "Leo Hodges" },
+        Person { name: "Jack Smith" },
+        Person { name: "Anne Brown" }
+    ]
+
+    Component.onCompleted: invite("William Green")
+}
+// ![0]
diff --git a/examples/declarative/cppextensions/referenceexamples/methods/main.cpp b/examples/declarative/cppextensions/referenceexamples/methods/main.cpp
new file mode 100644
index 0000000..d974647
--- /dev/null
+++ b/examples/declarative/cppextensions/referenceexamples/methods/main.cpp
@@ -0,0 +1,68 @@
+/****************************************************************************
+**
+** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the examples 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 Nokia Corporation 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 <QCoreApplication>
+#include <QDeclarativeEngine>
+#include <QDeclarativeComponent>
+#include <QDebug>
+#include "birthdayparty.h"
+#include "person.h"
+
+int main(int argc, char ** argv)
+{
+    QCoreApplication app(argc, argv);
+
+    qmlRegisterType<BirthdayParty>("People", 1,0, "BirthdayParty");
+    qmlRegisterType<Person>("People", 1,0, "Person");
+
+    QDeclarativeEngine engine;
+    QDeclarativeComponent component(&engine, QUrl("qrc:example.qml"));
+    BirthdayParty *party = qobject_cast<BirthdayParty *>(component.create());
+
+    if (party && party->host()) {
+        qWarning() << party->host()->name() << "is having a birthday!";
+        qWarning() << "They are inviting:";
+        for (int ii = 0; ii < party->guestCount(); ++ii)
+            qWarning() << "   " << party->guest(ii)->name();
+    } else {
+        qWarning() << component.errors();
+    }
+
+    return 0;
+}
diff --git a/examples/declarative/cppextensions/referenceexamples/methods/methods.pro b/examples/declarative/cppextensions/referenceexamples/methods/methods.pro
new file mode 100644
index 0000000..a62927e
--- /dev/null
+++ b/examples/declarative/cppextensions/referenceexamples/methods/methods.pro
@@ -0,0 +1,18 @@
+TEMPLATE = app
+TARGET = methods
+DEPENDPATH += .
+INCLUDEPATH += .
+QT += declarative
+
+# Input
+SOURCES += main.cpp \
+           person.cpp \
+           birthdayparty.cpp 
+HEADERS += person.h \
+           birthdayparty.h
+RESOURCES += methods.qrc
+
+target.path = $$[QT_INSTALL_EXAMPLES]/declarative/extending/methods
+sources.files = $$SOURCES $$HEADERS $$RESOURCES $$FORMS methods.pro
+sources.path = $$[QT_INSTALL_EXAMPLES]/declarative/extending/methods
+INSTALLS += target sources
diff --git a/examples/declarative/cppextensions/referenceexamples/methods/methods.qrc b/examples/declarative/cppextensions/referenceexamples/methods/methods.qrc
new file mode 100644
index 0000000..e2fa01d
--- /dev/null
+++ b/examples/declarative/cppextensions/referenceexamples/methods/methods.qrc
@@ -0,0 +1,5 @@
+<!DOCTYPE RCC><RCC version="1.0">
+<qresource>
+    <file>example.qml</file>
+</qresource>
+</RCC>
diff --git a/examples/declarative/cppextensions/referenceexamples/methods/person.cpp b/examples/declarative/cppextensions/referenceexamples/methods/person.cpp
new file mode 100644
index 0000000..beffe78
--- /dev/null
+++ b/examples/declarative/cppextensions/referenceexamples/methods/person.cpp
@@ -0,0 +1,66 @@
+/****************************************************************************
+**
+** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the examples 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 Nokia Corporation 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 "person.h"
+
+Person::Person(QObject *parent)
+: QObject(parent), m_shoeSize(0)
+{
+}
+
+QString Person::name() const
+{
+    return m_name;
+}
+
+void Person::setName(const QString &n)
+{
+    m_name = n;
+}
+
+int Person::shoeSize() const
+{
+    return m_shoeSize;
+}
+
+void Person::setShoeSize(int s)
+{
+    m_shoeSize = s;
+}
+
diff --git a/examples/declarative/cppextensions/referenceexamples/methods/person.h b/examples/declarative/cppextensions/referenceexamples/methods/person.h
new file mode 100644
index 0000000..8c950da
--- /dev/null
+++ b/examples/declarative/cppextensions/referenceexamples/methods/person.h
@@ -0,0 +1,63 @@
+/****************************************************************************
+**
+** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the examples 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 Nokia Corporation 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 PERSON_H
+#define PERSON_H
+
+#include <QObject>
+
+class Person : public QObject
+{
+    Q_OBJECT
+    Q_PROPERTY(QString name READ name WRITE setName)
+    Q_PROPERTY(int shoeSize READ shoeSize WRITE setShoeSize)
+public:
+    Person(QObject *parent = 0);
+
+    QString name() const;
+    void setName(const QString &);
+
+    int shoeSize() const;
+    void setShoeSize(int);
+private:
+    QString m_name;
+    int m_shoeSize;
+};
+
+#endif // PERSON_H
diff --git a/examples/declarative/cppextensions/referenceexamples/referenceexamples.pro b/examples/declarative/cppextensions/referenceexamples/referenceexamples.pro
index 169c7ab..505cefd 100644
--- a/examples/declarative/cppextensions/referenceexamples/referenceexamples.pro
+++ b/examples/declarative/cppextensions/referenceexamples/referenceexamples.pro
@@ -10,4 +10,5 @@ SUBDIRS += \
     grouped \
     properties \
     signal \
-    valuesource
+    valuesource \
+    methods