<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.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" />
<!-- codingconventions.qdoc -->
<title>Qt 4.8: QML Coding Conventions</title>
<link rel="stylesheet" type="text/css" href="style/style.css" />
<script src="scripts/jquery.js" type="text/javascript"></script>
<script src="scripts/functions.js" type="text/javascript"></script>
<link rel="stylesheet" type="text/css" href="style/superfish.css" />
<link rel="stylesheet" type="text/css" href="style/narrow.css" />
<!--[if IE]>
<meta name="MSSmartTagsPreventParsing" content="true">
<meta http-equiv="imagetoolbar" content="no">
<![endif]-->
<!--[if lt IE 7]>
<link rel="stylesheet" type="text/css" href="style/style_ie6.css">
<![endif]-->
<!--[if IE 7]>
<link rel="stylesheet" type="text/css" href="style/style_ie7.css">
<![endif]-->
<!--[if IE 8]>
<link rel="stylesheet" type="text/css" href="style/style_ie8.css">
<![endif]-->
<script src="scripts/superfish.js" type="text/javascript"></script>
<script src="scripts/narrow.js" type="text/javascript"></script>
</head>
<body class="" onload="CheckEmptyAndLoadList();">
<div class="header" id="qtdocheader">
<div class="content">
<div id="nav-logo">
<a href="index.html">Home</a></div>
<a href="index.html" class="qtref"><span>Qt Reference Documentation</span></a>
<div id="narrowsearch"></div>
<div id="nav-topright">
<ul>
<li class="nav-topright-home"><a href="http://qt.digia.com/">Qt HOME</a></li>
<li class="nav-topright-dev"><a href="http://qt-project.org/">DEV</a></li>
<li class="nav-topright-doc nav-topright-doc-active"><a href="http://qt-project.org/doc/">
DOC</a></li>
<li class="nav-topright-blog"><a href="http://blog.qt.digia.com/">BLOG</a></li>
</ul>
</div>
<div id="shortCut">
<ul>
<li class="shortCut-topleft-inactive"><span><a href="index.html">Qt 4.8</a></span></li>
<li class="shortCut-topleft-active"><a href="http://qt-project.org/doc/">ALL VERSIONS </a></li>
</ul>
</div>
<ul class="sf-menu" id="narrowmenu">
<li><a href="#">API Lookup</a>
<ul>
<li><a href="classes.html">Class index</a></li>
<li><a href="functions.html">Function index</a></li>
<li><a href="modules.html">Modules</a></li>
<li><a href="namespaces.html">Namespaces</a></li>
<li><a href="qtglobal.html">Global Declarations</a></li>
<li><a href="qdeclarativeelements.html">QML elements</a></li>
</ul>
</li>
<li><a href="#">Qt Topics</a>
<ul>
<li><a href="qt-basic-concepts.html">Programming with Qt</a></li>
<li><a href="qtquick.html">Device UIs & Qt Quick</a></li>
<li><a href="qt-gui-concepts.html">UI Design with Qt</a></li>
<li><a href="supported-platforms.html">Supported Platforms</a></li>
<li><a href="technology-apis.html">Qt and Key Technologies</a></li>
<li><a href="best-practices.html">How-To's and Best Practices</a></li>
</ul>
</li>
<li><a href="#">Examples</a>
<ul>
<li><a href="all-examples.html">Examples</a></li>
<li><a href="tutorials.html">Tutorials</a></li>
<li><a href="demos.html">Demos</a></li>
<li><a href="qdeclarativeexamples.html">QML Examples</a></li>
</ul>
</li>
</ul>
</div>
</div>
<div class="wrapper">
<div class="hd">
<span></span>
</div>
<div class="bd group">
<div class="sidebar">
<div class="searchlabel">
Search index:</div>
<div class="search" id="sidebarsearch">
<form id="qtdocsearch" action="" onsubmit="return false;">
<fieldset>
<input type="text" name="searchstring" id="pageType" value="" />
<div id="resultdialog">
<a href="#" id="resultclose">Close</a>
<p id="resultlinks" class="all"><a href="#" id="showallresults">All</a> | <a href="#" id="showapiresults">API</a> | <a href="#" id="showarticleresults">Articles</a> | <a href="#" id="showexampleresults">Examples</a></p>
<p id="searchcount" class="all"><span id="resultcount"></span><span id="apicount"></span><span id="articlecount"></span><span id="examplecount"></span> results:</p>
<ul id="resultlist" class="all">
</ul>
</div>
</fieldset>
</form>
</div>
<div class="box first bottombar" id="lookup">
<h2 title="API Lookup"><span></span>
API Lookup</h2>
<div id="list001" class="list">
<ul id="ul001" >
<li class="defaultLink"><a href="classes.html">Class index</a></li>
<li class="defaultLink"><a href="functions.html">Function index</a></li>
<li class="defaultLink"><a href="modules.html">Modules</a></li>
<li class="defaultLink"><a href="namespaces.html">Namespaces</a></li>
<li class="defaultLink"><a href="qtglobal.html">Global Declarations</a></li>
<li class="defaultLink"><a href="qdeclarativeelements.html">QML elements</a></li>
</ul>
</div>
</div>
<div class="box bottombar" id="topics">
<h2 title="Qt Topics"><span></span>
Qt Topics</h2>
<div id="list002" class="list">
<ul id="ul002" >
<li class="defaultLink"><a href="qt-basic-concepts.html">Programming with Qt</a></li>
<li class="defaultLink"><a href="qtquick.html">Device UIs & Qt Quick</a></li>
<li class="defaultLink"><a href="qt-gui-concepts.html">UI Design with Qt</a></li>
<li class="defaultLink"><a href="supported-platforms.html">Supported Platforms</a></li>
<li class="defaultLink"><a href="technology-apis.html">Qt and Key Technologies</a></li>
<li class="defaultLink"><a href="best-practices.html">How-To's and Best Practices</a></li>
</ul>
</div>
</div>
<div class="box" id="examples">
<h2 title="Examples"><span></span>
Examples</h2>
<div id="list003" class="list">
<ul id="ul003">
<li class="defaultLink"><a href="all-examples.html">Examples</a></li>
<li class="defaultLink"><a href="tutorials.html">Tutorials</a></li>
<li class="defaultLink"><a href="demos.html">Demos</a></li>
<li class="defaultLink"><a href="qdeclarativeexamples.html">QML Examples</a></li>
</ul>
</div>
</div>
</div>
<div class="wrap">
<div class="toolbar">
<div class="breadcrumb toolblock">
<ul>
<li class="first"><a href="index.html">Home</a></li>
<!-- Breadcrumbs go here -->
<li>QML Coding Conventions</li>
</ul>
</div>
<div class="toolbuttons toolblock">
<ul>
<li id="smallA" class="t_button">A</li>
<li id="medA" class="t_button active">A</li>
<li id="bigA" class="t_button">A</li>
<li id="print" class="t_button"><a href="javascript:this.print();">
<span>Print</span></a></li>
</ul>
</div>
</div>
<div class="content mainContent">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#qml-objects">QML Objects</a></li>
<li class="level1"><a href="#grouped-properties">Grouped Properties</a></li>
<li class="level1"><a href="#private-properties">Private Properties</a></li>
<li class="level1"><a href="#lists">Lists</a></li>
<li class="level1"><a href="#javascript-code">JavaScript Code</a></li>
</ul>
</div>
<h1 class="title">QML Coding Conventions</h1>
<span class="subtitle"></span>
<!-- $$$qml-coding-conventions.html-description -->
<div class="descr"> <a name="details"></a>
<p>This document contains the QML coding conventions that we follow in our documentation and examples and recommend that others follow.</p>
<p>This page assumes that you are already familiar with the QML language. If you need an introduction to the language, please read <a href="qdeclarativeintroduction.html">the QML introduction</a> first.</p>
<a name="qml-objects"></a>
<h2>QML Objects</h2>
<p>Through our documentation and examples, QML objects are always structured in the following order:</p>
<ul>
<li>id</li>
<li>property declarations</li>
<li>signal declarations</li>
<li>JavaScript functions</li>
<li>object properties</li>
<li>child objects</li>
<li>states</li>
<li>transitions</li>
</ul>
<p>For better readability, we separate these different parts with an empty line.</p>
<p>For example, a hypothetical <i>photo</i> QML object would look like this:</p>
<pre class="qml"> <span class="type"><a href="qml-rectangle.html">Rectangle</a></span> {
<span class="name">id</span>: <span class="name">photo</span> <span class="comment">// id on the first line makes it easy to find an object</span>
property <span class="type">bool</span> <span class="name">thumbnail</span>: <span class="number">false</span> <span class="comment">// property declarations</span>
property <span class="type">alias</span> <span class="name">image</span>: <span class="name">photoImage</span>.<span class="name">source</span>
signal <span class="type">clicked</span> <span class="comment">// signal declarations</span>
<span class="keyword">function</span> <span class="name">doSomething</span>(<span class="name">x</span>) <span class="comment">// javascript functions</span>
{
<span class="keyword">return</span> <span class="name">x</span> <span class="operator">+</span> <span class="name">photoImage</span>.<span class="name">width</span>
}
<span class="name">color</span>: <span class="string">"gray"</span> <span class="comment">// object properties</span>
<span class="name">x</span>: <span class="number">20</span>; <span class="name">y</span>: <span class="number">20</span>; <span class="name">height</span>: <span class="number">150</span> <span class="comment">// try to group related properties together</span>
<span class="name">width</span>: { <span class="comment">// large bindings</span>
<span class="keyword">if</span>(<span class="name">photoImage</span>.<span class="name">width</span> <span class="operator">></span> <span class="number">200</span>){
<span class="name">photoImage</span>.<span class="name">width</span>;
}else{
<span class="number">200</span>;
}
}
<span class="type"><a href="qml-rectangle.html">Rectangle</a></span> { <span class="comment">// child objects</span>
<span class="name">id</span>: <span class="name">border</span>
<span class="name">anchors</span>.centerIn: <span class="name">parent</span>; <span class="name">color</span>: <span class="string">"white"</span>
<span class="type"><a href="qml-image.html">Image</a></span> { <span class="name">id</span>: <span class="name">photoImage</span>; <span class="name">anchors</span>.centerIn: <span class="name">parent</span> }
}
<span class="name">states</span>: <span class="name">State</span> { <span class="comment">// states</span>
<span class="name">name</span>: <span class="string">"selected"</span>
<span class="type"><a href="qml-propertychanges.html">PropertyChanges</a></span> { <span class="name">target</span>: <span class="name">border</span>; <span class="name">color</span>: <span class="string">"red"</span> }
}
<span class="name">transitions</span>: <span class="name">Transition</span> { <span class="comment">// transitions</span>
<span class="name">from</span>: <span class="string">""</span>; <span class="name">to</span>: <span class="string">"selected"</span>
<span class="type"><a href="qml-coloranimation.html">ColorAnimation</a></span> { <span class="name">target</span>: <span class="name">border</span>; <span class="name">duration</span>: <span class="number">200</span> }
}
}</pre>
<a name="grouped-properties"></a>
<h2>Grouped Properties</h2>
<p>If using multiple properties from a group of properties, we use the <i>group notation</i> rather than the <i>dot notation</i> to improve readability.</p>
<p>For example, this:</p>
<pre class="qml"> <span class="type"><a href="qml-rectangle.html">Rectangle</a></span> {
<span class="name">anchors</span>.left: <span class="name">parent</span>.<span class="name">left</span>; <span class="name">anchors</span>.top: <span class="name">parent</span>.<span class="name">top</span>; <span class="name">anchors</span>.right: <span class="name">parent</span>.<span class="name">right</span>; <span class="name">anchors</span>.leftMargin: <span class="number">20</span>
}
<span class="type"><a href="qml-text.html">Text</a></span> {
<span class="name">text</span>: <span class="string">"hello"</span>
<span class="name">font</span>.bold: <span class="number">true</span>; <span class="name">font</span>.italic: <span class="number">true</span>; <span class="name">font</span>.pixelSize: <span class="number">20</span>; <span class="name">font</span>.capitalization: <span class="name">Font</span>.<span class="name">AllUppercase</span>
}</pre>
<p>can be written like this:</p>
<pre class="qml"> <span class="type"><a href="qml-rectangle.html">Rectangle</a></span> {
<span class="type">anchors</span> { <span class="name">left</span>: <span class="name">parent</span>.<span class="name">left</span>; <span class="name">top</span>: <span class="name">parent</span>.<span class="name">top</span>; <span class="name">right</span>: <span class="name">parent</span>.<span class="name">right</span>; <span class="name">leftMargin</span>: <span class="number">20</span> }
}
<span class="type"><a href="qml-text.html">Text</a></span> {
<span class="name">text</span>: <span class="string">"hello"</span>
<span class="type">font</span> { <span class="name">bold</span>: <span class="number">true</span>; <span class="name">italic</span>: <span class="number">true</span>; <span class="name">pixelSize</span>: <span class="number">20</span>; <span class="name">capitalization</span>: <span class="name">Font</span>.<span class="name">AllUppercase</span> }
}</pre>
<a name="private-properties"></a>
<h2>Private Properties</h2>
<p>QML and JavaScript do not enforce private properties like C++. There is a need to hide these private properties, for example, when the properties are part of the implementation. To effectively gain private properties in a QML Item, the convention is to add a QtObject{} child to contain the properties. This shields them from being accessed outside the file in QML and JavaScript. As it involves the creation of another object, it is more expensive than just creating a property. To minimize the performance cost, try to group all private properties in one file into the same QtObject.</p>
<pre class="qml"> <span class="type"><a href="qml-item.html">Item</a></span> {
<span class="name">id</span>: <span class="name">component</span>
<span class="name">width</span>: <span class="number">40</span>; <span class="name">height</span>: <span class="number">50</span>
<span class="type">QtObject</span> {
<span class="name">id</span>: <span class="name">d</span>
property <span class="type">real</span> <span class="name">area</span>: <span class="name">width</span> <span class="operator">*</span> <span class="name">height</span> <span class="operator">*</span> <span class="number">0.5</span> <span class="comment">//not meant for outside use</span>
}
}</pre>
<a name="lists"></a>
<h2>Lists</h2>
<p>If a list contains only one element, we generally omit the square brackets.</p>
<p>For example, it is very common for a component to only have one state.</p>
<p>In this case, instead of:</p>
<pre class="qml"> <span class="name">states</span>: [
<span class="type"><a href="qml-state.html">State</a></span> {
<span class="name">name</span>: <span class="string">"open"</span>
<span class="type"><a href="qml-propertychanges.html">PropertyChanges</a></span> { <span class="name">target</span>: <span class="name">container</span>; <span class="name">width</span>: <span class="number">200</span> }
}
]</pre>
<p>we will write this:</p>
<pre class="qml"> <span class="name">states</span>: <span class="name">State</span> {
<span class="name">name</span>: <span class="string">"open"</span>
<span class="type"><a href="qml-propertychanges.html">PropertyChanges</a></span> { <span class="name">target</span>: <span class="name">container</span>; <span class="name">width</span>: <span class="number">200</span> }
}</pre>
<a name="javascript-code"></a>
<h2>JavaScript Code</h2>
<p>If the script is a single expression, we recommend writing it inline:</p>
<pre class="qml"> <span class="type"><a href="qml-rectangle.html">Rectangle</a></span> { <span class="name">color</span>: <span class="string">"blue"</span>; <span class="name">width</span>: <span class="name">parent</span>.<span class="name">width</span> <span class="operator">/</span> <span class="number">3</span> }</pre>
<p>If the script is only a couple of lines long, we generally use a block:</p>
<pre class="qml"> <span class="type"><a href="qml-rectangle.html">Rectangle</a></span> {
<span class="name">color</span>: <span class="string">"blue"</span>
<span class="name">width</span>: {
var <span class="name">w</span> = <span class="name">parent</span>.<span class="name">width</span> <span class="operator">/</span> <span class="number">3</span>
<span class="name">console</span>.<span class="name">debug</span>(<span class="name">w</span>)
<span class="keyword">return</span> <span class="name">w</span>
}
}</pre>
<p>If the script is more than a couple of lines long or can be used by different objects, we recommend creating a function and calling it like this:</p>
<pre class="qml"> <span class="keyword">function</span> <span class="name">calculateWidth</span>(<span class="name">object</span>)
{
var <span class="name">w</span> = <span class="name">object</span>.<span class="name">width</span> <span class="operator">/</span> <span class="number">3</span>
<span class="comment">// ...</span>
<span class="comment">// more javascript code</span>
<span class="comment">// ...</span>
<span class="name">console</span>.<span class="name">debug</span>(<span class="name">w</span>)
<span class="keyword">return</span> <span class="name">w</span>
}
<span class="type"><a href="qml-rectangle.html">Rectangle</a></span> { <span class="name">color</span>: <span class="string">"blue"</span>; <span class="name">width</span>: <span class="name">calculateWidth</span>(<span class="name">parent</span>) }</pre>
<p>For long scripts, we will put the functions in their own JavaScript file and import it like this:</p>
<pre class="qml"> import "myscript.js" as Script
<span class="type"><a href="qml-rectangle.html">Rectangle</a></span> { <span class="name">color</span>: <span class="string">"blue"</span>; <span class="name">width</span>: <span class="name">Script</span>.<span class="name">calculateWidth</span>(<span class="name">parent</span>) }</pre>
</div>
<!-- @@@qml-coding-conventions.html -->
</div>
</div>
</div>
<div class="ft">
<span></span>
</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.</p>
<br />
<p>
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.</p>
<p>
Documentation sources may be obtained from <a href="http://www.qt-project.org">
www.qt-project.org</a>.</p>
<br />
<p>
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. <a title="Privacy Policy"
href="http://en.gitorious.org/privacy_policy/">Privacy Policy</a></p>
</div>
<script src="scripts/functions.js" type="text/javascript"></script>
</body>
</html>
