Initial stab at docs for QtQuick.Particles 2.0

Change-Id: I3c53f7998dff95616a994edf19094fa4007d74ab
Reviewed-on: http://codereview.qt.nokia.com/1388
Reviewed-by: Qt Sanity Bot <qt_sanity_bot@ovi.com>
Reviewed-by: Martin Jones <martin.jones@nokia.com>

diff --git a/doc/src/declarative/particles.qdoc b/doc/src/declarative/particles.qdoc
new file mode 100644 (file)
index 0000000..9f1da69
--- /dev/null
+++ b/doc/src/declarative/particles.qdoc
@@ -0,0 +1,116 @@
+/****************************************************************************
+**
+** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** GNU Free Documentation License
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file.
+**
+** Other Usage
+** Alternatively, this file may be used in accordance with the terms
+** and conditions contained in a signed written agreement between you
+** and Nokia.
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+  \qmlmodule QtQuick.Particles 2
+  \title QML Module QtQuick.Particles 2
+
+  \brief Elements for the Qt Quick particle system
+
+  This QML module contains a particle system for Qt Quick.
+
+  For a simple overview of how the system can be used, see \l{qml-particles.html}{Using the Qt Quick Particle System}.
+
+*/
+
+/*!
+    \page qml-particlesystem.html
+    \title Using the Qt Quick Particle System
+
+    \section1 The ParticleSystem
+    This particle system contains four main types of QML Elements: ParticleSystem, Painters, Emitters and Affectors.
+
+    The ParticleSystem element ties all the other elements together, and manages the shared timeline. Painters, Emitters
+    and Affectors must all have the same ParticleSystem to be able to interact with each other.
+
+    You may have as many ParticleSystems as you want subject to this constraint, so the logical separation is to have
+    one ParticleSystem for all the elements that you want to interact, or just one if the number of elements is small
+    and they are easily kept under control..
+
+    \section1 Logical Particles
+    All the particle system elements act on "logical particles". Every particle has a logical representation inside
+    the particle system, and this is what the elements act upon. Not every logical particle needs to be visualized,
+    and some logical particles could lead to multiple visual particles being drawn on screen.
+    \section1 Particle Groups
+    Every logical particle is a member of a particle group, and each group is identified by a name. If no other
+    group has been specified, a logical particle belongs to the group with the name "" (the empty string), which
+    acts the same as any other group. Groups are used for two purposes, for controlling particles and because they
+    can have stochastic state transitions.
+
+    Groups control particles because you can never access an individual particle with any of the particle system
+    elements. All elements act on groups as a whole, and so any particles that need to behave differently from each
+    other (aside from the usual stochastic parameter variation) will need to be in different groups.
+
+    Particles can also change groups dynamically. When this happens the particles trajectory is unaltered, but it
+    can be acted upon by different ParticlePainters or Affectors. Particles can either have their state changed by
+    an Affector, or stochastic state transitions can be defined in the group definition (in the particleStates property).
+    Generally, groups should only be defined in that property if they require stochastic state transitions. Otherwise,
+    it is sufficient to have the groups be defined simply by the strings used in the particle/particles properties
+    of the elements.
+
+    \section1 Emitters
+    Emitters emit logical particles into the system. These particles have a trajectory and lifespan, but no visualization.
+    These particles are emitted from the location of the Emitter.
+
+    FollowEmitters are a special type of emitter which emits particles from the location of other logicial particles. Any logical
+    particle of the followed type within the bounds of a FollowEmitter will cause particle emission from its location, as if there
+    were an Emitter on it with the same properties as the FollowEmitter.
+
+    \section1 ParticlePainters
+    Painters are the elements that visualize logical particles. For each logical particle in the groups assigned to it,
+    which are within its bounds (or outside, if you do not set the clip property on the element) it will be visualized
+    in a manner dependant on the type of ParticlePainter.  The base type of ParticlePainter does not draw anything.
+    ImageParticle renders an image at the particle location. CustomParticle allows you to write your own shaders to render
+    the particles, passing in the logical particle state as vertex data. ItemParticle allows you to visualize logical
+    particles using arbitrary QML delegates. ModelParticle is similar, but coordinates model data amongst the delegates
+    in a similar manner to the view classes.
+
+    As the ParticlePainter is the QML element visualizing the particles in the scene, it is its Z value which is important
+    when trying to place particles above or below other elements visually.
+
+    \section1 Affectors
+    Affectors are an optional component of a particle system. They can perform a variety of manipulations to the simulation,
+    such as altering the trajectory of particles or prematurely ending their life in the simulation. For performance reasons,
+    it is recommended not to use Affectors in high-volume particle systems.
+
+    \section1 Stochastic Parameters
+    As particle systems benefit from stochastic control of parameters across a large number of instances, several stochastic
+    helper types are used by the particle system. If you do not wish to have any stochastic variation in these parameters,
+    then do not specify any variation in these elements.
+
+    \section2 Directions
+    Directions can be specified by angle and magnitude, or by x and y components. While any direction can be specified with
+    either method, there is a significant difference between varying the x and y components and varying the angle and magnitude.
+    Varying the x and y components will lead to a rectangular area around the specified point, while varying the angle will lead
+    to an arc centered on the specfied point.
+
+    \section2 Shapes
+    The particle system contains several elements which represent shapes. These elements do not visualize shapes, and are used
+    for the purpose of selecting a random point within the shape. If you want a specific point with no randomness, use a 0 width
+    and 0 height shape (which is the default). Otherwise you can use the shape elements provides to specify an area, so that the
+    result can use a random point selected from that area.
+*/

diff --git a/src/declarative/particles/qsgangleddirection.cpp b/src/declarative/particles/qsgangleddirection.cpp
index 78bf024..ffd434f 100644 (file)
--- a/src/declarative/particles/qsgangleddirection.cpp
+++ b/src/declarative/particles/qsgangleddirection.cpp
@@ -43,6 +43,56 @@
 #include <cmath>
 QT_BEGIN_NAMESPACE
 const qreal CONV = 0.017453292519943295;
