/usr/share/qt5/doc/qtqml/qtqml-syntax-basics.html is in qtdeclarative5-doc-html 5.5.1-2ubuntu6.
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 | <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- basics.qdoc -->
<title>QML Syntax Basics | Qt QML 5.5</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.5</li>
<li><a href="qtqml-index.html">Qt QML</a></li>
<li>QML Syntax Basics</li>
<li id="buildversion">Qt 5.5.1 Reference Documentation</li>
</ul>
</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="#import-statements">Import Statements</a></li>
<li class="level1"><a href="#object-declarations">Object Declarations</a></li>
<li class="level2"><a href="#child-objects">Child Objects</a></li>
<li class="level1"><a href="#comments">Comments</a></li>
</ul>
</div>
<div class="sidebar-content" id="sidebar-content"></div></div>
<a name="qml-object-declarations"></a><h1 class="title">QML Syntax Basics</h1>
<span class="subtitle"></span>
<!-- $$$qtqml-syntax-basics.html-description -->
<div class="descr"> <a name="details"></a>
<p>QML is a multi-paradigm language that enables objects to be defined in terms of their attributes and how they relate and respond to changes in other objects. In contrast to purely imperative code, where changes in attributes and behavior are expressed through a series of statements that are processed step by step, QML's declarative syntax integrates attribute and behavioral changes directly into the definitions of individual objects. These attribute definitions can then include imperative code, in the case where complex custom application behavior is needed.</p>
<p>QML source code is generally loaded by the engine through QML <i>documents</i>, which are standalone documents of QML code. These can be used to define <a href="qtqml-typesystem-objecttypes.html">QML object types</a> that can then be reused throughout an application.</p>
<a name="import-statements"></a>
<h2 id="import-statements">Import Statements</h2>
<p>A QML document may have one or more imports at the top of the file. An import can be any one of:</p>
<ul>
<li>a versioned namespace into which types have been registered (e.g., by a plugin)</li>
<li>a relative directory which contains type-definitions as QML documents</li>
<li>a JavaScript file</li>
</ul>
<p>JavaScript file imports must be qualified when imported, so that the properties and methods they provide can be accessed.</p>
<p>The generic form of the various imports are as follows:</p>
<ul>
<li><code>import Namespace VersionMajor.VersionMinor</code></li>
<li><code>import Namespace VersionMajor.VersionMinor as SingletonTypeIdentifier</code></li>
<li><code>import "directory"</code></li>
<li><code>import "file.js" as ScriptIdentifier</code></li>
</ul>
<p>Examples:</p>
<ul>
<li><code>import QtQuick 2.0</code></li>
<li><code>import QtQuick.LocalStorage 2.0 as Database</code></li>
<li><code>import "../privateComponents"</code></li>
<li><code>import "somefile.js" as Script</code></li>
</ul>
<p>Please see the <a href="qtqml-syntax-imports.html">QML Syntax - Import Statements</a> documentation for in-depth information about QML imports.</p>
<a name="object-declarations"></a>
<h2 id="object-declarations">Object Declarations</h2>
<p>Syntactically, a block of QML code defines a tree of QML objects to be created. Objects are defined using <i>object declarations</i> that describe the type of object to be created as well as the attributes that are to be given to the object. Each object may also declare child objects using nested object declarations.</p>
<p>An object declaration consists of the name of its object type, followed by a set of curly braces. All attributes and child objects are then declared within these braces.</p>
<p>Here is a simple object declaration:</p>
<pre class="qml"><span class="type">Rectangle</span> {
<span class="name">width</span>: <span class="number">100</span>
<span class="name">height</span>: <span class="number">100</span>
<span class="name">color</span>: <span class="string">"red"</span>
}</pre>
<p>This declares an object of type Rectangle, followed by a set of curly braces that encompasses the attributes defined for that object. The Rectangle type is a type made available by the <code>QtQuick</code> module, and the attributes defined in this case are the values of the rectangle's <code>width</code>, <code>height</code> and <code>color</code> properties. (These are properties made available by the Rectangle type, as described in the Rectangle documentation.)</p>
<p>The above object can be loaded by the engine if it is part of a <a href="qtqml-documents-topic.html">QML document</a>. That is, if the source code is complemented with <i>import</i> statement that imports the <code>QtQuick</code> module (to make the Rectangle type available), as below:</p>
<pre class="qml">import QtQuick 2.0
<span class="type">Rectangle</span> {
<span class="name">width</span>: <span class="number">100</span>
<span class="name">height</span>: <span class="number">100</span>
<span class="name">color</span>: <span class="string">"red"</span>
}</pre>
<p>When placed into a <code>.qml</code> file and loaded by the QML engine, the above code creates a Rectangle object using the Rectangle type supplied by the <code>QtQuick</code> module:</p>
<p class="centerAlign"><img src="images/qtqml-syntax-basics-object-declaration.png" alt="" /></p><p><b>Note: </b>If an object definition only has a small number of properties, it can be written on a single line like this, with the properties separated by semi-colons:</p><pre class="qml"><span class="type">Rectangle</span> { <span class="name">width</span>: <span class="number">100</span>; <span class="name">height</span>: <span class="number">100</span>; <span class="name">color</span>: <span class="string">"red"</span> }</pre>
<p>Obviously, the Rectangle object declared in this example is very simple indeed, as it defines nothing more than a few property values. To create more useful objects, an object declaration may define many other types of attributes: these are discussed in the <a href="qtqml-syntax-objectattributes.html">QML Object Attributes</a> documentation. Additionally, an object declaration may define child objects, as discussed below.</p>
<a name="child-objects"></a>
<h3 >Child Objects</h3>
<p>Any object declaration can define child objects through nested object declarations. In this way, <b>any object declaration implicitly declares an object tree that may contain any number of child objects</b>.</p>
<p>For example, the Rectangle object declaration below includes a Gradient object declaration, which in turn contains two GradientStop declarations:</p>
<pre class="qml">import QtQuick 2.0
<span class="type">Rectangle</span> {
<span class="name">width</span>: <span class="number">100</span>
<span class="name">height</span>: <span class="number">100</span>
<span class="name">gradient</span>: <span class="name">Gradient</span> {
<span class="type">GradientStop</span> { <span class="name">position</span>: <span class="number">0.0</span>; <span class="name">color</span>: <span class="string">"yellow"</span> }
<span class="type">GradientStop</span> { <span class="name">position</span>: <span class="number">1.0</span>; <span class="name">color</span>: <span class="string">"green"</span> }
}
}</pre>
<p>When this code is loaded by the engine, it creates an object tree with a Rectangle object at the root; this object has a Gradient child object, which in turn has two GradientStop children.</p>
<p>Note, however, that this is a parent-child relationship in the context of the QML object tree, not in the context of the visual scene. The concept of a parent-child relationship in a visual scene is provided by the Item type from the <code>QtQuick</code> module, which is the base type for most QML types, as most QML objects are intended to be visually rendered. For example, Rectangle and Text are both Item-based types, and below, a Text object has been declared as a visual child of a Rectangle object:</p>
<pre class="qml">import QtQuick 2.0
<span class="type">Rectangle</span> {
<span class="name">width</span>: <span class="number">200</span>
<span class="name">height</span>: <span class="number">200</span>
<span class="name">color</span>: <span class="string">"red"</span>
<span class="type">Text</span> {
<span class="name">anchors</span>.centerIn: <span class="name">parent</span>
<span class="name">text</span>: <span class="string">"Hello, QML!"</span>
}
}</pre>
<p>When the Text object refers to its parent value in the above code, it is referring to its <i>visual parent</i>, not the parent in the object tree. In this case, they are one and the same: the Rectangle object is the parent of the Text object in both the context of the QML object tree as well as the context of the visual scene. However, while the parent property can be modified to change the visual parent, the parent of an object in the context of the object tree cannot be changed from QML.</p>
<p>(Additionally, notice that the Text object has been declared without assigning it to a property of the Rectangle, unlike the earlier example which assigned a Gradient object to the rectangle's <code>gradient</code> property. This is because the children property of Item has been set as the type's <a href="qtqml-syntax-objectattributes.html#default-properties">default property</a> to enable this more convenient syntax.)</p>
<p>See the visual parent documentation for more information on the concept of visual parenting with the Item type.</p>
<a name="comments"></a>
<h2 id="comments">Comments</h2>
<p>The syntax for commenting in QML is similar to that of JavaScript:</p>
<ul>
<li>Single line comments start with // and finish at the end of the line.</li>
<li>Multiline comments start with /* and finish with */</li>
</ul>
<pre class="qml"><span class="type">Text</span> {
<span class="name">text</span>: <span class="string">"Hello world!"</span> <span class="comment">//a basic greeting</span>
<span class="comment">/*
We want this text to stand out from the rest so
we give it a large size and different font.
*/</span>
<span class="name">font</span>.family: <span class="string">"Helvetica"</span>
<span class="name">font</span>.pointSize: <span class="number">24</span>
}</pre>
<p>Comments are ignored by the engine when processing QML code. They are useful for explaining what a section of code is doing, whether for reference at a later date or for explaining the implementation to others.</p>
<p>Comments can also be used to prevent the execution of code, which is sometimes useful for tracking down problems.</p>
<pre class="qml"> <span class="type">Text</span> {
<span class="name">text</span>: <span class="string">"Hello world!"</span>
<span class="comment">//opacity: 0.5</span>
}</pre>
<p>In the above example, the Text object will have normal opacity, since the line opacity: 0.5 has been turned into a comment.</p>
</div>
<!-- @@@qtqml-syntax-basics.html -->
</div>
</div>
</div>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2015 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>
|