<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- hostenvironment.qdoc -->
<title>JavaScript Host Environment | 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 >JavaScript Host Environment</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="#common-base">Common Base</a></li>
<li class="level1"><a href="#qml-global-object">QML Global Object</a></li>
<li class="level1"><a href="#javascript-objects-and-functions">JavaScript Objects and Functions</a></li>
<li class="level1"><a href="#javascript-environment-restrictions">JavaScript Environment Restrictions</a></li>
</ul>
</div>
<div class="sidebar-content" id="sidebar-content"></div></div>
<h1 class="title">JavaScript Host Environment</h1>
<span class="subtitle"></span>
<!-- $$$qtqml-javascript-hostenvironment.html-description -->
<div class="descr"> <a name="details"></a>
<p>QML provides a JavaScript host environment tailored to writing QML applications. This environment is different from the host environment provided by a browser or a server-side JavaScript environment such as Node.js. For example, QML does not provide a <code>window</code> object or <code>DOM API</code> as commonly found in a browser environment.</p>
<a name="common-base"></a>
<h2 id="common-base">Common Base</h2>
<p>Like a browser or server-side JavaScript environment, the QML runtime implements the <a href="http://www.ecma-international.org/publications/standards/Ecma-262.htm">ECMAScript Language Specification</a> standard. This provides access to all of the built-in types and functions defined by the standard, such as Object, Array, and Math. The QML runtime implements the 5th edition of the standard, which is the same edition commonly implemented by browsers.</p>
<p>The standard ECMAScript built-ins are not explicitly documented in the QML documentation. For more information on their use, please refer to the ECMA-262 5th edition standard or one of the many online JavaScript reference and tutorial sites, such as the <a href="http://www.w3schools.com/jsref/default.asp">W3Schools JavaScript Reference</a> (JavaScript Objects Reference section). Many sites focus on JavaScript in the browser, so in some cases you may need to double check the specification to determine whether a given function or object is part of standard ECMAScript or specific to the browser environment. In the case of the W3Schools link above, the <code>JavaScript Objects Reference</code> section generally covers the standard, while the <code>Browser Objects Reference</code> and <code>HTML DOM Objects Reference</code> sections are browser specific (and thus not applicable to QML).</p>
<a name="qml-global-object"></a>
<h2 id="qml-global-object">QML Global Object</h2>
<p>The QML JavaScript host environment implements a number of host objects and functions, as detailed in the <a href="qtqml-javascript-qmlglobalobject.html">QML Global Object</a> documentation.</p>
<p>These host objects and functions are always available, regardless of whether any modules have been imported.</p>
<a name="javascript-objects-and-functions"></a>
<h2 id="javascript-objects-and-functions">JavaScript Objects and Functions</h2>
<p>A list of the JavaScript objects, functions and properties supported by the QML engine can be found in the <a href="qtqml-javascript-functionlist.html">List of JavaScript Objects and Functions</a>.</p>
<p>Note that QML makes the following modifications to native objects:</p>
<ul>
<li>An <a href="qml-qtqml-string.html#arg-method">arg()</a> function is added to the <a href="qml-qtqml-string.html">String</a> prototype.</li>
<li>Locale-aware conversion functions are added to the <a href="qml-qtqml-date.html">Date</a> and <a href="qml-qtqml-number.html">Number</a> prototypes.</li>
</ul>
<a name="javascript-environment-restrictions"></a>
<h2 id="javascript-environment-restrictions">JavaScript Environment Restrictions</h2>
<p>QML implements the following restrictions for JavaScript code:</p>
<ul>
<li>JavaScript code written in a <code>.qml</code> file cannot modify the global object. JavaScript code in a .js file can modify the global object, and those modifications will be visible to the .qml file when <a href="qtqml-javascript-imports.html#importing-a-javascript-resource-from-a-qml-document">imported</a>.<p>In QML, the global object is constant - existing properties cannot be modified or deleted, and no new properties may be created.</p>
<p>Most JavaScript programs do not intentionally modify the global object. However, JavaScript's automatic creation of undeclared variables is an implicit modification of the global object, and is prohibited in QML.</p>
<p>Assuming that the <code>a</code> variable does not exist in the scope chain, the following code is illegal in QML:</p>
<pre class="cpp">
<span class="comment">// Illegal modification of undeclared variable</span>
a <span class="operator">=</span> <span class="number">1</span>;
<span class="keyword">for</span> (var ii <span class="operator">=</span> <span class="number">1</span>; ii <span class="operator"><</span> <span class="number">10</span>; <span class="operator">+</span><span class="operator">+</span>ii)
a <span class="operator">=</span> a <span class="operator">*</span> ii;
console<span class="operator">.</span>log(<span class="string">"Result: "</span> <span class="operator">+</span> a);
</pre>
<p>It can be trivially modified to this legal code.</p>
<pre class="cpp">
var a <span class="operator">=</span> <span class="number">1</span>;
<span class="keyword">for</span> (var ii <span class="operator">=</span> <span class="number">1</span>; ii <span class="operator"><</span> <span class="number">10</span>; <span class="operator">+</span><span class="operator">+</span>ii)
a <span class="operator">=</span> a <span class="operator">*</span> ii;
console<span class="operator">.</span>log(<span class="string">"Result: "</span> <span class="operator">+</span> a);
</pre>
<p>Any attempt to modify the global object - either implicitly or explicitly - will cause an exception. If uncaught, this will result in a warning being printed, that includes the file and line number of the offending code.</p>
</li>
<li>Global code is run in a reduced scope.<p>During startup, if a QML file includes an external JavaScript file with "global" code, it is executed in a scope that contains only the external file itself and the global object. That is, it will not have access to the QML objects and properties it <a href="qtqml-documents-scope.html">normally would</a>.</p>
<p>Global code that only accesses script local variables is permitted. This is an example of valid global code.</p>
<pre class="cpp">
var colors <span class="operator">=</span> <span class="operator">[</span> <span class="string">"red"</span><span class="operator">,</span> <span class="string">"blue"</span><span class="operator">,</span> <span class="string">"green"</span><span class="operator">,</span> <span class="string">"orange"</span><span class="operator">,</span> <span class="string">"purple"</span> <span class="operator">]</span>;
</pre>
<p>Global code that accesses QML objects will not run correctly.</p>
<pre class="cpp">
<span class="comment">// Invalid global code - the "rootObject" variable is undefined</span>
var initialPosition <span class="operator">=</span> { rootObject<span class="operator">.</span>x<span class="operator">,</span> rootObject<span class="operator">.</span>y }
</pre>
<p>This restriction exists as the QML environment is not yet fully established. To run code after the environment setup has completed, see <a href="qtqml-javascript-expressions.html#javascript-in-application-startup-code">JavaScript in Application Startup Code</a>.</p>
</li>
<li>The value of <code>this</code> is currently undefined in QML in the majority of contexts.<p>The <code>this</code> keyword is supported when binding properties from JavaScript. In all other situations, the value of <code>this</code> is undefined in QML.</p>
<p>To refer to a specific object, provide an <code>id</code>. For example:</p>
<pre class="qml">
<span class="type">Item</span> {
<span class="name">width</span>: <span class="number">200</span>; <span class="name">height</span>: <span class="number">100</span>
<span class="keyword">function</span> <span class="name">mouseAreaClicked</span>(<span class="name">area</span>) {
<span class="name">console</span>.<span class="name">log</span>(<span class="string">"Clicked in area at: "</span> <span class="operator">+</span> <span class="name">area</span>.<span class="name">x</span> <span class="operator">+</span> <span class="string">", "</span> <span class="operator">+</span> <span class="name">area</span>.<span class="name">y</span>);
}
<span class="comment">// This will not work because this is undefined</span>
<span class="type">MouseArea</span> {
<span class="name">height</span>: <span class="number">50</span>; <span class="name">width</span>: <span class="number">200</span>
<span class="name">onClicked</span>: <span class="name">mouseAreaClicked</span>(this)
}
<span class="comment">// This will pass area2 to the function</span>
<span class="type">MouseArea</span> {
<span class="name">id</span>: <span class="name">area2</span>
<span class="name">y</span>: <span class="number">50</span>; <span class="name">height</span>: <span class="number">50</span>; <span class="name">width</span>: <span class="number">200</span>
<span class="name">onClicked</span>: <span class="name">mouseAreaClicked</span>(<span class="name">area2</span>)
}
}
</pre>
</li>
</ul>
</div>
<!-- @@@qtqml-javascript-hostenvironment.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>