+/*!
+    \qmlclass AngledDirection QSGAngledDirection
+    \inqmlmodule QtQuick.Particles 2
+    \since QtQuick.Particles 2.0
+    \inherits StochasticDirection
+    \brief The AngledDirection element allows you to specify a direction that varies in angle
+
+    The AngledDirection element allows both the specification of a direction by angle and magnitude,
+    as well as varying the parameters by angle or magnitude.
+*/
+/*!
+    \qmlproperty real QtQuick.Particles2::AngledDirection::angle
+    This property specifies the base angle for the direction.
+    The angle of this direction will vary by no more than angleVariation
+    from this angle.
+
+    Angle is specified by degrees clockwise from straight right.
+
+    The default value is zero.
+*/
+/*!
+    \qmlproperty real QtQuick.Particles2::AngledDirection::magnitude
+    This property specifies the base magnitude for the direction.
+    The magnitude of this direction will vary by no more than magnitudeVariation
+    from this magnitude.
+
+    Magnitude is specified in units of pixels per second.
+
+    The default value is zero.
+*/
+/*!
+    \qmlproperty real QtQuick.Particles2::AngledDirection::angleVariation
+    This property specifies the maximum angle variation for the direction.
+    The angle of the direction will vary by up to angleVariation clockwise
+    and anticlockwise from the value specified in angle.
+
+    Angle is specified by degrees clockwise from straight right.
+
+    The default value is zero.
+*/
+/*!
+    \qmlproperty real QtQuick.Particles2::AngledDirection::magnitudeVariation
+    This property specifies the base magnitude for the direction.
+    The magnitude of this direction will vary by no more than magnitudeVariation
+    from the base magnitude.
+
+    Magnitude is specified in units of pixels per second.
+
+    The default value is zero.
+*/
 QSGAngledDirection::QSGAngledDirection(QObject *parent) :
     QSGStochasticDirection(parent)
   , m_angle(0)

diff --git a/src/declarative/particles/qsgcumulativedirection.cpp b/src/declarative/particles/qsgcumulativedirection.cpp
index fe635e5..5ffdef6 100644 (file)
--- a/src/declarative/particles/qsgcumulativedirection.cpp
+++ b/src/declarative/particles/qsgcumulativedirection.cpp
@@ -42,6 +42,15 @@
 #include "qsgcumulativedirection_p.h"
 QT_BEGIN_NAMESPACE
 
+/*!
+    \qmlclass CumulativeDirection QSGCumulativeDirection
+    \inqmlmodule QtQuick.Particles 2
+    \since QtQuick.Particles 2.0
+    \inherits StochasticDirection
+    \brief The CumulativeDirection element allows you to specify a direction made of other directions
+
+    The CumulativeDirection element will act as a direction that sums the directions within it.
+*/
 QSGCumulativeDirection::QSGCumulativeDirection(QObject *parent):QSGStochasticDirection(parent)
 {
 }

diff --git a/src/declarative/particles/qsgcustomparticle.cpp b/src/declarative/particles/qsgcustomparticle.cpp
index 9081695..f1477f6 100644 (file)
--- a/src/declarative/particles/qsgcustomparticle.cpp
+++ b/src/declarative/particles/qsgcustomparticle.cpp
@@ -119,6 +119,15 @@ struct PlainVertices {
     PlainVertex v4;
 };
 
+/*!
+    \qmlclass CustomParticle QSGCustomParticle
+    \inqmlmodule QtQuick.Particles 2
+    \since QtQuick.Particles 2.0
+    \inherits ParticlePainter
+    \brief The CustomParticle element allows you to specify your own shader to paint particles.
+
+*/
+
 QSGCustomParticle::QSGCustomParticle(QSGItem* parent)
     : QSGParticlePainter(parent)
     , m_pleaseReset(true)
@@ -137,7 +146,7 @@ void QSGCustomParticle::componentComplete()
 
 //Trying to keep the shader conventions the same as in qsgshadereffectitem
 /*!
-    \qmlproperty string CustomParticle::fragmentShader
+    \qmlproperty string QtQuick.Particles2::CustomParticle::fragmentShader
 
     This property holds the fragment shader's GLSL source code.
     The default shader passes the texture coordinate along to the fragment
@@ -156,7 +165,7 @@ void QSGCustomParticle::setFragmentShader(const QByteArray &code)
 }
 
 /*!
-    \qmlproperty string CustomParticle::vertexShader
+    \qmlproperty string QtQuick.Particles2::CustomParticle::vertexShader
 
     This property holds the vertex shader's GLSL source code.
     The default shader expects the texture coordinate to be passed from the

diff --git a/src/declarative/particles/qsgellipseextruder.cpp b/src/declarative/particles/qsgellipseextruder.cpp
index e430233..59e8803 100644 (file)
--- a/src/declarative/particles/qsgellipseextruder.cpp
+++ b/src/declarative/particles/qsgellipseextruder.cpp
@@ -42,12 +42,29 @@
 #include "qsgellipseextruder_p.h"
 #include <cmath>
 QT_BEGIN_NAMESPACE
+/*!
+    \qmlclass EllipseShape QSGEllipseExtruder
+    \inqmlmodule QtQuick.Particles 2
+    \since QtQuick.Particles 2.0
+    \inherits Shape
+    \brief The EllipseShape represents an ellipse to other particle system elements
+
+    This shape can be used by Emitter subclasses and Affector subclasses to have
+    them act upon an ellipse shaped area.
+*/
 QSGEllipseExtruder::QSGEllipseExtruder(QObject *parent) :
     QSGParticleExtruder(parent)
   , m_fill(true)
 {
 }
 
