<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE html> <html lang="en"> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <!-- contextproperties.qdoc --> <title>Embedding C++ Objects into QML with Context Properties | Qt QML 5.9</title> <link rel="stylesheet" type="text/css" href="style/offline-simple.css" /> <script type="text/javascript"> document.getElementsByTagName("link").item(0).setAttribute("href", "style/offline.css"); // loading style sheet breaks anchors that were jumped to before // so force jumping to anchor again setTimeout(function() { var anchor = location.hash; // need to jump to different anchor first (e.g. none) location.hash = "#"; setTimeout(function() { location.hash = anchor; }, 0); }, 0); </script> </head> <body> <div class="header" id="qtdocheader"> <div class="main"> <div class="main-rounded"> <div class="navigationbar"> <table><tr> <td >Qt 5.9</td><td ><a href="qtqml-index.html">Qt QML</a></td><td >Embedding C++ Objects into QML with Context Properties</td></tr></table><table class="buildversion"><tr> <td id="buildversion" width="100%" align="right">Qt 5.9.4 Reference Documentation</td> </tr></table> </div> </div> <div class="content"> <div class="line"> <div class="content mainContent"> <div class="sidebar"> <div class="toc"> <h3><a name="toc">Contents</a></h3> <ul> <li class="level1"><a href="#setting-a-simple-context-property">Setting a Simple Context Property</a></li> <li class="level1"><a href="#setting-an-object-as-a-context-property">Setting an Object as a Context Property</a></li> </ul> </div> <div class="sidebar-content" id="sidebar-content"></div></div> <h1 class="title">Embedding C++ Objects into QML with Context Properties</h1> <span class="subtitle"></span> <!-- $$$qtqml-cppintegration-contextproperties.html-description --> <div class="descr"> <a name="details"></a> <p>When loading a QML object into a C++ application, it can be useful to directly embed some C++ data that can be used from within the QML code. This makes it possible, for example, to invoke a C++ method on the embedded object, or use a C++ object instance as a data model for a QML view.</p> <p>The ability to inject C++ data into a QML object is made possible by the <a href="qqmlcontext.html">QQmlContext</a> class. This class exposes data to the context of a QML object so that the data can be referred to directly from within the scope of the QML code.</p> <a name="setting-a-simple-context-property"></a> <h2 id="setting-a-simple-context-property">Setting a Simple Context Property</h2> <p>For example, here is a QML item that refers to a <code>currentDateTime</code> value that does not exist in the current scope:</p> <pre class="qml"> <span class="comment">// MyItem.qml</span> import QtQuick 2.0 <span class="type">Text</span> { <span class="name">text</span>: <span class="name">currentDateTime</span> } </pre> <p>This <code>currentDateTime</code> value can be set directly by the C++ application that loads the QML component, using <a href="qqmlcontext.html#setContextProperty">QQmlContext::setContextProperty</a>():</p> <pre class="cpp"> <span class="type">QQuickView</span> view; view<span class="operator">.</span>rootContext()<span class="operator">-</span><span class="operator">></span>setContextProperty(<span class="string">"currentDateTime"</span><span class="operator">,</span> <span class="type">QDateTime</span><span class="operator">::</span>currentDateTime()); view<span class="operator">.</span>setSource(<span class="type">QUrl</span><span class="operator">::</span>fromLocalFile(<span class="string">"MyItem.qml"</span>)); view<span class="operator">.</span>show(); </pre> <p><b>Note: </b>Since all expressions evaluated in QML are evaluated in a particular context, if the context is modified, all bindings in that context will be re-evaluated. Thus, context properties should be used with care outside of application initialization, as this may lead to decreased application performance.</p><a name="setting-an-object-as-a-context-property"></a> <h2 id="setting-an-object-as-a-context-property">Setting an Object as a Context Property</h2> <p>Context properties can hold either QVariant or QObject* values. This means custom C++ objects can also be injected using this approach, and these objects can be modified and read directly in QML. Here, we modify the above example to embed a QObject instance instead of a QDateTime value, and the QML code invokes a method on the object instance:</p> <div class="table"><table class="generic"> <tr valign="top" class="odd"><td >C++</td><td ><pre class="cpp"> <span class="keyword">class</span> ApplicationData : <span class="keyword">public</span> <span class="type">QObject</span> { Q_OBJECT <span class="keyword">public</span>: Q_INVOKABLE <span class="type">QDateTime</span> getCurrentDateTime() <span class="keyword">const</span> { <span class="keyword">return</span> <span class="type">QDateTime</span><span class="operator">::</span>currentDateTime(); } }; <span class="type">int</span> main(<span class="type">int</span> argc<span class="operator">,</span> <span class="type">char</span> <span class="operator">*</span>argv<span class="operator">[</span><span class="operator">]</span>) { <span class="type">QGuiApplication</span> app(argc<span class="operator">,</span> argv); <span class="type">QQuickView</span> view; ApplicationData data; view<span class="operator">.</span>rootContext()<span class="operator">-</span><span class="operator">></span>setContextProperty(<span class="string">"applicationData"</span><span class="operator">,</span> <span class="operator">&</span>data); view<span class="operator">.</span>setSource(<span class="type">QUrl</span><span class="operator">::</span>fromLocalFile(<span class="string">"MyItem.qml"</span>)); view<span class="operator">.</span>show(); <span class="keyword">return</span> app<span class="operator">.</span>exec(); } </pre> </td></tr> <tr valign="top" class="even"><td >QML</td><td ><pre class="qml"> <span class="comment">// MyItem.qml</span> import QtQuick 2.0 <span class="type">Text</span> { <span class="name">text</span>: <span class="name">applicationData</span>.<span class="name">getCurrentDateTime</span>() } </pre> </td></tr> </table></div> <p>(Note that date/time values returned from C++ to QML can be formatted through <a href="qml-qtqml-qt.html#formatDateTime-method">Qt.formatDateTime()</a> and associated functions.)</p> <p>If the QML item needs to receive signals from the context property, it can connect to them using the <a href="qml-qtqml-connections.html">Connections</a> type. For example, if <code>ApplicationData</code> has a signal named <code>dataChanged()</code>, this signal can be connected to using an <code>onDataChanged</code> handler within a <a href="qml-qtqml-connections.html">Connections</a> object:</p> <pre class="qml"> <span class="type">Text</span> { <span class="name">text</span>: <span class="name">applicationData</span>.<span class="name">getCurrentDateTime</span>() <span class="type"><a href="qml-qtqml-connections.html">Connections</a></span> { <span class="name">target</span>: <span class="name">applicationData</span> <span class="name">onDataChanged</span>: <span class="name">console</span>.<span class="name">log</span>(<span class="string">"The application data changed!"</span>) } } </pre> <p>Context properties can be useful for using C++ based data models in a QML view. See the following examples:</p> <ul> <li>String ListModel</li> <li>Object ListModel</li> <li>AbstractItemModel</li> </ul> <p>demonstrating the use of QStringList, QList<QObject*>-based models and QAbstractItemModel in QML views.</p> <p>Also see the <a href="qqmlcontext.html">QQmlContext</a> documentation for more information.</p> </div> <!-- @@@qtqml-cppintegration-contextproperties.html --> </div> </div> </div> </div> </div> <div class="footer"> <p> <acronym title="Copyright">©</acronym> 2017 The Qt Company Ltd. 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> Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners. </p> </div> </body> </html>