Add support for more sequence types

This commit adds support for more sequence types by adding a sequence
wrapper.  This class enables conversion between v8::Array and C++
sequences of various types (currently just QList<int>, QList<qreal>,
QList<bool>, QList<QString>, QList<QUrl> and QStringList), but more
types can be added later if required).

When a JavaScript object is created from such a sequence, its
prototype object is set to the v8::Array prototype object.  The
indexed setter, indexed getter, length and toString methods are
implemented directly or in terms of the underlying sequence resource.

Note that currently, sequences of ValueTypes are NOT supported, due to
the fact that operations like:
     someObj.someValueTypeSequence[i].x = 5;
would not behave as required.

Task-number: QTBUG-20826
Task-number: QTBUG-21770
Change-Id: I36deb448fb0e87a32084a900e70a2604ff369309
Reviewed-by: Chris Adams <christopher.adams@nokia.com>

1 files changed, 30 insertions, 0 deletions

diff --git a/doc/src/declarative/extending.qdoc b/doc/src/declarative/extending.qdoc
index 0563f65cc0..bed31ab88a 100644
--- a/doc/src/declarative/extending.qdoc
+++ b/doc/src/declarative/extending.qdoc
@@ -236,6 +236,36 @@ The \c guest property declaration looks like this:
 \l {Extending QML - Object and List Property Types Example} shows the complete
 code used to create the \c BirthdayParty type.
 
+\section1 Sequence Types
+
+Certain C++ sequence types are supported transparently in QML as JavaScript Array types.
+In particular, QML currently supports:
+\list
+  \o \c {QList<int>}
+  \o \c {QList<qreal>}
+  \o \c {QList<bool>}
+  \o \c {QList<QString>}
+  \o \c {QList<QUrl>}
+\endlist
+
+These sequence types are implemented directly in terms of the underlying C++ sequence.
+There are two ways in which such sequences can be exposed to QML: as a Q_PROPERTY of
+the given sequence type; or as the return type of a Q_INVOKABLE method.  There are some
+differences in the way these are implemented, which are important to note.
+
+If the sequence is exposed as a Q_PROPERTY, accessing any value in the sequence by index
+will cause the sequence data to be read from the QObject's property, then a read to occur.
+Similarly, modifying any value in the sequence will cause the sequence data to be read,
+and then the modification will be performed and the modified sequence will be written back
+to the QObject's property.
+
+If the sequence is returned from a Q_INVOKABLE function, access and mutation is much cheaper,
+as no QObject property read or write occurs; instead, the C++ sequence data is accessed and
+modified directly.
+
+Other sequence types are not supported transparently, and instead an instance of any other
+sequence type will be passed between QML and C++ as an opaque QVariantList.
+
 \section1 Inheritance and Coercion
 
 \snippet examples/declarative/cppextensions/referenceexamples/coercion/example.qml 0