+/*!
+    \qmlproperty bool QtQuick.Particles2::EllipseShape::fill
+    If fill is true the ellipse is filled; otherwise it is just a border.
+
+    Default is true.
+*/
+
 QPointF QSGEllipseExtruder::extrude(const QRectF & r)
 {
     qreal theta = ((qreal)rand()/RAND_MAX) * 6.2831853071795862;

diff --git a/src/declarative/particles/qsgemitter.cpp b/src/declarative/particles/qsgemitter.cpp
index 67ebcd6..f05ee6a 100644 (file)
--- a/src/declarative/particles/qsgemitter.cpp
+++ b/src/declarative/particles/qsgemitter.cpp
@@ -43,6 +43,24 @@
 #include "qsgparticlesystem_p.h"
 QT_BEGIN_NAMESPACE
 
+/*!
+    \qmlclass Emitter QSGBasicEmitter
+    \inqmlmodule QtQuick.Particles 2
+    \since QtQuick.Particles 2.0
+    \brief The Emitter element allows you to emit logical particles.
+
+    This element emits logical particles into the ParticleSystem, with the
+    given starting attributes.
+
+    Note that logical particles are not
+    automatically rendered, you will need to have one or more
+    ParticlePainter elements visualizing them.
+
+    Note that the given starting attributes can be modified at any point
+    in the particle's lifetime by any Affector element in the same
+    ParticleSystem. This includes attributes like lifespan.
+*/
+
 QSGBasicEmitter::QSGBasicEmitter(QSGItem* parent)
     : QSGParticleEmitter(parent)
     , m_speed_from_movement(0)
@@ -54,6 +72,52 @@ QSGBasicEmitter::QSGBasicEmitter(QSGItem* parent)
 //    setFlag(ItemHasContents);
 }
 
+/*!
+    \qmlproperty ParticleSystem QtQuick.Particles2::Emitter::system
+
+    This is the Particle system that the Emitter will emit into.
+    This can be omitted if the Emitter is a direct child of the ParticleSystem
+*/
+/*!
+    \qmlproperty string QtQuick.Particles2::Emitter::particle
+*/
+/*!
+    \qmlproperty Shape QtQuick.Particles2::Emitter::shape
+*/
+/*!
+    \qmlproperty bool QtQuick.Particles2::Emitter::emitting
+*/
+/*!
+    \qmlproperty real QtQuick.Particles2::Emitter::emitRate
+*/
+/*!
+    \qmlproperty int QtQuick.Particles2::Emitter::lifeSpan
+*/
+/*!
+    \qmlproperty int QtQuick.Particles2::Emitter::lifeSpanVariation
+*/
+/*!
+    \qmlproperty int QtQuick.Particles2::Emitter::emitCap
+*/
+/*!
+    \qmlproperty real QtQuick.Particles2::Emitter::size
+*/
+/*!
+    \qmlproperty real QtQuick.Particles2::Emitter::endSize
+*/
+/*!
+    \qmlproperty real QtQuick.Particles2::Emitter::sizeVariation
+*/
+/*!
+    \qmlproperty StochasticDirection QtQuick.Particles2::Emitter::speed
+*/
+/*!
+    \qmlproperty StochasticDirection QtQuick.Particles2::Emitter::acceleration
+*/
+/*!
+    \qmlproperty qreal QtQuick.Particles2::Emitter::speedFromMovement
+*/
+
 void QSGBasicEmitter::setSpeedFromMovement(qreal t)
 {
     if (t == m_speed_from_movement)

diff --git a/src/declarative/particles/qsgfollowemitter.cpp b/src/declarative/particles/qsgfollowemitter.cpp
index 9b5b084..ff9f83d 100644 (file)
--- a/src/declarative/particles/qsgfollowemitter.cpp
+++ b/src/declarative/particles/qsgfollowemitter.cpp
@@ -44,6 +44,23 @@
 #include <cmath>
 QT_BEGIN_NAMESPACE
 
+/*!
+    \qmlclass Emitter QSGBasicEmitter
+    \inqmlmodule QtQuick.Particles 2
+    \since QtQuick.Particles 2.0
+    \brief The Emitter element allows you to emit logical particles.
+
+    This element emits logical particles into the ParticleSystem, with the
+    given starting attributes.
+
+    Note that logical particles are not
+    automatically rendered, you will need to have one or more
+    ParticlePainter elements visualizing them.
+
+    Note that the given starting attributes can be modified at any point
+    in the particle's lifetime by any Affector element in the same
+    ParticleSystem. This includes attributes like lifespan.
+*/
 QSGFollowEmitter::QSGFollowEmitter(QSGItem *parent) :
     QSGParticleEmitter(parent)
   , m_particlesPerParticlePerSecond(0)
@@ -63,6 +80,65 @@ QSGFollowEmitter::QSGFollowEmitter(QSGItem *parent) :
             this, SLOT(recalcParticlesPerSecond()));
 }
 
