<?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" />
<!-- qtprogrammers.qdoc -->
<title>Qt 4.8: QML for Qt Programmers</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 for Qt Programmers</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="#familiar-concepts">Familiar Concepts</a></li>
<li class="level1"><a href="#qml-items-compared-with-qwidgets">QML Items compared with QWidgets</a></li>
<li class="level2"><a href="#simple-widgets">Simple Widgets</a></li>
<li class="level2"><a href="#parent-widgets">Parent Widgets</a></li>
<li class="level2"><a href="#compound-widgets">Compound Widgets</a></li>
<li class="level1"><a href="#qml-items-compared-with-qgraphicswidgets">QML Items Compared With QGraphicsWidgets</a></li>
</ul>
</div>
<h1 class="title">QML for Qt Programmers</h1>
<span class="subtitle"></span>
<!-- $$$qtprogrammers.html-description -->
<div class="descr"> <a name="details"></a>
<a name="qtprogrammers"></a><p>While QML does not require Qt knowledge to use, if you <i>are</i> already familiar with Qt, much of your knowledge is directly relevant to learning and using QML. Of course, an application with a UI defined in QML also uses Qt for all the non-UI logic.</p>
<a name="familiar-concepts"></a>
<h2>Familiar Concepts</h2>
<p>QML provides direct access to the following concepts from Qt:</p>
<ul>
<li><a href="qaction.html">QAction</a> - the <a href="qdeclarativebasictypes.html">action</a> type</li>
<li><a href="qobject.html">QObject</a> signals and slots - available as functions to call in JavaScript</li>
<li><a href="qobject.html">QObject</a> properties - available as variables in JavaScript</li>
<li><a href="qwidget.html">QWidget</a> - <a href="qdeclarativeview.html">QDeclarativeView</a> is a QML-displaying widget</li>
<li>Qt models - used directly in data binding (<a href="qabstractitemmodel.html">QAbstractItemModel</a>)</li>
</ul>
<p>Qt knowledge is <i>required</i> for <a href="qml-extending.html">Extending QML Functionalities using C++</a>, and also for <a href="qml-integration.html">Integrating QML Code with existing Qt UI code</a>.</p>
<a name="qml-items-compared-with-qwidgets"></a>
<h2>QML Items compared with QWidgets</h2>
<p>QML Items are very similar to QWidgets: they define the look and feel of the user interface. (Note that while QWidgets haven't traditionally been used to define the look and feel of view delegates, QML Items can be used for this as well.)</p>
<p>There are three structurally different types of <a href="qwidget.html">QWidget</a>:</p>
<ul>
<li>Simple widgets that are not used as parents (<a href="qlabel.html">QLabel</a>, <a href="qcheckbox.html">QCheckBox</a>, <a href="qtoolbutton.html">QToolButton</a>, etc.)</li>
<li>Parent widgets that are normally used as parents to other widgets (<a href="qgroupbox.html">QGroupBox</a>, <a href="qstackedwidget.html">QStackedWidget</a>, <a href="qtabwidget.html">QTabWidget</a>, etc.)</li>
<li>Compound widgets that are internally composed of child widgets (<a href="qcombobox.html">QComboBox</a>, <a href="qspinbox.html">QSpinBox</a>, <a href="qfiledialog.html">QFileDialog</a>, <a href="qtabwidget.html">QTabWidget</a>, etc.)</li>
</ul>
<p>QML Items also serve these purposes. Each is considered separately below.</p>
<a name="simple-widgets"></a>
<h3>Simple Widgets</h3>
<p>The most important rule to remember while implementing a new <a href="qdeclarativeitem.html">QDeclarativeItem</a> in C++ is that it should not contain any look and feel policies - leave that to the QML usage of the item.</p>
<p>As an example, imagine you wanted a reusable Button item. If you therefore decided to write a <a href="qdeclarativeitem.html">QDeclarativeItem</a> subclass to implement a button, just as <a href="qtoolbutton.html">QToolButton</a> subclasses <a href="qwidget.html">QWidget</a> for this purpose, following the rule above, your <tt>QDeclarativeButton</tt> would not have any appearance - just the notions of enabled, triggering, etc.</p>
<p>But there is already an object in Qt that does this: <a href="qaction.html">QAction</a>.</p>
<p><a href="qaction.html">QAction</a> is the UI-agnostic essence of <a href="qpushbutton.html">QPushButton</a>, <a href="qcheckbox.html">QCheckBox</a>, <a href="qmenu.html">QMenu</a> items, <a href="qtoolbutton.html">QToolButton</a>, and other visual widgets that are commonly bound to a <a href="qaction.html">QAction</a>.</p>
<p>So, the job of implementing a checkbox abstraction for QML is already done - it's <a href="qaction.html">QAction</a>. The look and feel of an action - the appearance of the button, the transition between states, and exactly how it respond to mouse, key, or touch input, should all be left for definition in QML.</p>
<p>It is illustrative to note that QDeclarativeTextEdit is built upon QTextControl, QDeclarativeWebView is built upon <a href="qwebpage.html">QWebPage</a>, and <a href="qml-listview.html">ListView</a> uses <a href="qabstractitemmodel.html">QAbstractItemModel</a>, just as <a href="qtextedit.html">QTextEdit</a>, <a href="qwebview.html">QWebView</a>, and <a href="qlistview.html">QListView</a> are built upon those same UI-agnostic components.</p>
<p>The encapsulation of the look and feel that QWidgets gives is important, and for this the QML concept of <a href="qdeclarativedocuments.html">components</a> serves the same purpose. If you are building a complete suite of applications which should have a consistent look and feel, you should build a set of reusable components with the look and feel you desire.</p>
<p>So, to implement your reusable button, you would simply build a QML component.</p>
<a name="parent-widgets"></a>
<h3>Parent Widgets</h3>
<p>Parent widgets each provide a generic way to interface to one or more arbitrary other widgets. A <a href="qtabwidget.html">QTabWidget</a> provides an interface to multiple "pages", one of which is visible at any time, and a mechanism for selecting among them (the <a href="qtabbar.html">QTabBar</a>). A <a href="qscrollarea.html">QScrollArea</a> provides scrollbars around a widget that is otherwise too large to fit in available space.</p>
<p>Nearly all such components can be created directly in QML. Only a few cases which require very particular event handling, such as Flickable, require C++ implementations.</p>
<p>As an example, imagine you decided to make a generic tab widget item to be used through your application suite wherever information is in such quantity that it needs to be divided up into pages.</p>
<p>A significant difference in the parenting concept with QML compare to QWidgets is that while child items are positioned relative to their parents, there is no requirement that they be wholly contained ("clipped") to the parent (although the clipped property of the child Item does allow this where it is needed). This difference has rather far-reaching consequences, for example:</p>
<ul>
<li>A shadow or highlight around a widget could be a child of that widget.</li>
<li>Particle effects can flow outside the object where they originate.</li>
<li>Transitioning animations can "hide" items by visibly moving them beyond the screen bounds.</li>
</ul>
<a name="compound-widgets"></a>
<h3>Compound Widgets</h3>
<p>Some widgets provide functionality by composing other widgets as an "implementation detail", providing a higher level API to the composition. <a href="qspinbox.html">QSpinBox</a> for example is a line edit and some buttons to increase/decrease the edited value. <a href="qfiledialog.html">QFileDialog</a> uses a whole host of widgets to give the user a way of finding and selecting a file name.</p>
<p>When developing reusable QML Items, you may choose to do the same: build an item composed of other items you have already defined.</p>
<p>The only caveat when doing this is to consider the possible animations and transitions that users of the compound item might wish to employ. For example, a spinbox might need to smoothly transition from an arbitrary Text item, or characters within a Text item, so your spinbox item would need to be sufficiently flexible to allow such animation.</p>
<a name="qml-items-compared-with-qgraphicswidgets"></a>
<h2>QML Items Compared With QGraphicsWidgets</h2>
<p>The main difference between QML items and QGraphicsWidgets is how they are intended to be used. The technical implementation details are much the same, but in practice they are different because QML items are made for declarative and compositional use, and QGraphicsWidgets are made for imperative and more integrated use. Both QML items and QGraphicsWidgets inherit from <a href="qgraphicsobject.html">QGraphicsObject</a>, and can co-exist. The differences are in the layouting system and the interfacing with other components. Note that, as QGraphicsWidgets tend more to be all-in-one packages, the equivalent of a <a href="qgraphicswidget.html">QGraphicsWidget</a> may be many QML items composed across several QML files, but it can still be loaded and used as a single <a href="qgraphicsobject.html">QGraphicsObject</a> from C++.</p>
<p>QGraphicsWidgets are usually designed to be laid out with QGraphicsLayouts. QML does not use QGraphicsLayouts, as the Qt layouts do not mix well with animated and fluid UIs, so the geometry interface is one of the main differences. When writing QML elements, you allow the designers to place their bounding rectangle using absolute geometry, bindings or anchors (all setup for you when you inherit <a href="qdeclarativeitem.html">QDeclarativeItem</a>) and you do not use layouts or size hints. If size hints are appropriate, then place them in the QML documentation so that the designers know how to use the item best, but still have complete control over the look and feel.</p>
<p>The other main difference is that QGraphicsWidgets tend to follow the widget model, in that they are a self-contained bundle of UI and logic. In contrast, QML primitives are usually a single purpose item that does not fulfill a use case on its own, but is composed into the equivalent of the widget inside the QML file. So when writing QML Items, try to avoid doing UI logic or composing visual elements inside the items. Try instead to write more general purpose primitives, so that the look and feel (which involves the UI logic) can be written in QML.</p>
<p>Both differences are caused by the different method of interaction. <a href="qgraphicswidget.html">QGraphicsWidget</a> is a <a href="qgraphicsobject.html">QGraphicsObject</a> subclass which makes fluid UI development from C++ easier, and <a href="qdeclarativeitem.html">QDeclarativeItem</a> is a <a href="qgraphicsobject.html">QGraphicsObject</a> subclass which makes fluid UI development from QML easier. The difference therefore is primarily one of the interface exposed, and the design of the items that come with it (the Declarative primitives for QML and the nothing for <a href="qgraphicswidget.html">QGraphicsWidget</a>, because you need to write your own UI logic into the subclass).</p>
<p>If you wish to use both QML and C++ to write the UI, for example to ease the transition period, it is recommended to use <a href="qdeclarativeitem.html">QDeclarativeItem</a> subclasses (although you can use QGraphicsWidgets as well). To allow for easier use from C++ make the root item of each C++ component a <a href="qml-layoutitem.html">LayoutItem</a>, and load individual 'widgets' of QML (possibly comprised of multiple files, and containing a self-contained bundle of UI and logic) into your scene to replace individual QGraphicsWidgets one at a time.</p>
</div>
<!-- @@@qtprogrammers.html -->
</div>
</div>
</div>
<div class="ft">
<span></span>
</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.</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>
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. <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>
