QML Particles Element
The Particles object generates and moves particles. More...
Inherits Item
This element was introduced in Qt 4.7.
Properties
- angle : real
- angleDeviation : real
- count : int
- emissionRate : int
- emissionVariance : real
- fadeInDuration : int
- fadeOutDuration : int
- lifeSpan : int
- lifeSpanDeviation : int
- motion : ParticleMotion
- source : string
- velocity : real
- velocityDeviation : real
Methods
Detailed Description
Particles are available in the Qt.labs.particles 1.0 module. Elements in the Qt.labs module are not guaranteed to remain compatible in future versions.
This element provides preliminary support for particles in QML, and may be heavily changed or removed in later versions.
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.
The particles are painted relative to the parent of the Particles object. Moving the Particles object will not move the particles already emitted.
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.
import QtQuick 1.0 import Qt.labs.particles 1.0 Rectangle { width: 240 height: 320 color: "black" Particles { y: 0 width: parent.width height: 30 source: "star.png" lifeSpan: 5000 count: 50 angle: 70 angleDeviation: 36 velocity: 30 velocityDeviation: 10 ParticleMotionWander { xvariance: 30 pace: 100 } } Particles { y: 300 x: 120 width: 1 height: 1 source: "star.png" lifeSpan: 5000 count: 200 angle: 270 angleDeviation: 45 velocity: 50 velocityDeviation: 30 ParticleMotionGravity { yattractor: 1000 xattractor: 0 acceleration: 25 } } }
Property Documentation
These properties control particle direction.
angleDeviation 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:
Particles { source: "star.png" angle: 60 angleDeviation: 90 }
count : int |
This property holds the maximum number of particles
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.
If count is -1 then there is no maximum number of active particles, and particles will be constantly emitted at the rate specified by emissionRate.
The default value for count is 1.
If both count and emissionRate are set to -1, nothing will be emitted.
emissionRate : int |
This property holds the target number of particles to emit every second.
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.
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.
The default value for emissionRate is -1.
If both count and emissionRate are set to -1, nothing will be emitted.
emissionVariance : real |
This property holds how inconsistent the rate of particle emissions are. It is a number between 0 (no variance) and 1 (some variance).
The expected number of particles emitted per second is emissionRate. 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.
emissionVariance is the maximum deviation from emitting emissionRate particles per second. An emissionVariance of 0 means you should get exactly emissionRate particles emitted per second, and an emissionVariance of 1 means you will get between zero and two times emissionRate particles per second, but you should get emissionRate particles per second on average.
Note that even with an emissionVariance of 0 there may be some variance due to performance and hardware constraints.
The default value of emissionVariance is 0.5
These properties hold the time taken to fade the particles in and out.
By default fade in is 200ms and fade out is 300ms.
These properties describe the life span of each particle.
The default lifespan for a particle is 1000ms.
lifeSpanDeviation randomly varies the lifeSpan up to the specified variation. For example, the following creates particles whose lifeSpan will vary from 150ms to 250ms:
Particles { source: "star.png" lifeSpan: 200 lifeSpanDeviation: 100 }
This property sets the type of motion to apply to the particles.
When a particle is created it will have an initial direction and velocity. The motion of the particle during its lifeSpan is then influenced by the motion property.
Default motion is ParticleMotionLinear.
source : string |
This property holds the URL of the particle image.
These properties control the velocity of the particles.
velocityDeviation randomly varies the velocity up to the specified variation. For example, the following creates particles whose initial velocity will vary from 40 to 60.
Particles { source: "star.png" velocity: 50 velocityDeviation: 20 }
Method Documentation
Initiates a burst of particles.
This method takes two arguments. The first argument is the number of particles to emit and the second argument is the emissionRate for the burst. If the second argument is omitted, it is treated as -1. The burst of particles has a separate emissionRate and count to the normal emission of particles. The burst uses the same values as normal emission for all other properties, including emissionVariance.
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.