+
+/*!
+    \qmlproperty ParticleSystem QtQuick.Particles2::FollowEmitter::system
+
+    This is the Particle system that the FollowEmitter will emit into.
+    This can be omitted if the FollowEmitter is a direct child of the ParticleSystem
+*/
+/*!
+    \qmlproperty string QtQuick.Particles2::FollowEmitter::particle
+*/
+/*!
+    \qmlproperty string QtQuick.Particles2::FollowEmitter::follow
+*/
+/*!
+    \qmlproperty Shape QtQuick.Particles2::FollowEmitter::shape
+*/
+/*!
+    \qmlproperty Shape QtQuick.Particles2::FollowEmitter::emitShape
+*/
+/*!
+    \qmlproperty real QtQuick.Particles2::FollowEmitter::emitWidth
+*/
+/*!
+    \qmlproperty real QtQuick.Particles2::FollowEmitter::emitHeight
+*/
+/*!
+    \qmlproperty bool QtQuick.Particles2::FollowEmitter::emitting
+*/
+/*!
+    \qmlproperty real QtQuick.Particles2::FollowEmitter::emitRatePerParticle
+*/
+/*!
+    \qmlproperty int QtQuick.Particles2::FollowEmitter::lifeSpan
+*/
+/*!
+    \qmlproperty int QtQuick.Particles2::FollowEmitter::lifeSpanVariation
+*/
+/*!
+    \qmlproperty int QtQuick.Particles2::FollowEmitter::emitCap
+*/
+/*!
+    \qmlproperty real QtQuick.Particles2::FollowEmitter::size
+*/
+/*!
+    \qmlproperty real QtQuick.Particles2::FollowEmitter::endSize
+*/
+/*!
+    \qmlproperty real QtQuick.Particles2::FollowEmitter::sizeVariation
+*/
+/*!
+    \qmlproperty StochasticDirection QtQuick.Particles2::FollowEmitter::speed
+*/
+/*!
+    \qmlproperty StochasticDirection QtQuick.Particles2::FollowEmitter::acceleration
+*/
+/*!
+    \qmlproperty qreal QtQuick.Particles2::FollowEmitter::speedFromMovement
+*/
+
 void QSGFollowEmitter::recalcParticlesPerSecond(){
     if (!m_system)
         return;

diff --git a/src/declarative/particles/qsgfriction.cpp b/src/declarative/particles/qsgfriction.cpp
index 2bd4391..fcd43a5 100644 (file)
--- a/src/declarative/particles/qsgfriction.cpp
+++ b/src/declarative/particles/qsgfriction.cpp
@@ -41,6 +41,19 @@
 
 #include "qsgfriction_p.h"
 QT_BEGIN_NAMESPACE
+/*!
+    \qmlclass Friction QSGFrictionAffector
+    \inqmlmodule QtQuick.Particles 2
+    \since QtQuick.Particles 2.0
+    \inherits Affector
+    \brief The Friction affector slows down movement proportional to the particle's current speed.
+
+*/
+
+/*!
+    \qmlproperty real QtQuick.Particles2::Friction::factor
+*/
+
 QSGFrictionAffector::QSGFrictionAffector(QSGItem *parent) :
     QSGParticleAffector(parent), m_factor(0.0)
 {

diff --git a/src/declarative/particles/qsggravity.cpp b/src/declarative/particles/qsggravity.cpp
index 0959c76..1639588 100644 (file)
--- a/src/declarative/particles/qsggravity.cpp
+++ b/src/declarative/particles/qsggravity.cpp
@@ -43,6 +43,25 @@
 #include <cmath>
 QT_BEGIN_NAMESPACE
 const qreal CONV = 0.017453292520444443;
+/*!
+    \qmlclass Gravity QSGGravityAffector
+    \inqmlmodule QtQuick.Particles 2
+    \since QtQuick.Particles 2.0
+    \inherits Affector
+    \brief The Gravity element allows you to set a constant accleration in an angle
+
+    This element will set the acceleration of all affected particles to a vector of
+    the specified magnitude in the specified angle.
+*/
+
+/*!
+    \qmlproperty real QtQuick.Particles2::Gravity::acceleration
+
+*/
+/*!
+    \qmlproperty real QtQuick.Particles2::Gravity::angle
+*/
+
 QSGGravityAffector::QSGGravityAffector(QSGItem *parent) :
     QSGParticleAffector(parent), m_acceleration(-10), m_angle(90), m_xAcc(0), m_yAcc(0)
 {

diff --git a/src/declarative/particles/qsgimageparticle.cpp b/src/declarative/particles/qsgimageparticle.cpp
index aa73821..8c04175 100644 (file)
--- a/src/declarative/particles/qsgimageparticle.cpp
+++ b/src/declarative/particles/qsgimageparticle.cpp
@@ -278,6 +278,78 @@ QSGMaterialShader *SimpleMaterial::createShader() const {
     return new SimpleMaterialData;
 }
 
+/*!
+    \qmlclass ImageParticle QSGImageParticle
+    \inqmlmodule QtQuick.Particles 2
+    \since QtQuick.Particles 2.0
+    \inherits ParticlePainter
+    \brief The ImageParticle element visualizes logical particles using an image
+
+    This element renders a logical particle as an image. The image can be
+        - colorized
+        - roatated
+        - deformed
+        - a sprite-based animation
+*/
+/*!
+    \qmlproperty url QtQuick.Particles2::ImageParticle::source
+*/
+/*!
+    \qmlproperty url QtQuick.Particles2::ImageParticle::colorTable
+*/
+/*!
+    \qmlproperty url QtQuick.Particles2::ImageParticle::sizeTable
+*/
+/*!
+    \qmlproperty url QtQuick.Particles2::ImageParticle::opacityTable
+*/
+/*!
+    \qmlproperty color QtQuick.Particles2::ImageParticle::color
+*/
+/*!
+    \qmlproperty real QtQuick.Particles2::ImageParticle::colorVariation
+*/
+/*!
+    \qmlproperty real QtQuick.Particles2::ImageParticle::redVariation
+*/
+/*!
+    \qmlproperty real QtQuick.Particles2::ImageParticle::greenVariation
+*/
+/*!
+    \qmlproperty real QtQuick.Particles2::ImageParticle::blueVariation
+*/
+/*!
+    \qmlproperty real QtQuick.Particles2::ImageParticle::alpha
+*/
+/*!
+    \qmlproperty real QtQuick.Particles2::ImageParticle::alphaVariation
+*/
+/*!
+    \qmlproperty real QtQuick.Particles2::ImageParticle::rotation
+*/
+/*!
+    \qmlproperty real QtQuick.Particles2::ImageParticle::rotationVariation
+*/
+/*!
+    \qmlproperty real QtQuick.Particles2::ImageParticle::rotationSpeed
+*/
+/*!
+    \qmlproperty real QtQuick.Particles2::ImageParticle::rotationSpeedVariation
+*/
+/*!
+    \qmlproperty bool QtQuick.Particles2::ImageParticle::autoRotation
+*/
+/*!
+    \qmlproperty StochasticDirection QtQuick.Particles2::ImageParticle::xVector
+*/
+/*!
+    \qmlproperty StochasticDirection QtQuick.Particles2::ImageParticle::yVector
+*/
+/*!
+    \qmlproperty list<Sprite> QtQuick.Particles2::ImageParticle::sprites
+*/
+
+
 QSGImageParticle::QSGImageParticle(QSGItem* parent)
     : QSGParticlePainter(parent)
     , m_do_reset(false)

diff --git a/src/declarative/particles/qsgitemparticle.cpp b/src/declarative/particles/qsgitemparticle.cpp
index 625c98b..1d2d166 100644 (file)
--- a/src/declarative/particles/qsgitemparticle.cpp
+++ b/src/declarative/particles/qsgitemparticle.cpp
@@ -48,6 +48,15 @@
 
 QT_BEGIN_NAMESPACE
 
+/*!
+    \qmlclass ItemParticle QSGItemParticle
+    \inqmlmodule QtQuick.Particles 2
+    \since QtQuick.Particles 2.0
+    \inherits ParticlePainter
+    \brief The ItemParticle element allows you to specify your own delegate to paint particles.
+
+*/
+
 QSGItemParticle::QSGItemParticle(QSGItem *parent) :
     QSGParticlePainter(parent), m_fade(true), m_delegate(0)
 {

diff --git a/src/declarative/particles/qsgkill.cpp b/src/declarative/particles/qsgkill.cpp
index b9373ef..9d4bc94 100644 (file)
--- a/src/declarative/particles/qsgkill.cpp
+++ b/src/declarative/particles/qsgkill.cpp
@@ -42,6 +42,15 @@
 #include "qsgkill_p.h"
 #include "qsgparticleemitter_p.h"
 QT_BEGIN_NAMESPACE
+/*!
+    \qmlclass Kill QSGKillAffector
+    \inqmlmodule QtQuick.Particles 2
+    \since QtQuick.Particles 2.0
+    \inherits Affector
+    \brief The Kill affector allows you to expire affected particles
+
+*/
+
 QSGKillAffector::QSGKillAffector(QSGItem *parent) :
     QSGParticleAffector(parent)
 {

diff --git a/src/declarative/particles/qsglineextruder.cpp b/src/declarative/particles/qsglineextruder.cpp
index 5acb2b2..a08d052 100644 (file)
--- a/src/declarative/particles/qsglineextruder.cpp
+++ b/src/declarative/particles/qsglineextruder.cpp
@@ -41,6 +41,25 @@
 #include "qsglineextruder_p.h"
 #include <cmath>
 
+/*!
+    \qmlclass LineShape QSGLineExtruder
+    \inqmlmodule QtQuick.Particles 2
+    \since QtQuick.Particles 2.0
+    \inherits Shape
+    \brief The LineShape represents a line to Affectors and Emitter
+
+*/
+
+/*!
+    \qmlproperty bool QtQuick.Particles2::LineShape::mirrored
+
+    By default, the line goes from (0,0) to (width, height) of the item that
+    this shape is being applied to.
+
+    If mirrored is set to true, this will be mirrored along the y axis.
+    The line will then go from (0,height) to (width, 0).
+*/
+
 QSGLineExtruder::QSGLineExtruder(QObject *parent) :
     QSGParticleExtruder(parent), m_mirrored(false)
 {

diff --git a/src/declarative/particles/qsgmaskextruder.cpp b/src/declarative/particles/qsgmaskextruder.cpp
index 4119c95..e762803 100644 (file)
--- a/src/declarative/particles/qsgmaskextruder.cpp
+++ b/src/declarative/particles/qsgmaskextruder.cpp
@@ -43,6 +43,19 @@
 #include <QImage>
 #include <QDebug>
 QT_BEGIN_NAMESPACE
+/*!
+    \qmlclass MaskShape QSGMaskExtruder
+    \inqmlmodule QtQuick.Particles 2
+    \since QtQuick.Particles 2.0
+    \inherits Shape
+    \brief The MaskShape element allows you to represent an image as a shape to affectors and emitters.
+
+*/
+/*!
+    \qmlproperty url QtQuick.Particles2::MaskShape::source
+*/
+
+
 QSGMaskExtruder::QSGMaskExtruder(QObject *parent) :
     QSGParticleExtruder(parent)
   , m_lastWidth(-1)

diff --git a/src/declarative/particles/qsgmodelparticle.cpp b/src/declarative/particles/qsgmodelparticle.cpp
index 60c4438..844b76d 100644 (file)
--- a/src/declarative/particles/qsgmodelparticle.cpp
+++ b/src/declarative/particles/qsgmodelparticle.cpp
@@ -46,6 +46,15 @@
 #include <QDebug>
 
 QT_BEGIN_NAMESPACE
+/*!
+    \qmlclass ModelParticle QSGModelParticle
+    \inqmlmodule QtQuick.Particles 2
+    \since QtQuick.Particles 2.0
+    \inherits ParticlePainter
+    \brief The ModelParticle element allows you to specify a model and delegate pair to paint particles.
+
+*/
+
 
 QSGModelParticle::QSGModelParticle(QSGItem *parent) :
     QSGParticlePainter(parent), m_ownModel(false), m_comp(0), m_model(0), m_fade(true), m_modelCount(0)

diff --git a/src/declarative/particles/qsgparticleaffector.cpp b/src/declarative/particles/qsgparticleaffector.cpp
index 7c6eac5..bf268ef 100644 (file)
--- a/src/declarative/particles/qsgparticleaffector.cpp
+++ b/src/declarative/particles/qsgparticleaffector.cpp
@@ -42,6 +42,64 @@
 #include "qsgparticleaffector_p.h"
 #include <QDebug>
 QT_BEGIN_NAMESPACE
+/*!
+    \qmlclass Affector QSGParticleAffector
+    \inqmlmodule QtQuick.Particles 2
+    \since QtQuick.Particles 2.0
+    \brief Affector elements can alter the attributes of logical particles at any point in their lifetime.
+
+    The base Affector does not alter any attributes, but can be used to emit a signal
+    when a particle meets certain conditions.
+
+    If an affector has a defined size, then it will only affect particles within its size and position on screen.
+*/
+/*!
+    \qmlproperty ParticleSystem QtQuick.Particles2::Affector::system
+    This is the system which will be affected by the element.
+    If the Affector is a direct child of a ParticleSystem, it will automatically be associated with it.
+*/
+/*!
+    \qmlproperty list<string> QtQuick.Particles2::Affector::particles
+    Which logical particle groups will be affected.
+
+    If empty, it will affect all particles.
+*/
+/*!
+    \qmlproperty list<string> QtQuick.Particles2::Affector::collisionParticles
+    If any logical particle groups are specified here, then the affector
+    will only be triggered if the particle being examined intersects with
+    a particle of one of these groups.
+
+    By default, no groups are specified.
+*/
+/*!
+    \qmlproperty bool QtQuick.Particles2::Affector::active
+    If active is set to false, this affector will not affect any particles.
+
+    Usually this is used to conditionally turn an affector on or off.
+
+    Default value is true.
+*/
+/*!
+    \qmlproperty bool QtQuick.Particles2::Affector::onceOff
+    If onceOff is set to true, this affector will only affect each particle
+    once in their lifetimes.
+
+    Default value is false.
+*/
+/*!
+    \qmlproperty Shape QtQuick.Particles2::Affector::shape
+    If a size has been defined, the shape property can be used to affect a
+    non-rectangular area.
+*/
+/*!
+    \qmlproperty bool QtQuick.Particles2::Affector::signal
+    If this is set to true, then an affected(x,y) signal will be emitted each
+    time this affector affects a particle.
+
+    Default value is false.
+*/
+
 QSGParticleAffector::QSGParticleAffector(QSGItem *parent) :
     QSGItem(parent), m_needsReset(false), m_system(0), m_active(true)
   , m_updateIntSet(false), m_shape(new QSGParticleExtruder(this)), m_signal(false)

diff --git a/src/declarative/particles/qsgparticleemitter.cpp b/src/declarative/particles/qsgparticleemitter.cpp
index 9f8a5e7..dfd1618 100644 (file)
--- a/src/declarative/particles/qsgparticleemitter.cpp
+++ b/src/declarative/particles/qsgparticleemitter.cpp
@@ -41,6 +41,7 @@
 
 #include "qsgparticleemitter_p.h"
 QT_BEGIN_NAMESPACE
+//Not visible from QML, so not documented. Document subclasses.
 QSGParticleEmitter::QSGParticleEmitter(QSGItem *parent) :
     QSGItem(parent)
   , m_particlesPerSecond(10)

diff --git a/src/declarative/particles/qsgparticleemitter_p.h b/src/declarative/particles/qsgparticleemitter_p.h
index 8967a52..9cf130d 100644 (file)
--- a/src/declarative/particles/qsgparticleemitter_p.h
+++ b/src/declarative/particles/qsgparticleemitter_p.h
@@ -60,7 +60,6 @@ QT_MODULE(Declarative)
 class QSGParticleEmitter : public QSGItem
 {
     Q_OBJECT
-    //###currently goes in emitters OR sets system. Pick one?
     Q_PROPERTY(QSGParticleSystem* system READ system WRITE setSystem NOTIFY systemChanged)
     Q_PROPERTY(QString particle READ particle WRITE setParticle NOTIFY particleChanged)
     Q_PROPERTY(QSGParticleExtruder* shape READ extruder WRITE setExtruder NOTIFY extruderChanged)

diff --git a/src/declarative/particles/qsgparticleextruder.cpp b/src/declarative/particles/qsgparticleextruder.cpp
index 965cfc5..b51ab8b 100644 (file)
--- a/src/declarative/particles/qsgparticleextruder.cpp
+++ b/src/declarative/particles/qsgparticleextruder.cpp
@@ -43,6 +43,15 @@
 
 QT_BEGIN_NAMESPACE
 
+/*!
+    \qmlclass Shape QSGParticleExtruder
+    \inqmlmodule QtQuick.Particles 2
+    \since QtQuick.Particles 2.0
+    \brief The Shape element allows you to specify an area for affectors and emitter.
+
+    The base class is just a rectangle.
+*/
+
 QSGParticleExtruder::QSGParticleExtruder(QObject *parent) :
     QObject(parent), m_fill(true)
 {

diff --git a/src/declarative/particles/qsgparticlepainter.cpp b/src/declarative/particles/qsgparticlepainter.cpp
index 6c892b4..7bcaefa 100644 (file)
--- a/src/declarative/particles/qsgparticlepainter.cpp
+++ b/src/declarative/particles/qsgparticlepainter.cpp
@@ -42,6 +42,28 @@
 #include "qsgparticlepainter_p.h"
 #include <QDebug>
 QT_BEGIN_NAMESPACE
+/*!
+    \qmlclass ParticlePainter QSGParticlePainter
+    \inqmlmodule QtQuick.Particles 2
+    \since QtQuick.Particles 2.0
+    \inherits ParticlePainter
+    \brief ParticlePainter elements allow you to specify how to paint particles.
+
+    The default implementation paints nothing. See the subclasses if you want to
+    paint something visible.
+
+*/
+/*!
+    \qmlproperty ParticleSystem QtQuick.Particles2::ParticlePainter::system
+    This is the system whose particles can be painted by the element.
+    If the ParticlePainter is a direct child of a ParticleSystem, it will automatically be associated with it.
+*/
+/*!
+    \qmlproperty list<string> QtQuick.Particles2::ParticlePainter::particles
+    Which logical particle groups will be painted.
+
+    If empty, it will paint the default particle ("").
+*/
 QSGParticlePainter::QSGParticlePainter(QSGItem *parent) :
     QSGItem(parent),
     m_system(0), m_count(0), m_sentinel(new QSGParticleData(0))

diff --git a/src/declarative/particles/qsgparticlesystem.cpp b/src/declarative/particles/qsgparticlesystem.cpp
index 15a0119..98c685f 100644 (file)
--- a/src/declarative/particles/qsgparticlesystem.cpp
+++ b/src/declarative/particles/qsgparticlesystem.cpp
@@ -52,6 +52,37 @@
 #include <QDebug>
 
 QT_BEGIN_NAMESPACE
+/*!
+    \qmlclass ParticleSystem QSGParticleSystem
+    \inqmlmodule QtQuick.Particles 2
+    \since QtQuick.Particles 2.0
+    \brief The ParticleSystem brings together ParticlePainter, Emitter and Affector elements.
+
+*/
+
+/*!
+    \qmlproperty bool QtQuick.Particles2::ParticleSystem::running
+
+    If running is set to false, the particle system will not advance the simulation.
+*/
+/*!
+    \qmlproperty int QtQuick.Particles2::ParticleSystem::startTime
+
+    If start time is specified, then the system will simulate up to this time
+    before the system starts playing. This allows you to appear to start with a
+    fully populated particle system, instead of starting with no particles visible.
+*/
+/*!
+    \qmlproperty list<Sprite> QtQuick.Particles2::ParticleSystem::particleStates
+
+    You can define a sub-set of particle groups in this property in order to provide them
+    with stochastic state transitions.
+
+    Each QtQuick2::Sprite in this list is interpreted as corresponding to the particle group
+    with ths same name. Any transitions defined in these sprites will take effect on the particle
+    groups as well. Additionally FollowEmitters, Affectors and ParticlePainters definined
+    inside one of these sprites are automatically associated with the corresponding particle group.
+*/
 
 const qreal EPSILON = 0.001;
 //Utility functions for when within 1ms is close enough

diff --git a/src/declarative/particles/qsgpointattractor.cpp b/src/declarative/particles/qsgpointattractor.cpp
index 9b4c997..6be61aa 100644 (file)
--- a/src/declarative/particles/qsgpointattractor.cpp
+++ b/src/declarative/particles/qsgpointattractor.cpp
@@ -43,6 +43,19 @@
 #include <cmath>
 #include <QDebug>
 QT_BEGIN_NAMESPACE
+/*!
+    \qmlclass PointAttractor QSGPointAttractorAffector
+    \inqmlmodule QtQuick.Particles 2
+    \since QtQuick.Particles 2.0
+    \inherits Affector
+    \brief The PointAttractor allows you to attract particles towards a specific point.
+
+    Note that the size and position of this element affects which particles it affects.
+    The size of the point attracted to is always 0x0, and the location of that point
+    is specified by the x and y properties that badly need renaming.
+
+*/
+
 QSGPointAttractorAffector::QSGPointAttractorAffector(QSGItem *parent) :
     QSGParticleAffector(parent), m_strength(0.0), m_x(0), m_y(0)
   , m_physics(Velocity), m_proportionalToDistance(Linear)

diff --git a/src/declarative/particles/qsgpointdirection.cpp b/src/declarative/particles/qsgpointdirection.cpp
index 5b91650..0448ac9 100644 (file)
--- a/src/declarative/particles/qsgpointdirection.cpp
+++ b/src/declarative/particles/qsgpointdirection.cpp
@@ -43,6 +43,29 @@
 
 QT_BEGIN_NAMESPACE
 
+/*!
+    \qmlclass PointDirection QSGPointDirection
+    \inqmlmodule QtQuick.Particles 2
+    \since QtQuick.Particles 2.0
+    \inherits StochasticDirection
+    \brief The PointDirection element allows you to specify a direction that varies in x and y components
+
+    The PointDirection element allows both the specification of a direction by x and y components,
+    as well as varying the parameters by x or y component.
+*/
+/*!
+    \qmlproperty real QtQuick.Particles2::PointDirection::x
+*/
+/*!
+    \qmlproperty real QtQuick.Particles2::PointDirection::y
+*/
+/*!
+    \qmlproperty real QtQuick.Particles2::PointDirection::xVariation
+*/
+/*!
+    \qmlproperty real QtQuick.Particles2::PointDirection::yVariation
+*/
+
 QSGPointDirection::QSGPointDirection(QObject *parent) :
     QSGStochasticDirection(parent)
   , m_x(0)

diff --git a/src/declarative/particles/qsgspritegoal.cpp b/src/declarative/particles/qsgspritegoal.cpp
index 1c59034..79fcf81 100644 (file)
--- a/src/declarative/particles/qsgspritegoal.cpp
+++ b/src/declarative/particles/qsgspritegoal.cpp
@@ -47,6 +47,28 @@
 
 QT_BEGIN_NAMESPACE
 
+/*!
+    \qmlclass SpriteGoal QSGSpriteGoalAffector
+    \inqmlmodule QtQuick.Particles 2
+    \since QtQuick.Particles 2.0
+    \inherits Affector
+    \brief The SpriteGoal Affector allows you to change the state of a sprite or group of a particle.
+
+*/
+/*!
+    \qmlproperty string QtQuick.Particles2::SpriteGoal::goalState
+*/
+/*!
+    \qmlproperty bool QtQuick.Particles2::SpriteGoal::jump
+*/
+/*!
+    \qmlproperty bool QtQuick.Particles2::SpriteGoal::systemStates
+*/
+
+    Q_PROPERTY(QString goalState READ goalState WRITE setGoalState NOTIFY goalStateChanged)
+    Q_PROPERTY(bool jump READ jump WRITE setJump NOTIFY jumpChanged)
+    Q_PROPERTY(bool systemStates READ systemStates WRITE setSystemStates NOTIFY systemStatesChanged)
+
 QSGSpriteGoalAffector::QSGSpriteGoalAffector(QSGItem *parent) :
     QSGParticleAffector(parent), m_goalIdx(-1), m_jump(false), m_systemStates(false), m_lastEngine(0), m_notUsingEngine(false)
 {

diff --git a/src/declarative/particles/qsgstochasticdirection.cpp b/src/declarative/particles/qsgstochasticdirection.cpp
index 38def96..f44b941 100644 (file)
--- a/src/declarative/particles/qsgstochasticdirection.cpp
+++ b/src/declarative/particles/qsgstochasticdirection.cpp
@@ -42,6 +42,14 @@
 #include "qsgstochasticdirection_p.h"
 
 QT_BEGIN_NAMESPACE
+/*!
+    \qmlclass StochasticDirection QSGStochasticDirection
+    \inqmlmodule QtQuick.Particles 2
+    \since QtQuick.Particles 2.0
+    \brief The StochasticDirection elements allow you to specify a vector space.
+
+*/
+
 
 QSGStochasticDirection::QSGStochasticDirection(QObject *parent) :
     QObject(parent)

diff --git a/src/declarative/particles/qsgtargeteddirection.cpp b/src/declarative/particles/qsgtargeteddirection.cpp
index 0f6c0df..3e5d3e1 100644 (file)
--- a/src/declarative/particles/qsgtargeteddirection.cpp
+++ b/src/declarative/particles/qsgtargeteddirection.cpp
@@ -45,6 +45,44 @@
 #include <QDebug>
 
 QT_BEGIN_NAMESPACE
+/*!
+    \qmlclass TargetedDirection QSGTargetedDirection
+    \inqmlmodule QtQuick.Particles 2
+    \since QtQuick.Particles 2.0
+    \inherits StochasticDirection
+    \brief The TargetedDirection element allows you to specify a direction towards the target point
+
+*/
+/*!
+    \qmlproperty real QtQuick.Particles2::TargetedDirection::targetX
+*/
+/*!
+    \qmlproperty real QtQuick.Particles2::TargetedDirection::targetY
+*/
+/*!
+    \qmlproperty Item QtQuick.Particles2::TargetedDirection::targetItem
+    If specified, this will take precedence over targetX and targetY.
+    The targeted point will be the center of the specified Item
+*/
+/*!
+    \qmlproperty real QtQuick.Particles2::TargetedDirection::targetVariation
+*/
+/*!
+    \qmlproperty real QtQuick.Particles2::TargetedDirection::magnitude
+*/
+/*!
+    \qmlproperty real QtQuick.Particles2::TargetedDirection::magnitudeVariation
+*/
+/*!
+    \qmlproperty bool QtQuick.Particles2::TargetedDirection::proportionalMagnitude
+
+    If true, then the value of magnitude and magnitudeVariation shall be interpreted as multiples
+    of the distance between the source point and the target point, per second.
+
+    If false(default), then the value of magnitude and magnitudeVariation shall be interpreted as
+    pixels per second.
+*/
+
 QSGTargetedDirection::QSGTargetedDirection(QObject *parent) :
     QSGStochasticDirection(parent)
   , m_targetX(0)

diff --git a/src/declarative/particles/qsgtargeteddirection_p.h b/src/declarative/particles/qsgtargeteddirection_p.h
index 3a7e0d0..6fdd3f9 100644 (file)
--- a/src/declarative/particles/qsgtargeteddirection_p.h
+++ b/src/declarative/particles/qsgtargeteddirection_p.h
@@ -59,6 +59,7 @@ class QSGTargetedDirection : public QSGStochasticDirection
 
     Q_PROPERTY(qreal targetVariation READ targetVariation WRITE setTargetVariation NOTIFY targetVariationChanged)
 
+    //TODO: An enum would be better
     Q_PROPERTY(bool proportionalMagnitude READ proportionalMagnitude WRITE setProportionalMagnitude NOTIFY proprotionalMagnitudeChanged)
     Q_PROPERTY(qreal magnitude READ magnitude WRITE setMagnitude NOTIFY magnitudeChanged)
     Q_PROPERTY(qreal magnitudeVariation READ magnitudeVariation WRITE setMagnitudeVariation NOTIFY magnitudeVariationChanged)

diff --git a/src/declarative/particles/qsgturbulence.cpp b/src/declarative/particles/qsgturbulence.cpp
index 929c652..c846f15 100644 (file)
--- a/src/declarative/particles/qsgturbulence.cpp
+++ b/src/declarative/particles/qsgturbulence.cpp
@@ -46,6 +46,27 @@
 #include <QDebug>
 QT_BEGIN_NAMESPACE
 
+/*!
+    \qmlclass Turbulence QSGTurbulenceAffector
+    \inqmlmodule QtQuick.Particles 2
+    \since QtQuick.Particles 2.0
+    \inherits Affector
+    \brief The TurbulenceAffector is a bit of a hack and probably shouldn't be used yet.
+
+*/
+/*!
+    \qmlproperty int QtQuick.Particles2::Turbulence::strength
+    Maximum magnitude of a point in the vector field.
+*/
+/*!
+    \qmlproperty int QtQuick.Particles2::Turbulence::frequency
+    Times per second vector field is perturbed.
+*/
+/*!
+    \qmlproperty int QtQuick.Particles2::Turbulence::gridSize
+    Square root of the number of points in the vector field simulcrum.
+*/
+
 QSGTurbulenceAffector::QSGTurbulenceAffector(QSGItem *parent) :
     QSGParticleAffector(parent),
     m_strength(10), m_lastT(0), m_frequency(64), m_gridSize(10), m_field(0), m_inited(false)

diff --git a/src/declarative/particles/qsgwander.cpp b/src/declarative/particles/qsgwander.cpp
index 70e43a8..849f288 100644 (file)
--- a/src/declarative/particles/qsgwander.cpp
+++ b/src/declarative/particles/qsgwander.cpp
@@ -42,6 +42,14 @@
 #include "qsgwander_p.h"
 #include "qsgparticlesystem_p.h"//for ParticlesVertices
 QT_BEGIN_NAMESPACE
+/*!
+    \qmlclass Wander QSGWanderAffector
+    \inqmlmodule QtQuick.Particles 2
+    \since QtQuick.Particles 2.0
+    \inherits Affector
+    \brief The Wander affector allows particles to randomly vary their trajectory.
+
+*/
 
 QSGWanderAffector::QSGWanderAffector(QSGItem *parent) :
     QSGParticleAffector(parent), m_xVariance(0), m_yVariance(0), m_pace(0)