/usr/share/qt5/doc/qtqml/qtqml-javascript-expressions.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 | <?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" />
<!-- expressions.qdoc -->
<title>JavaScript Expressions in QML Documents | 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>JavaScript Expressions in QML Documents</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="#javascript-expressions-in-qml-objects">JavaScript Expressions in QML Objects</a></li>
<li class="level2"><a href="#property-bindings">Property Bindings</a></li>
<li class="level2"><a href="#signal-handlers">Signal Handlers</a></li>
<li class="level2"><a href="#javascript-expressions-in-functions">JavaScript Expressions in Functions</a></li>
<li class="level3"><a href="#custom-methods">Custom Methods</a></li>
<li class="level3"><a href="#functions-in-imported-javascript-files">Functions in Imported JavaScript Files</a></li>
<li class="level3"><a href="#connecting-signals-to-javascript-functions">Connecting Signals to JavaScript Functions</a></li>
<li class="level1"><a href="#running-javascript-at-startup">Running JavaScript at Startup</a></li>
</ul>
</div>
<h1 class="title">JavaScript Expressions in QML Documents</h1>
<span class="subtitle"></span>
<!-- $$$qtqml-javascript-expressions.html-description -->
<div class="descr"> <a name="details"></a>
<p>The <a href="qtqml-javascript-hostenvironment.html">JavaScript Host Environment</a> provided by QML can run valid standard JavaScript constructs such as conditional operators, arrays, variable setting, loops. In addition to the standard JavaScript properties, the <a href="qtqml-javascript-qmlglobalobject.html">QML Global Object</a> includes a number of helper methods that simplify building UIs and interacting with the QML environment.</p>
<p>The JavaScript environment provided by QML is stricter than that in a web browser. For example, in QML you cannot add, or modify, members of the JavaScript global object. In regular JavaScript, it is possible to do this accidentally by using a variable without declaring it. In QML this will throw an exception, so all local variables should be explicitly declared. See <a href="qtqml-javascript-hostenvironment.html#javascript-environment-restrictions">JavaScript Environment Restrictions</a> for a complete description of the restrictions on JavaScript code executed from QML.</p>
<p>There are various ways in which JavaScript expressions may be defined and used in QML, including property bindings, signal handlers, custom methods and JavaScript imports.</p>
<a name="javascript-expressions-in-qml-objects"></a>
<h2>JavaScript Expressions in QML Objects</h2>
<p>QML <a href="qtqml-typesystem-objecttypes.html">object types</a> defined in <a href="qtqml-documents-topic.html">QML documents</a> can make use of JavaScript expressions which implement program logic. There are four ways that JavaScript can be used in a QML document:</p>
<ul>
<li><a href="qtqml-syntax-objectattributes.html#property-attributes">properties</a> can be assigned <a href="qtqml-syntax-propertybinding.html">bindings</a> which are defined with JavaScript expressions, and which are automatically evaluated by the <a href="qqmlengine.html">QML engine</a> when any properties accessed in the binding change, in order to ensure always-up-to-date property values. Binding expressions can also perform function evaluation as an explicit side effect</li>
<li><a href="qtqml-syntax-objectattributes.html#signal-attributes">signal handlers</a> can be defined which are automatically evaluated when the object emits the associated signal</li>
<li><a href="qtqml-syntax-objectattributes.html#method-attributes">custom methods</a> can be defined in QML files as JavaScript functions</li>
<li>JavaScript files providing functions and variables can be <a href="qtqml-javascript-imports.html">imported</a> in a QML document</li>
</ul>
<a name="property-bindings"></a>
<h3>Property Bindings</h3>
<p>During startup, the QML engine will set up and initialize the property bindings. The JavaScript conditional operator is a valid property binding.</p>
<pre class="qml">import QtQuick 2.0
<span class="type">Rectangle</span> {
<span class="name">id</span>: <span class="name">colorbutton</span>
<span class="name">width</span>: <span class="number">200</span>; <span class="name">height</span>: <span class="number">80</span>;
<span class="name">color</span>: <span class="name">mousearea</span>.<span class="name">pressed</span> ? <span class="string">"steelblue"</span> : <span class="string">"lightsteelblue"</span>
<span class="type">MouseArea</span> {
<span class="name">id</span>: <span class="name">mousearea</span>
<span class="name">anchors</span>.fill: <span class="name">parent</span>
}
}</pre>
<p>In fact, any JavaScript expression (no matter how complex) may be used in a property binding definition, as long as the result of the expression is a value whose type can be assigned to the property.</p>
<p>There are two ways to define a property binding: the first (and most common) is, as previously shown, in a <a href="qtqml-syntax-objectattributes.html#value-assignment-on-initialization">property initialization</a>. The second (and much rarer) way is to assign the property a function returned from the <a href="qml-qtqml-qt.html#binding-method">Qt.binding()</a> function, from within imperative JavaScript code, as shown below:</p>
<pre class="qml">import QtQuick 2.0
<span class="type">Rectangle</span> {
<span class="name">id</span>: <span class="name">colorbutton</span>
<span class="name">width</span>: <span class="number">200</span>; <span class="name">height</span>: <span class="number">80</span>;
<span class="name">color</span>: <span class="string">"red"</span>
<span class="type">MouseArea</span> {
<span class="name">id</span>: <span class="name">mousearea</span>
<span class="name">anchors</span>.fill: <span class="name">parent</span>
}
<span class="name">Component</span>.onCompleted: {
<span class="name">color</span> <span class="operator">=</span> <span class="name">Qt</span>.<span class="name">binding</span>(<span class="keyword">function</span>() { <span class="keyword">return</span> <span class="name">mousearea</span>.<span class="name">pressed</span> ? <span class="string">"steelblue"</span> : <span class="string">"lightsteelblue"</span> });
}
}</pre>
<p>See the <a href="qtqml-syntax-propertybinding.html">property bindings</a> documentation for more information about how to define property bindings, and see the documentation about <a href="qtqml-syntax-propertybinding.html#qml-javascript-assignment">Property Assignment versus Property Binding</a> for information about how bindings differ from value assignments.</p>
<a name="signal-handlers"></a>
<h3>Signal Handlers</h3>
<p>QML object types can emit signals in reaction to certain events occurring. Those signals can be handled by signal handler functions, which can be defined by clients to implement custom program logic.</p>
<p>Suppose that a button represented by a Rectangle type has a MouseArea and a Text label. The MouseArea will emit its "pressed" signal when the user presses the defined interactive area, which will automatically trigger the onPressed handler, which can be defined by clients. The QML engine will execute the JavaScript expressions defined in the onPressed and onReleased handlers, as required. Typically, a signal handler is bound to JavaScript expressions to initiate other events or to simply assign property values.</p>
<pre class="qml">import QtQuick 2.0
<span class="type">Rectangle</span> {
<span class="name">id</span>: <span class="name">button</span>
<span class="name">width</span>: <span class="number">200</span>; <span class="name">height</span>: <span class="number">80</span>; <span class="name">color</span>: <span class="string">"lightsteelblue"</span>
<span class="type">MouseArea</span> {
<span class="name">id</span>: <span class="name">mousearea</span>
<span class="name">anchors</span>.fill: <span class="name">parent</span>
<span class="name">onPressed</span>: {
<span class="comment">// arbitrary JavaScript expression</span>
<span class="name">label</span>.<span class="name">text</span> <span class="operator">=</span> <span class="string">"I am Pressed!"</span>
}
<span class="name">onReleased</span>: {
<span class="comment">// arbitrary JavaScript expression</span>
<span class="name">label</span>.<span class="name">text</span> <span class="operator">=</span> <span class="string">"Click Me!"</span>
}
}
<span class="type">Text</span> {
<span class="name">id</span>: <span class="name">label</span>
<span class="name">anchors</span>.centerIn: <span class="name">parent</span>
<span class="name">text</span>: <span class="string">"Press Me!"</span>
}
}</pre>
<p>Please see the <a href="qtqml-syntax-signals.html">Signal and Handler Event System</a> documentation for in-depth discussion of signals and signal handlers, and see the <a href="qtqml-syntax-objectattributes.html">QML Object Attributes</a> documentation for in-depth discussion of how to define the implementation of signal handlers in QML with JavaScript.</p>
<a name="javascript-expressions-in-functions"></a>
<h3>JavaScript Expressions in Functions</h3>
<p>Program logic can also be defined in JavaScript functions. These functions can be defined inline in QML documents (as custom methods) or externally in imported JavaScript files.</p>
<a name="custom-methods"></a>
<h4>Custom Methods</h4>
<p>Custom methods can be defined in QML documents and may be called from signal handlers, property bindings, or functions in other QML objects. Methods defined in this way are often referred to as "inline JavaScript functions" as their implementation is included in the QML object type definition (QML document), as opposed to an external JavaScript file.</p>
<p>An example of an inline custom method is as follows:</p>
<pre class="qml">import QtQuick 2.0
<span class="type">Item</span> {
<span class="keyword">function</span> <span class="name">factorial</span>(<span class="name">a</span>) {
<span class="name">a</span> <span class="operator">=</span> <span class="name">parseInt</span>(<span class="name">a</span>);
<span class="keyword">if</span> (<span class="name">a</span> <span class="operator"><=</span> <span class="number">0</span>)
<span class="keyword">return</span> <span class="number">1</span>;
<span class="keyword">else</span>
<span class="keyword">return</span> <span class="name">a</span> <span class="operator">*</span> <span class="name">factorial</span>(<span class="name">a</span> <span class="operator">-</span> <span class="number">1</span>);
}
<span class="type">MouseArea</span> {
<span class="name">anchors</span>.fill: <span class="name">parent</span>
<span class="name">onClicked</span>: <span class="name">console</span>.<span class="name">log</span>(<span class="name">factorial</span>(<span class="number">10</span>))
}
}</pre>
<p>The factorial function will run whenever the MouseArea detects a clicked signal.</p>
<p>Importantly, custom methods defined inline in a QML document are exposed to other objects, and therefore inline functions on the root object in a QML component can be invoked by callers outside the component. If this is not desired, the method can be added to a non-root object or, preferably, written in an external JavaScript file.</p>
<p>See the <a href="qtqml-syntax-objectattributes.html">QML Object Attributes</a> documentation for in-depth discussion of how to define custom methods in QML with JavaScript code implementations.</p>
<a name="functions-in-imported-javascript-files"></a>
<h4>Functions in Imported JavaScript Files</h4>
<p>Non-trivial program logic is best separated into external JavaScript files. These files can be imported into QML files using an <tt>import</tt> statement, in the same way that <a href="qtqml-modules-topic.html">modules</a> are imported.</p>
<p>For example, the <tt>factorial()</tt> method in the above example could be moved into an external file named <tt>factorial.js</tt>, and accessed like this:</p>
<pre class="qml">import "factorial.js" as MathFunctions
<span class="type">Item</span> {
<span class="type">MouseArea</span> {
<span class="name">anchors</span>.fill: <span class="name">parent</span>
<span class="name">onClicked</span>: <span class="name">console</span>.<span class="name">log</span>(<span class="name">MathFunctions</span>.<span class="name">factorial</span>(<span class="number">10</span>))
}
}</pre>
<p>For more information about loading external JavaScript files into QML, read the section about <a href="qtqml-javascript-imports.html">Importing JavaScript Resources in QML</a>.</p>
<a name="connecting-signals-to-javascript-functions"></a>
<h4>Connecting Signals to JavaScript Functions</h4>
<p>QML object types which emit signals also provide default signal handlers for their signals, as described in a previous section. Sometimes, however, a client will want to cause a signal emitted from one object to trigger a function defined in another object; and in that case, a signal connection is often preferable.</p>
<p>A signal emitted by a QML object may be connected to a JavaScript function by calling the signal's <tt>connect()</tt> method and passing the JavaScript function as an argument. For example, the following code connects the MouseArea <tt>clicked</tt> signal to the <tt>jsFunction()</tt> in <tt>script.js</tt>:</p>
<table class="generic">
<tr valign="top" class="odd"><td ><pre class="qml">import QtQuick 2.0
import "script.js" as MyScript
<span class="type">Item</span> {
<span class="name">id</span>: <span class="name">item</span>
<span class="name">width</span>: <span class="number">200</span>; <span class="name">height</span>: <span class="number">200</span>
<span class="type">MouseArea</span> {
<span class="name">id</span>: <span class="name">mouseArea</span>
<span class="name">anchors</span>.fill: <span class="name">parent</span>
}
<span class="name">Component</span>.onCompleted: {
<span class="name">mouseArea</span>.<span class="name">clicked</span>.<span class="name">connect</span>(<span class="name">MyScript</span>.<span class="name">jsFunction</span>)
}
}</pre>
</td><td ><pre class="js"><span class="comment">// script.js</span>
<span class="keyword">function</span> <span class="name">jsFunction</span>() {
<span class="name">console</span>.<span class="name">log</span>(<span class="string">"Called JavaScript function!"</span>)
}</pre>
</td></tr>
</table>
<p>The <tt>jsFunction()</tt> will now be called whenever MouseArea's <tt>clicked</tt> signal is emitted.</p>
<p>See <a href="qtqml-syntax-signals.html">Connecting Signals to Methods and Signals</a> for more information.</p>
<a name="running-javascript-at-startup"></a>
<h2>Running JavaScript at Startup</h2>
<p>It is occasionally necessary to run some imperative code at application (or component instance) startup. While it is tempting to just include the startup script as <i>global code</i> in an external script file, this can have severe limitations as the QML environment may not have been fully established. For example, some objects might not have been created or some <a href="qtqml-syntax-propertybinding.html">property bindings</a> may not have been run. <a href="qtqml-javascript-hostenvironment.html#javascript-environment-restrictions">JavaScript Environment Restrictions</a> covers the exact limitations of global script code.</p>
<p>Every QML object has an <i>attached</i> <a href="qml-qtqml-component.html">Component</a> property that references the component within which the object was instantiated. Every <a href="qml-qtqml-component.html">Component</a> will emit a <tt>completed</tt> signal, and thus every object can define an implementation for the <tt>onCompleted()</tt> handler which can be used to trigger the execution of script code at startup after the QML environment has been completely established. For example:</p>
<pre class="qml">import QtQuick 2.0
<span class="type">Rectangle</span> {
<span class="keyword">function</span> <span class="name">startupFunction</span>() {
<span class="comment">// ... startup code</span>
}
<span class="name">Component</span>.onCompleted: <span class="name">startupFunction</span>();
}</pre>
<p>Any object in a QML file - including nested objects and nested QML component instances - can use this attached property. If there is more than one <tt>onCompleted()</tt> handler to execute at startup, they are run sequentially in an undefined order.</p>
<p>Likewise, the <a href="qml-qtqml-component.html#onDestruction-signal">Component::onDestruction</a> handler definitions are triggered on component destruction.</p>
</div>
<!-- @@@qtqml-javascript-expressions.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>
|