Document support for QVariantList and QVariantMap type conversion

4 files changed, 156 insertions, 1 deletions

diff --git a/doc/src/declarative/qtbinding.qdoc b/doc/src/declarative/qtbinding.qdoc
index 71f41bc..04b8ca6 100644
--- a/doc/src/declarative/qtbinding.qdoc
+++ b/doc/src/declarative/qtbinding.qdoc
@@ -426,6 +426,7 @@ By default, QML recognizes the following data types:
 \o QSize, QSizeF
 \o QRect, QRectF
 \o QVariant
+\o QVariantList, QVariantMap
 \o QObject*
 \o Enumerations declared with Q_ENUMS()
 \endlist
@@ -434,6 +435,37 @@ To allow a custom C++ type to be created or used in QML, the C++ class must be r
 type using qmlRegisterType(), as shown in the \l {Defining new QML elements} section above.
 
 
+\section2 JavaScript arrays and objects
+
+There is built-in support for automatic type conversion between QVariantList and JavaScript
+arrays, and QVariantMap and JavaScript objects.
+
+For example, the function defined in QML below left expects two arguments, an array and an object, and prints
+their contents using the standard JavaScript syntax for array and object item access. The C++ code
+below right calls this function, passing a QVariantList and a QVariantMap, which are automatically
+converted to JavaScript array and object values, repectively:
+
+\table
+\row
+\o \snippet doc/src/snippets/declarative/qtbinding/variantlistmap/MyItem.qml 0
+\o \snippet doc/src/snippets/declarative/qtbinding/variantlistmap/main.cpp 0
+\endtable
+
+This produces output like:
+
+\code
+Array item: 10
+Array item: #00ff00
+Array item: bottles
+Object item: language = QML
+Object item: released = Tue Sep 21 2010 00:00:00 GMT+1000 (EST)
+\endcode
+
+Similarly, if a C++ type uses a QVariantList or QVariantMap type for a property or method
+parameter, the value can be created as a JavaScript array or object in the QML
+side, and is automatically converted to a QVariantList or QVariantMap when it is passed to C++.
+
+
 \section2 Using enumerations of a custom type
 
 To use an enumeration from a custom C++ component, the enumeration must be declared with Q_ENUMS() to
@@ -455,7 +487,7 @@ See the \l {Tutorial: Writing QML extensions with C++}{Writing QML extensions wi
 the \l {Extending QML in C++} reference documentation for more information.
 
 
-\section2 Automatic type conversion
+\section2 Automatic type conversion from strings
 
 As a convenience, some basic types can be specified in QML using format strings to make it easier to
 pass simple values from QML to C++.
diff --git a/doc/src/snippets/declarative/qtbinding/variantlistmap/MyItem.qml b/doc/src/snippets/declarative/qtbinding/variantlistmap/MyItem.qml
new file mode 100644
index 0000000..dd59fed
--- /dev/null
+++ b/doc/src/snippets/declarative/qtbinding/variantlistmap/MyItem.qml
@@ -0,0 +1,54 @@
+/****************************************************************************
+**
+** 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 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 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 QtQuick 1.0
+
+//![0]
+// MyItem.qml
+Item {
+    function readValues(anArray, anObject) {
+        for (var i=0; i<anArray.length; i++)
+            console.log("Array item:", anArray[i])
+
+        for (var prop in anObject) {
+            console.log("Object item:", prop, "=", anObject[prop])
+        }
+    }
+}
+//![0]
diff --git a/doc/src/snippets/declarative/qtbinding/variantlistmap/main.cpp b/doc/src/snippets/declarative/qtbinding/variantlistmap/main.cpp
new file mode 100644
index 0000000..9986264
--- /dev/null
+++ b/doc/src/snippets/declarative/qtbinding/variantlistmap/main.cpp
@@ -0,0 +1,67 @@
+/****************************************************************************
+**
+** 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 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 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 <QtCore>
+#include <QtDeclarative>
+
+int main(int argc, char *argv[]) {
+    QApplication app(argc, argv);
+
+//![0]
+// C++
+QDeclarativeView view(QUrl::fromLocalFile("MyItem.qml"));
+
+QVariantList list;
+list << 10 << Qt::green << "bottles";
+
+QVariantMap map;
+map.insert("language", "QML");
+map.insert("released", QDate(2010, 9, 21));
+
+QMetaObject::invokeMethod(view.rootObject(), "readValues",
+        Q_ARG(QVariant, QVariant::fromValue(list)),
+        Q_ARG(QVariant, QVariant::fromValue(map)));
+//![0]
+
+    view.setSource(QUrl::fromLocalFile("MyItem.qml"));
+    view.show();
+
+    return app.exec();
+}
+
diff --git a/doc/src/snippets/declarative/qtbinding/variantlistmap/variantlistmap.pro b/doc/src/snippets/declarative/qtbinding/variantlistmap/variantlistmap.pro
new file mode 100644
index 0000000..68eeaf2
--- /dev/null
+++ b/doc/src/snippets/declarative/qtbinding/variantlistmap/variantlistmap.pro
@@ -0,0 +1,2 @@
+QT += declarative
+SOURCES += main.cpp