/usr/share/qt5/doc/qtqml/qtqml-cppintegration-data.html is in qtdeclarative5-doc-html 5.2.1-3ubuntu15.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 | <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en_US" lang="en_US">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- data.qdoc -->
<title>Data Type Conversion Between QML and C++ | QtQml 5.2</title>
<link rel="stylesheet" type="text/css" href="style/offline.css" />
</head>
<body>
<div class="header" id="qtdocheader">
<div class="main">
<div class="main-rounded">
<div class="navigationbar">
<ul>
<li>Qt 5.2</li>
<li><a href="qtqml-index.html">Qt QML</a></li>
<li>Data Type Conversion Between QML and C++</li>
<li id="buildversion">
Qt 5.2.1 Reference Documentation</li>
</ul>
</div>
</div>
<div class="content">
<div class="line">
<div class="content mainContent">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#data-ownership">Data Ownership</a></li>
<li class="level1"><a href="#basic-qt-data-types">Basic Qt Data Types</a></li>
<li class="level1"><a href="#qobject-derived-types">QObject-derived Types</a></li>
<li class="level1"><a href="#conversion-between-qt-and-javascript-types">Conversion Between Qt and JavaScript Types</a></li>
<li class="level2"><a href="#qvariantlist-and-qvariantmap-to-javascript-array-and-object">QVariantList and QVariantMap to JavaScript Array and Object</a></li>
<li class="level2"><a href="#qdatetime-to-javascript-date">QDateTime to JavaScript Date</a></li>
<li class="level2"><a href="#sequence-type-to-javascript-array">Sequence Type to JavaScript Array</a></li>
<li class="level1"><a href="#enumeration-types">Enumeration Types</a></li>
<li class="level2"><a href="#enumeration-types-as-signal-and-method-parameters">Enumeration Types as Signal and Method Parameters</a></li>
</ul>
</div>
<h1 class="title">Data Type Conversion Between QML and C++</h1>
<span class="subtitle"></span>
<!-- $$$qtqml-cppintegration-data.html-description -->
<div class="descr"> <a name="details"></a>
<p>When data values are exchanged between QML and C++, they are converted by the QML engine to have the correct data types as appropriate for use in QML or C++. This requires the exchanged data to be of a type that is recognizable by the engine.</p>
<p>The QML engine provides built-in support for a large number of Qt C++ data types. Additionally, custom C++ types may be registered with the QML type system to make them available to the engine.</p>
<p>This page discusses the data types supported by the QML engine and how they are converted between QML and C++.</p>
<a name="data-ownership"></a>
<h2>Data Ownership</h2>
<p>When data is transferred from C++ to QML, the ownership of the data always remains with C++. The exception to this rule is when a QObject is returned from an explicit C++ method call: in this case, the QML engine assumes ownership of the object, unless the ownership of the object has explicitly been set to remain with C++ by invoking <a href="qqmlengine.html#setObjectOwnership">QQmlEngine::setObjectOwnership</a>() with <a href="qqmlengine.html#ObjectOwnership-enum">QQmlEngine::CppOwnership</a> specified.</p>
<p>Additionally, the QML engine respects the normal QObject parent ownership semantics of Qt C++ objects, and will not ever take ownership of a QObject instance which already has a parent.</p>
<a name="basic-qt-data-types"></a>
<h2>Basic Qt Data Types</h2>
<p>By default, QML recognizes the following Qt data types, which are automatically converted to a corresponding <a href="qtqml-typesystem-basictypes.html">QML basic type</a> when passed from C++ to QML and vice-versa:</p>
<table class="generic">
<tr valign="top" class="odd"><td >Qt Type</td><td >QML Basic Type</td></tr>
<tr valign="top" class="even"><td >bool</td><td ><a href="qml-bool.html">bool</a></td></tr>
<tr valign="top" class="odd"><td >unsigned int, int</td><td ><a href="qml-int.html">int</a></td></tr>
<tr valign="top" class="even"><td >double</td><td ><a href="qml-double.html">double</a></td></tr>
<tr valign="top" class="odd"><td >float, qreal</td><td ><a href="qml-real.html">real</a></td></tr>
<tr valign="top" class="even"><td >QString</td><td ><a href="qml-string.html">string</a></td></tr>
<tr valign="top" class="odd"><td >QUrl</td><td ><a href="qml-url.html">url</a></td></tr>
<tr valign="top" class="even"><td >QColor</td><td >color</td></tr>
<tr valign="top" class="odd"><td >QFont</td><td >font</td></tr>
<tr valign="top" class="even"><td >QDate</td><td ><a href="qml-date.html">date</a></td></tr>
<tr valign="top" class="odd"><td >QTime, QDateTime</td><td >time</td></tr>
<tr valign="top" class="even"><td >QPoint, QPointF</td><td ><a href="qml-point.html">point</a></td></tr>
<tr valign="top" class="odd"><td >QSize, QSizeF</td><td ><a href="qml-size.html">size</a></td></tr>
<tr valign="top" class="even"><td >QRect, QRectF</td><td ><a href="qml-rect.html">rect</a></td></tr>
<tr valign="top" class="odd"><td >QMatrix4x4</td><td >matrix4x4</td></tr>
<tr valign="top" class="even"><td >QQuaternion</td><td >quaternion</td></tr>
<tr valign="top" class="odd"><td >QVector2D, QVector3D, QVector4D</td><td >vector2d, vector3d, vector4d</td></tr>
<tr valign="top" class="even"><td >Enums declared with Q_ENUMS()</td><td ><a href="qml-enumeration.html">enumeration</a></td></tr>
</table>
<p><b>Note: </b>Classes provided by the Qt GUI module, such as QColor, QFont, QQuaternion and QMatrix4x4, are only available from QML when the Qt Quick module is included.</p><p>As a convenience, many of these types can be specified in QML by string values, or by a related method provided by the <a href="qml-qtqml-qt.html">QtQml::Qt</a> object. For example, the Image::sourceSize property is of type <a href="qml-size.html">size</a> (which automatically translates to the QSize type) and can be specified by a string value formatted as "width<tt>x</tt>height", or by the Qt.size() function:</p>
<pre class="qml"><span class="type">Item</span> {
<span class="type">Image</span> { <span class="name">sourceSize</span>: <span class="string">"100x200"</span> }
<span class="type">Image</span> { <span class="name">sourceSize</span>: <span class="name">Qt</span>.<span class="name">size</span>(<span class="number">100</span>, <span class="number">200</span>) }
}</pre>
<p>See documentation for each individual type under <a href="qtqml-typesystem-basictypes.html">QML Basic Types</a> for more information.</p>
<a name="qobject-derived-types"></a>
<h2>QObject-derived Types</h2>
<p>Any QObject-derived class may be used as a type for the exchange of data between QML and C++, providing the class has been registered with the QML type system.</p>
<p>The engine allows the registration of both instantiable and non-instantiable types. Once a class is registered as a QML type, it can be used as a data type for exchanging data between QML and C++. See <a href="qtqml-cppintegration-definetypes.html#registering-c-types-with-the-qml-type-system">Registering C++ types with the QML type system</a> for further details on type registration.</p>
<a name="conversion-between-qt-and-javascript-types"></a>
<h2>Conversion Between Qt and JavaScript Types</h2>
<p>The QML engine has built-in support for converting a number of Qt types to related JavaScript types, and vice-versa, when transferring data between QML and C++. This makes it possible to use these types and receive them in C++ or JavaScript without needing to implement custom types that provide access to the data values and their attributes.</p>
<p>(Note that the JavaScript environment in QML modifies native JavaScript object prototypes, including those of <tt>String</tt>, <tt>Date</tt> and <tt>Number</tt>, to provide additional features. See the <a href="qtqml-javascript-hostenvironment.html">JavaScript Host Environment</a> for further details.)</p>
<a name="qvariantlist-and-qvariantmap-to-javascript-array-and-object"></a>
<h3>QVariantList and QVariantMap to JavaScript Array and Object</h3>
<p>The QML engine provides automatic type conversion between QVariantList and JavaScript arrays, and between QVariantMap and JavaScript objects.</p>
<p>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:</p>
<table class="generic">
<thead><tr class="qt-style"></tr></thead>
<tr valign="top" class="odd"><td ><pre class="qml"><span class="comment">// MyItem.qml</span>
<span class="type">Item</span> {
<span class="keyword">function</span> <span class="name">readValues</span>(<span class="name">anArray</span>, anObject) {
<span class="keyword">for</span> (<span class="keyword">var</span> <span class="name">i</span>=<span class="number">0</span>; <span class="name">i</span><span class="operator"><</span><span class="name">anArray</span>.<span class="name">length</span>; i++)
<span class="name">console</span>.<span class="name">log</span>(<span class="string">"Array item:"</span>, <span class="name">anArray</span>[<span class="name">i</span>])
<span class="keyword">for</span> (<span class="keyword">var</span> <span class="name">prop</span> in <span class="name">anObject</span>) {
<span class="name">console</span>.<span class="name">log</span>(<span class="string">"Object item:"</span>, <span class="name">prop</span>, <span class="string">"="</span>, <span class="name">anObject</span>[<span class="name">prop</span>])
}
}
}</pre>
</td><td ><pre class="cpp"><span class="comment">// C++</span>
<span class="type">QQuickView</span> view(<span class="type">QUrl</span><span class="operator">::</span>fromLocalFile(<span class="string">"MyItem.qml"</span>));
<span class="type">QVariantList</span> list;
list <span class="operator"><</span><span class="operator"><</span> <span class="number">10</span> <span class="operator"><</span><span class="operator"><</span> <span class="type"><a href="qml-qtqml-qt.html">Qt</a></span><span class="operator">::</span>green <span class="operator"><</span><span class="operator"><</span> <span class="string">"bottles"</span>;
<span class="type">QVariantMap</span> map;
map<span class="operator">.</span>insert(<span class="string">"language"</span><span class="operator">,</span> <span class="string">"QML"</span>);
map<span class="operator">.</span>insert(<span class="string">"released"</span><span class="operator">,</span> <span class="type">QDate</span>(<span class="number">2010</span><span class="operator">,</span> <span class="number">9</span><span class="operator">,</span> <span class="number">21</span>));
<span class="type">QMetaObject</span><span class="operator">::</span>invokeMethod(view<span class="operator">.</span>rootObject()<span class="operator">,</span> <span class="string">"readValues"</span><span class="operator">,</span>
Q_ARG(<span class="type">QVariant</span><span class="operator">,</span> <span class="type">QVariant</span><span class="operator">::</span>fromValue(list))<span class="operator">,</span>
Q_ARG(<span class="type">QVariant</span><span class="operator">,</span> <span class="type">QVariant</span><span class="operator">::</span>fromValue(map)));</pre>
</td></tr>
</table>
<p>This produces output like:</p>
<pre class="cpp">Array item: <span class="number">10</span>
Array item: <span class="preprocessor">#00ff00</span>
Array item: bottles
Object item: language <span class="operator">=</span> QML
Object item: released <span class="operator">=</span> Tue Sep <span class="number">21</span> <span class="number">2010</span> <span class="number">00</span>:<span class="number">00</span>:<span class="number">00</span> GMT<span class="operator">+</span><span class="number">1000</span> (EST)</pre>
<p>Similarly, if a C++ type uses a QVariantList or QVariantMap type for a property type or method parameter, the value can be created as a JavaScript array or object in QML, and is automatically converted to a QVariantList or QVariantMap when it is passed to C++.</p>
<a name="qdatetime-to-javascript-date"></a>
<h3>QDateTime to JavaScript Date</h3>
<p>The QML engine provides automatic type conversion between QDateTime values and JavaScript <tt>Date</tt> objects.</p>
<p>For example, the function defined in QML below left expects a JavaScript <tt>Date</tt> object, and also returns a new <tt>Date</tt> object with the current date and time. The C++ code below right calls this function, passing a QDateTime value that is automatically converted by the engine into a <tt>Date</tt> object when it is passed to the <tt>readDate()</tt> function. In turn, the readDate() function returns a <tt>Date</tt> object that is automatically converted into a QDateTime value when it is received in C++:</p>
<table class="generic">
<thead><tr class="qt-style"></tr></thead>
<tr valign="top" class="odd"><td ><pre class="qml"><span class="comment">// MyItem.qml</span>
<span class="type">Item</span> {
<span class="keyword">function</span> <span class="name">readDate</span>(<span class="name">dt</span>) {
<span class="name">console</span>.<span class="name">log</span>(<span class="string">"The given date is:"</span>, <span class="name">dt</span>.<span class="name">toUTCString</span>());
<span class="keyword">return</span> new <span class="name">Date</span>();
}
}</pre>
</td><td ><pre class="cpp"><span class="comment">// C++</span>
<span class="type">QQuickView</span> view(<span class="type">QUrl</span><span class="operator">::</span>fromLocalFile(<span class="string">"MyItem.qml"</span>));
<span class="type">QDateTime</span> dateTime <span class="operator">=</span> <span class="type">QDateTime</span><span class="operator">::</span>currentDateTime();
<span class="type">QDateTime</span> retValue;
<span class="type">QMetaObject</span><span class="operator">::</span>invokeMethod(view<span class="operator">.</span>rootObject()<span class="operator">,</span> <span class="string">"readDate"</span><span class="operator">,</span>
Q_RETURN_ARG(<span class="type">QVariant</span><span class="operator">,</span> retValue)<span class="operator">,</span>
Q_ARG(<span class="type">QVariant</span><span class="operator">,</span> <span class="type">QVariant</span><span class="operator">::</span>fromValue(dateTime)));
qDebug() <span class="operator"><</span><span class="operator"><</span> <span class="string">"Value returned from readDate():"</span> <span class="operator"><</span><span class="operator"><</span> retValue;</pre>
</td></tr>
</table>
<p>Similarly, if a C++ type uses a QDateTime for a property type or method parameter, the value can be created as a JavaScript <tt>Date</tt> object in QML, and is automatically converted to a QDateTime value when it is passed to C++.</p>
<a name="sequence-type-to-javascript-array"></a>
<h3>Sequence Type to JavaScript Array</h3>
<p>Certain C++ sequence types are supported transparently in QML as JavaScript <tt>Array</tt> types.</p>
<p>In particular, QML currently supports:</p>
<ul>
<li><tt>QList<int></tt></li>
<li><tt>QList<qreal></tt></li>
<li><tt>QList<bool></tt></li>
<li><tt>QList<QString></tt> and <tt>QStringList</tt></li>
<li><tt>QList<QUrl></tt></li>
</ul>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p><b>Important Note:</b> There are some minor differences between the semantics of such sequence Array types and default JavaScript Array types which result from the use of a C++ storage type in the implementation. In particular, deleting an element from an Array will result in a default-constructed value replacing that element, rather than an Undefined value. Similarly, setting the length property of the Array to a value larger than its current value will result in the Array being padded out to the specified length with default-constructed elements rather than Undefined elements. Finally, the Qt container classes support signed (rather than unsigned) integer indexes; thus, attempting to access any index greater than INT_MAX will fail.</p>
<p>The default-constructed values for each sequence type are as follows:</p>
<table class="generic">
<tr valign="top" class="odd"><td >QList<int></td><td >integer value 0</td></tr>
<tr valign="top" class="even"><td >QList<qreal></td><td >real value 0.0</td></tr>
<tr valign="top" class="odd"><td >QList<bool></td><td >boolean value <tt>false</tt></td></tr>
<tr valign="top" class="even"><td >QList<QString> and QStringList</td><td >empty QString</td></tr>
<tr valign="top" class="odd"><td >QList<QUrl></td><td >empty QUrl</td></tr>
</table>
<p>If you wish to remove elements from a sequence rather than simply replace them with default constructed values, do not use the indexed delete operator ("delete sequence[i]") but instead use the <tt>splice</tt> function ("sequence.splice(startIndex, deleteCount)").</p>
<a name="enumeration-types"></a>
<h2>Enumeration Types</h2>
<p>To use a custom enumeration as a data type, its class must be registered and the enumeration must also be declared with Q_ENUMS() to register it with Qt's meta object system. For example, the <tt>Message</tt> class below has a <tt>Status</tt> enum:</p>
<pre class="cpp"> <span class="keyword">class</span> Message : <span class="keyword">public</span> <span class="type">QObject</span>
{
Q_OBJECT
Q_ENUMS(Status)
Q_PROPERTY(Status status READ status NOTIFY statusChanged)
<span class="keyword">public</span>:
<span class="keyword">enum</span> Status {
Ready<span class="operator">,</span>
Loading<span class="operator">,</span>
Error
};
Status status() <span class="keyword">const</span>;
<span class="keyword">signals</span>:
<span class="type">void</span> statusChanged();
};</pre>
<p>Providing the <tt>Message</tt> class has been <a href="qtqml-cppintegration-definetypes.html#registering-c-types-with-the-qml-type-system">registered</a> with the QML type system, its <tt>Status</tt> enum can be used from QML:</p>
<pre class="qml"><span class="type">Message</span> {
<span class="name">onStatusChanged</span>: {
<span class="keyword">if</span> (<span class="name">status</span> <span class="operator">==</span> <span class="name">Message</span>.<span class="name">Ready</span>)
<span class="name">console</span>.<span class="name">log</span>(<span class="string">"Message is loaded!"</span>)
}
}</pre>
<p><b>Note: </b>The names of enum values must begin with a capital letter in order to be accessible from QML.</p><a name="enumeration-types-as-signal-and-method-parameters"></a>
<h3>Enumeration Types as Signal and Method Parameters</h3>
<p>C++ signals and methods with enumeration-type parameters can be used from QML provided that the enumeration and the signal or method are both declared within the same class, or that the enumeration value is one of those declared in the <a href="qml-qtqml-qt.html">Qt Namespace</a>.</p>
<p>Additionally, if a C++ signal with an enum parameter should be connectable to a QML function using the <a href="qtqml-syntax-signals.html#connecting-signals-to-methods-and-signals">connect()</a> function, the enum type must be registered using qRegisterMetaType().</p>
<p>For QML signals, enum values may be passed as signal parameters using the <tt>int</tt> type:</p>
<pre class="qml"> <span class="type">Message</span> {
signal <span class="type">someOtherSignal</span>(int statusValue)
<span class="name">Component</span>.onCompleted: {
<span class="name">someOtherSignal</span>(<span class="name">Message</span>.<span class="name">Loading</span>)
}
}</pre>
</div>
<!-- @@@qtqml-cppintegration-data.html -->
</div>
</div>
</div>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2013 Digia Plc and/or its
subsidiaries. Documentation contributions included herein are the copyrights of
their respective owners.<br> The documentation provided herein is licensed under the terms of the <a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation License version 1.3</a> as published by the Free Software Foundation.<br> Digia, Qt and their respective logos are trademarks of Digia Plc in Finland and/or other countries worldwide. All other trademarks are property
of their respective owners. </p>
</div>
</body>
</html>
|