<?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" />
<!-- qdeclarativeparticles.cpp -->
<title>Qt 4.8: QML Particles Element</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><a href="qdeclarativeelements.html">QML Elements</a></li>
<li>QML Particles Element</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">
<p class="naviNextPrevious headerNavi">
</p><p/>
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#properties">Properties</a></li>
<li class="level1"><a href="#methods">Methods</a></li>
<li class="level1"><a href="#details">Detailed Description</a></li>
</ul>
</div>
<h1 class="title">QML Particles Element</h1>
<span class="subtitle"></span>
<!-- $$$Particles-brief -->
<p>The Particles object generates and moves particles. <a href="#details">More...</a></p>
<!-- @@@Particles -->
<p>Inherits <a href="qml-item.html">Item</a></p>
<p>This element was introduced in Qt 4.7.</p>
<ul>
<li><a href="qml-particles-members.html">List of all members, including inherited members</a></li>
</ul>
<a name="properties"></a>
<h2>Properties</h2>
<ul>
<li class="fn"><b><b><a href="qml-particles.html#angle-prop">angle</a></b></b> : real</li>
<li class="fn"><b><b><a href="qml-particles.html#angleDeviation-prop">angleDeviation</a></b></b> : real</li>
<li class="fn"><b><b><a href="qml-particles.html#count-prop">count</a></b></b> : int</li>
<li class="fn"><b><b><a href="qml-particles.html#emissionRate-prop">emissionRate</a></b></b> : int</li>
<li class="fn"><b><b><a href="qml-particles.html#emissionVariance-prop">emissionVariance</a></b></b> : real</li>
<li class="fn"><b><b><a href="qml-particles.html#fadeInDuration-prop">fadeInDuration</a></b></b> : int</li>
<li class="fn"><b><b><a href="qml-particles.html#fadeOutDuration-prop">fadeOutDuration</a></b></b> : int</li>
<li class="fn"><b><b><a href="qml-particles.html#lifeSpan-prop">lifeSpan</a></b></b> : int</li>
<li class="fn"><b><b><a href="qml-particles.html#lifeSpanDeviation-prop">lifeSpanDeviation</a></b></b> : int</li>
<li class="fn"><b><b><a href="qml-particles.html#motion-prop">motion</a></b></b> : ParticleMotion</li>
<li class="fn"><b><b><a href="qml-particles.html#source-prop">source</a></b></b> : string</li>
<li class="fn"><b><b><a href="qml-particles.html#velocity-prop">velocity</a></b></b> : real</li>
<li class="fn"><b><b><a href="qml-particles.html#velocityDeviation-prop">velocityDeviation</a></b></b> : real</li>
</ul>
<a name="methods"></a>
<h2>Methods</h2>
<ul>
<li class="fn"><b><b><a href="qml-particles.html#burst-method">burst</a></b></b></li>
</ul>
<!-- $$$Particles-description -->
<a name="details"></a>
<h2>Detailed Description</h2>
<p>Particles are available in the <b>Qt.labs.particles 1.0</b> module. <i>Elements in the Qt.labs module are not guaranteed to remain compatible in future versions.</i></p>
<p>This element provides preliminary support for particles in QML, and may be heavily changed or removed in later versions.</p>
<p>The particles created by this object cannot be dealt with directly, they can only be controlled through the parameters of the Particles object. The particles are all the same pixmap, specified by the user.</p>
<p>The particles are painted relative to the parent of the Particles object. Moving the Particles object will not move the particles already emitted.</p>
<p>The below example creates two differently behaving particle sources. The top one has particles falling from the top like snow, the lower one has particles expelled up like a fountain.</p>
<pre class="qml"> import QtQuick 1.0
import Qt.labs.particles 1.0
<span class="type"><a href="qml-rectangle.html">Rectangle</a></span> {
<span class="name">width</span>: <span class="number">240</span>
<span class="name">height</span>: <span class="number">320</span>
<span class="name">color</span>: <span class="string">"black"</span>
<span class="type">Particles</span> {
<span class="name">y</span>: <span class="number">0</span>
<span class="name">width</span>: <span class="name">parent</span>.<span class="name">width</span>
<span class="name">height</span>: <span class="number">30</span>
<span class="name">source</span>: <span class="string">"star.png"</span>
<span class="name">lifeSpan</span>: <span class="number">5000</span>
<span class="name">count</span>: <span class="number">50</span>
<span class="name">angle</span>: <span class="number">70</span>
<span class="name">angleDeviation</span>: <span class="number">36</span>
<span class="name">velocity</span>: <span class="number">30</span>
<span class="name">velocityDeviation</span>: <span class="number">10</span>
<span class="type"><a href="qml-particlemotionwander.html">ParticleMotionWander</a></span> {
<span class="name">xvariance</span>: <span class="number">30</span>
<span class="name">pace</span>: <span class="number">100</span>
}
}
<span class="type">Particles</span> {
<span class="name">y</span>: <span class="number">300</span>
<span class="name">x</span>: <span class="number">120</span>
<span class="name">width</span>: <span class="number">1</span>
<span class="name">height</span>: <span class="number">1</span>
<span class="name">source</span>: <span class="string">"star.png"</span>
<span class="name">lifeSpan</span>: <span class="number">5000</span>
<span class="name">count</span>: <span class="number">200</span>
<span class="name">angle</span>: <span class="number">270</span>
<span class="name">angleDeviation</span>: <span class="number">45</span>
<span class="name">velocity</span>: <span class="number">50</span>
<span class="name">velocityDeviation</span>: <span class="number">30</span>
<span class="type"><a href="qml-particlemotiongravity.html">ParticleMotionGravity</a></span> {
<span class="name">yattractor</span>: <span class="number">1000</span>
<span class="name">xattractor</span>: <span class="number">0</span>
<span class="name">acceleration</span>: <span class="number">25</span>
}
}
}</pre>
<p class="centerAlign"><img src="images/particles.gif" alt="" /></p><!-- @@@Particles -->
<h2>Property Documentation</h2>
<!-- $$$angle -->
<div class="qmlitem"><div class="qmlproto"><table class="qmlname"><tr valign="top" class="odd"><td class="tblQmlPropNode"><p><a name="angle-prop"></a><span class="name">angle</span> : <span class="type"><a href="qml-real.html">real</a></span></p></td></tr><tr valign="top" class="even"><td class="tblQmlPropNode"><p><a name="angleDeviation-prop"></a><span class="name">angleDeviation</span> : <span class="type"><a href="qml-real.html">real</a></span></p></td></tr></table></div><div class="qmldoc"><p>These properties control particle direction.</p>
<p><a href="qml-particles.html#angleDeviation-prop">angleDeviation</a> randomly varies the direction up to the specified variation. For example, the following creates particles whose initial direction will vary from 15 degrees to 105 degrees:</p>
<pre class="qml"> <span class="type"><a href="qml-particles.html">Particles</a></span> {
<span class="name">source</span>: <span class="string">"star.png"</span>
<span class="name">angle</span>: <span class="number">60</span>
<span class="name">angleDeviation</span>: <span class="number">90</span>
}</pre>
</div></div><!-- @@@angle -->
<br/>
<!-- $$$count -->
<div class="qmlitem"><div class="qmlproto"><table class="qmlname"><tr valign="top" class="odd"><td class="tblQmlPropNode"><p><a name="count-prop"></a><span class="name">count</span> : <span class="type"><a href="qml-int.html">int</a></span></p></td></tr></table></div><div class="qmldoc"><p>This property holds the maximum number of particles</p>
<p>The particles element emits particles until it has count active particles. When this number is reached, new particles are not emitted until some of the current particles reach the end of their lifespan.</p>
<p>If count is -1 then there is no maximum number of active particles, and particles will be constantly emitted at the rate specified by <a href="qml-particles.html#emissionRate-prop">emissionRate</a>.</p>
<p>The default value for count is 1.</p>
<p>If both count and <a href="qml-particles.html#emissionRate-prop">emissionRate</a> are set to -1, nothing will be emitted.</p>
</div></div><!-- @@@count -->
<br/>
<!-- $$$emissionRate -->
<div class="qmlitem"><div class="qmlproto"><table class="qmlname"><tr valign="top" class="odd"><td class="tblQmlPropNode"><p><a name="emissionRate-prop"></a><span class="name">emissionRate</span> : <span class="type"><a href="qml-int.html">int</a></span></p></td></tr></table></div><div class="qmldoc"><p>This property holds the target number of particles to emit every second.</p>
<p>The particles element will emit up to emissionRate particles every second. Fewer particles may be emitted per second if the maximum number of particles has been reached.</p>
<p>If emissionRate is set to -1 there is no limit to the number of particles emitted per second, and particles will be instantly emitted to reach the maximum number of particles specified by count.</p>
<p>The default value for emissionRate is -1.</p>
<p>If both count and emissionRate are set to -1, nothing will be emitted.</p>
</div></div><!-- @@@emissionRate -->
<br/>
<!-- $$$emissionVariance -->
<div class="qmlitem"><div class="qmlproto"><table class="qmlname"><tr valign="top" class="odd"><td class="tblQmlPropNode"><p><a name="emissionVariance-prop"></a><span class="name">emissionVariance</span> : <span class="type"><a href="qml-real.html">real</a></span></p></td></tr></table></div><div class="qmldoc"><p>This property holds how inconsistent the rate of particle emissions are. It is a number between 0 (no variance) and 1 (some variance).</p>
<p>The expected number of particles emitted per second is <a href="qml-particles.html#emissionRate-prop">emissionRate</a>. If emissionVariance is 0 then particles will be emitted consistently throughout each second to reach that number. If emissionVariance is greater than 0 the rate of particle emission will vary randomly throughout the second, with the consequence that the actual number of particles emitted in one second will vary randomly as well.</p>
<p>emissionVariance is the maximum deviation from emitting <a href="qml-particles.html#emissionRate-prop">emissionRate</a> particles per second. An emissionVariance of 0 means you should get exactly <a href="qml-particles.html#emissionRate-prop">emissionRate</a> particles emitted per second, and an emissionVariance of 1 means you will get between zero and two times <a href="qml-particles.html#emissionRate-prop">emissionRate</a> particles per second, but you should get <a href="qml-particles.html#emissionRate-prop">emissionRate</a> particles per second on average.</p>
<p>Note that even with an emissionVariance of 0 there may be some variance due to performance and hardware constraints.</p>
<p>The default value of emissionVariance is 0.5</p>
</div></div><!-- @@@emissionVariance -->
<br/>
<!-- $$$fadeInDuration -->
<div class="qmlitem"><div class="qmlproto"><table class="qmlname"><tr valign="top" class="odd"><td class="tblQmlPropNode"><p><a name="fadeInDuration-prop"></a><span class="name">fadeInDuration</span> : <span class="type"><a href="qml-int.html">int</a></span></p></td></tr><tr valign="top" class="even"><td class="tblQmlPropNode"><p><a name="fadeOutDuration-prop"></a><span class="name">fadeOutDuration</span> : <span class="type"><a href="qml-int.html">int</a></span></p></td></tr></table></div><div class="qmldoc"><p>These properties hold the time taken to fade the particles in and out.</p>
<p>By default fade in is 200ms and fade out is 300ms.</p>
</div></div><!-- @@@fadeInDuration -->
<br/>
<!-- $$$lifeSpan -->
<div class="qmlitem"><div class="qmlproto"><table class="qmlname"><tr valign="top" class="odd"><td class="tblQmlPropNode"><p><a name="lifeSpan-prop"></a><span class="name">lifeSpan</span> : <span class="type"><a href="qml-int.html">int</a></span></p></td></tr><tr valign="top" class="even"><td class="tblQmlPropNode"><p><a name="lifeSpanDeviation-prop"></a><span class="name">lifeSpanDeviation</span> : <span class="type"><a href="qml-int.html">int</a></span></p></td></tr></table></div><div class="qmldoc"><p>These properties describe the life span of each particle.</p>
<p>The default lifespan for a particle is 1000ms.</p>
<p><a href="qml-particles.html#lifeSpanDeviation-prop">lifeSpanDeviation</a> randomly varies the lifeSpan up to the specified variation. For example, the following creates particles whose lifeSpan will vary from 150ms to 250ms:</p>
<pre class="qml"> <span class="type"><a href="qml-particles.html">Particles</a></span> {
<span class="name">source</span>: <span class="string">"star.png"</span>
<span class="name">lifeSpan</span>: <span class="number">200</span>
<span class="name">lifeSpanDeviation</span>: <span class="number">100</span>
}</pre>
</div></div><!-- @@@lifeSpan -->
<br/>
<!-- $$$motion -->
<div class="qmlitem"><div class="qmlproto"><table class="qmlname"><tr valign="top" class="odd"><td class="tblQmlPropNode"><p><a name="motion-prop"></a><span class="name">motion</span> : <span class="type">ParticleMotion</span></p></td></tr></table></div><div class="qmldoc"><p>This property sets the type of motion to apply to the particles.</p>
<p>When a particle is created it will have an initial direction and velocity. The motion of the particle during its <a href="qml-particles.html#lifeSpan-prop">lifeSpan</a> is then influenced by the motion property.</p>
<p>Default motion is <a href="qml-particlemotionlinear.html">ParticleMotionLinear</a>.</p>
</div></div><!-- @@@motion -->
<br/>
<!-- $$$source -->
<div class="qmlitem"><div class="qmlproto"><table class="qmlname"><tr valign="top" class="odd"><td class="tblQmlPropNode"><p><a name="source-prop"></a><span class="name">source</span> : <span class="type"><a href="qml-string.html">string</a></span></p></td></tr></table></div><div class="qmldoc"><p>This property holds the URL of the particle image.</p>
</div></div><!-- @@@source -->
<br/>
<!-- $$$velocity -->
<div class="qmlitem"><div class="qmlproto"><table class="qmlname"><tr valign="top" class="odd"><td class="tblQmlPropNode"><p><a name="velocity-prop"></a><span class="name">velocity</span> : <span class="type"><a href="qml-real.html">real</a></span></p></td></tr><tr valign="top" class="even"><td class="tblQmlPropNode"><p><a name="velocityDeviation-prop"></a><span class="name">velocityDeviation</span> : <span class="type"><a href="qml-real.html">real</a></span></p></td></tr></table></div><div class="qmldoc"><p>These properties control the velocity of the particles.</p>
<p><a href="qml-particles.html#velocityDeviation-prop">velocityDeviation</a> randomly varies the velocity up to the specified variation. For example, the following creates particles whose initial velocity will vary from 40 to 60.</p>
<pre class="qml"> <span class="type"><a href="qml-particles.html">Particles</a></span> {
<span class="name">source</span>: <span class="string">"star.png"</span>
<span class="name">velocity</span>: <span class="number">50</span>
<span class="name">velocityDeviation</span>: <span class="number">20</span>
}</pre>
</div></div><!-- @@@velocity -->
<br/>
<h2>Method Documentation</h2>
<!-- $$$burst -->
<div class="qmlitem"><div class="qmlproto"><table class="qmlname"><tr valign="top" class="odd"><td class="tblQmlFuncNode"><p><a name="burst-method"></a>Particles::<span class="name">burst</span> ( <span class="type"><a href="qml-int.html">int</a></span> <i>count</i>, <span class="type"><a href="qml-int.html">int</a></span> <i>emissionRate</i> )</p></td></tr></table></div><div class="qmldoc"><p>Initiates a burst of particles.</p>
<p>This method takes two arguments. The first argument is the number of particles to emit and the second argument is the <a href="qml-particles.html#emissionRate-prop">emissionRate</a> for the burst. If the second argument is omitted, it is treated as -1. The burst of particles has a separate <a href="qml-particles.html#emissionRate-prop">emissionRate</a> and count to the normal emission of particles. The burst uses the same values as normal emission for all other properties, including <a href="qml-particles.html#emissionVariance-prop">emissionVariance</a>.</p>
<p>The normal emission of particles will continue during the burst, however the particles created by the burst count towards the maximum number used by normal emission. To avoid this behavior, use two Particles elements.</p>
</div></div><!-- @@@burst -->
<br/>
<p class="naviNextPrevious footerNavi">
</p>
</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>
