<?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.12.6</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.12</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"><a href="qtqml-index.html">Qt 5.12.6 Reference Documentation</a></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 7th edition of the standard.</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 7th 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>
<p>In addition, QML also extends the behavior of the instanceof function to allow for type checking against QML types. This means that you may use it to verify that a variable is indeed the type you expect, for example:</p>
<pre class="qml">
</pre>
<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 undefined in QML in the majority of contexts.<p>The <code>this</code> keyword is supported when binding properties from JavaScript. In QML binding expressions, QML signal handlers, and QML declared functions, <code>this</code> refers to the scope object. 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">
</pre>
</li>
</ul>
</div>
<p><b>See also </b><a href="qtqml-documents-scope.html">Scope and Naming Resolution</a>.</p>
<!-- @@@qtqml-javascript-hostenvironment.html -->
</div>
</div>
</div>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2019 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>
distrib
>
Mageia
>
7
>
i586
>
media
>
core-updates
>
by-pkgid
>
6e2327ca1c896c6d674ae53117299f21
>
files
>
219
