ParallelAnimation

Since: BlackBerry 10.0.0

#include <bb/cascades/ParallelAnimation>

A group animation that plays its children animations in parallel.

Children animations can be added to the animation using the builder model.

When the animations' AbstractAnimation::play() method is called the children animations will be played in parallel.

Setting an explicit target via the AbstractAnimation::target property will set implicit targets for its children animations automatically. This allows you to specify a target only for the root of the animation tree.

Children animations of a ParallelAnimation will not have their states updated while an animation is playing. AbstractAnimation functions such as isPlaying(), isStopped(), isEnded() can not be used on children animations since their return values will not accurately represent the current state of the animation. Only the root animation in the animation tree will contain accurate states and will have corresponding lifecycle signals emitted.

This example shows how to use a parallel animation to run a fade transition and a translate transition on a Button, simultaneously. The button is translated along its x-axis from 0 to 100 and is faded out at the same time. Since the target node (pButton) is specified as the root of the animation tree, the SequentialAnimation and its children animations will target the same node (it becomes the children's implicit target).

Button *button = Button::create();
ParallelAnimation *animation = ParallelAnimation::create(button)
    // Translate to X 100
    .add(TranslateTransition::create()
        .fromX(0).toX(100))
    // Fade the opacity from 1.0f to 0.0f
    .add(FadeTransition::create()
        .from(1.0f).to(0.5f))
    .autoDeleted();
animation->play();
And here's how to create a ParallelAnimation in QML:
Button {
    text: "Translate then fade me away"
    onClicked: parallel.play()
    animations: [
        ParallelAnimation {
            id: parallel
            TranslateTransition {
                duration: 1000
                fromX: 0
                toX: 100
            }
            FadeTransition {
                duration: 1000
                fromOpacity: 1.0
                toOpacity: 0.2
            }
        }
    ]
}


Overview

QML properties

Only has inherited QML properties

animations: QDeclarativeListProperty< bb::cascades::AbstractAnimation > [read-only]Inherited
attachedObjects: QDeclarativeListProperty< QObject > [read-only]Inherited
delay: intInherited
objectName: QStringInherited
parent: QObject [read-only]Inherited
repeatCount: intInherited
state: bb::cascades::AnimationState::Type [read-only]Inherited
target: bb::cascades::VisualNodeInherited
ui: bb::cascades::UIConfig [read-only]Inherited

QML signals

Only has inherited QML signals

onCreationCompletedInherited: {}
onDelayChangedInherited: {}
onEndedInherited: {}
onObjectNameChangedInherited: {}
onRepeatCountChangedInherited: {}
onStartedInherited: {}
onStateChangedInherited: {}
onStoppedInherited: {}
onTargetChangedInherited: {}

Properties Index

Only has inherited properties

QDeclarativeListProperty< bb::cascades::AbstractAnimation >animations [read-only]Inherited
QDeclarativeListProperty< QObject >attachedObjects [read-only]Inherited
intdelayInherited
QStringobjectNameInherited
QObjectparent [read-only]Inherited
intrepeatCountInherited
bb::cascades::AnimationState::Typestate [read-only]Inherited
bb::cascades::VisualNodetargetInherited
bb::cascades::UIConfigui [read-only]Inherited

Public Static Attributes Index

Only has inherited public static attributes

const intRepeatForeverInherited

Public Functions Index

ParallelAnimation ()
virtual ~ParallelAnimation ()
intdelay () const Inherited
virtual boolevent (QEvent *event)Inherited
Q_INVOKABLE boolisEnded () const Inherited
Q_INVOKABLE boolisPlaying () const Inherited
Q_INVOKABLE boolisStarted () const Inherited
Q_INVOKABLE boolisStopped () const Inherited
Q_SLOT voidplay ()Inherited
intrepeatCount () const Inherited
Q_SLOT voidresetDelay ()Inherited
Q_SLOT voidresetRepeatCount ()Inherited
Q_SLOT voidresetTarget ()Inherited
voidsetDelay (int delay)Inherited
voidsetObjectName (const QString &name)Inherited
voidsetRepeatCount (int repeatCount)Inherited
Q_SLOT voidsetTarget (bb::cascades::VisualNode *target)Inherited
bb::cascades::AnimationState::Typestate () const Inherited
Q_SLOT voidstop ()Inherited
bb::cascades::VisualNode *target () const Inherited
virtual Q_INVOKABLE QStringtoDebugString () const Inherited
Q_INVOKABLE bb::cascades::UIConfig *ui () const Inherited

Static Public Functions Index

Buildercreate (VisualNode *target=0)

Protected Functions Index

Only has inherited protected functions

BaseObject (QObject *parent=0)Inherited
virtual voidconnectNotify (const char *signal)Inherited
virtual voiddisconnectNotify (const char *signal)Inherited

Signals Index

Only has inherited signals

voidcreationCompleted ()Inherited
voiddelayChanged (int delay)Inherited
voidended ()Inherited
voidobjectNameChanged (const QString &objectName)Inherited
voidrepeatCountChanged (int repeatCount)Inherited
voidstarted ()Inherited
voidstateChanged (bb::cascades::AnimationState::Type newState)Inherited
voidstopped ()Inherited
voidtargetChanged (bb::cascades::VisualNode *target)Inherited

Properties

(Only has inherited properties)

QDeclarativeListProperty< bb::cascades::AbstractAnimation > animationsInherited[read-only]

A QDeclarativeListProperty containing a list of animations owned by this GroupAnimation.

Since:

BlackBerry 10.0.0

QDeclarativeListProperty< QObject > attachedObjectsInherited[read-only]

A hierarchical list of the UIObject's attached objects.

Since:

BlackBerry 10.0.0

int delayInherited

The delay (in milliseconds) before an animation executes when the play() function is invoked.

Since:

BlackBerry 10.0.0

QString objectNameInherited

This property is overridden from QObject.

See also:

QObject::objectName().

Since:

BlackBerry 10.0.0

QObject parentInherited[read-only]

A read-only property that represents this object's parent.

The parent of an object is specified using QObject::setParent(QObject*). The purpose of the property is to expose the object's parent to QML.

This property is read-only to prevent modifications from QML, where typically the parent is declaratively set. In C++ code, the parent can be explicitly set using QObject::setParent(QObject*), or implicitly set by adding it to a visual container.

The default value of this property is 0.

Since:

BlackBerry 10.0.0

int repeatCountInherited

The number of times that an animation runs.

Once an animation is playing, changing its properties will not take effect until the next time animation is started.

To have an animation run forever, you can specify AnimationRepeatCount::Forever. Here's how you can set an animation to run forever in QML:

Container {
    background: Color.Black
    preferredHeight: 50
    preferredWidth: 50
    animations: [
        TranslateTransition {
            id: foreverandever
            fromX: 0
            toX: 500
            duration: 1000
            repeatCount: AnimationRepeatCount.Forever
        }
    ]
    onCreationCompleted: foreverandever.play()
}
The default value is 1. This must not be a negative value.
Since:

BlackBerry 10.0.0

bb::cascades::AnimationState::Type stateInherited[read-only]

The current state of the animation.

The default value is bb::cascades:AnimationState::Stopped.

Since:

BlackBerry 10.0.0

bb::cascades::VisualNode targetInherited

The target for the animation.

Even if a target is not explicitly set, the animation can have an implicit target in the following instances:

  • If the animation is a child of a VisualNode object, the parent is assumed to be the animation's implicit target

  • If the animation is a child of a GroupAnimation object, the GroupAnimation object's target is assumed to be the animation's implicit target

If an animation has children, setting the explicit target for the animation causes the children's implicit targets to change accordingly.

When the target node is explicitly set on the animation, the node it is attached to does not take ownership, meaning that if the target node is destroyed, the animation is not removed with it. To help manage the animation lifecycle, the ownership of an animation can assigned to a VisualNode by calling VisualNode::addAnimation(). This can help ensure that the animation's memory is cleaned up properly.

Once an animation is playing, changing its properties will not take effect until the next time animation is started.

The default value of this property is 0.

Since:

BlackBerry 10.0.0

bb::cascades::UIConfig uiInherited[read-only]

An object that gives access to unit conversion routines.

QML use:
        // Size using design units
        Container {
            preferredWidth: ui.du(12)
            preferredHeight: ui.du(5)
        }

        // Size using design units, snap to whole pixels
        Container {
            preferredWidth: ui.sdu(13.5)
            preferredHeight: ui.sdu(7.5)
        }

        // Size using absolute pixel values
        Container {
            preferredWidth: ui.px(150)
            preferredHeight: ui.px(50)
        }
C++ use:
Container *container1 = Container::create().background(Color::Red);
UIConfig *ui = container1->ui();
container1->setPreferredWidth(ui->du(12));
container1->setPreferredHeight(ui->du(5));

Container *container2 = Container::create().background(Color::Green);
container2->setPreferredWidth(ui->sdu(13.5));
container2->setPreferredHeight(ui->sdu(7.5));

Container *container3 = Container::create().background(Color::Blue);
container3->setPreferredWidth(ui->px(150));
container3->setPreferredHeight(ui->sdu(50));
Since:

Blackberry 10.3.0

Public Static Attributes

(Only has inherited public static attributes)

const int RepeatForever ()Inherited

A constant to be used for specifying an animation that repeats forever.

Since:

BlackBerry 10.0.0

Public Functions

ParallelAnimation ()

Constructs a ParallelAnimation with no children.

Since:

BlackBerry 10.0.0

virtual~ParallelAnimation ()

Destructor.

Since:

BlackBerry 10.0.0

int delay ()Inherited

Returns the delay (in milliseconds) before an animation executes after the play() function is invoked.

Return:

A non-negative number indicating the delay of this animation.

Since:

BlackBerry 10.0.0

virtual bool event (Inherited

Overloaded to implement the event mechanism in Cascades.

Warning!

If this function is overridden, it must be called by the derived class for events to work properly in Cascades.

Parameters
event

The received event.

Return:

True if the received event was recognized and processed, false otherwise.

Since:

BlackBerry 10.0.0

Q_INVOKABLE bool isEnded ()Inherited

Indicates whether the animation has ended.

An animation has ended if it has run its course without being stopped. It should be noted that if this node is a child of GroupAnimation this method cannot be used to determine the state of this animation node. Only the root GroupAnimation in an animation tree will indicate its state correctly.

Return:

true if the animation has ended, false otherwise.

Since:

BlackBerry 10.0.0

Q_INVOKABLE bool isPlaying ()Inherited

Indicates whether the animation is currently playing.

Note that if this node is a child of GroupAnimation this method cannot be used to determine the state of this animation node. Only the root GroupAnimation in an animation tree will indicate its state correctly.

Return:

true if the animation is currently playing, false otherwise.

Since:

BlackBerry 10.0.0

Q_INVOKABLE bool isStarted ()Inherited

Indicates whether the animation has been started but is not yet playing.

If the animation is a child of a GroupAnimation object, this function cannot be used to determine the state of this animation node. Only the root GroupAnimation in an animation tree will indicate its state correctly.

Return:

true if the animation is started, but not yet playing, false otherwise.

Since:

BlackBerry 10.0.0

Q_INVOKABLE bool isStopped ()Inherited

Indicates whether the animation was interrupted by the stop() function.

It should be noted that if this node is a child of GroupAnimation this method cannot be used to determine the state of this animation node. Only the root GroupAnimation in an animation tree will indicate its state correctly.

Return:

true if the animation was interrupted, false otherwise.

Since:

BlackBerry 10.0.0

Q_SLOT void play ()Inherited

Plays the animation.

Only the root animation in a tree of animations can be played explicitly. If this function is called on a child animation, the function is ignored.

If more than one animation is affecting the same property, calling play() on more than one will stop the running one.

Since:

BlackBerry 10.0.0

int repeatCount ()Inherited

Returns the value of the repeatCount property.

The repeatCount property is the number of times the animation will be repeated after it started.

Return:

A positive number indicating the number of times this animation will be repeated. If repeatCount is equal to bb::cascades::AnimationRepeatCount::Forever, the animation will repeat indefinitely.

Since:

BlackBerry 10.0.0

Q_SLOT void resetDelay ()Inherited

Resets the delay to its default value of 0 milliseconds.

Since:

BlackBerry 10.0.0

Q_SLOT void resetRepeatCount ()Inherited

Resets the repeatCount property to its default value of 1.

Since:

BlackBerry 10.0.0

Q_SLOT void resetTarget ()Inherited

Resets the target to its default value of 0.

Since:

BlackBerry 10.0.0

void setDelay (
  • intdelay)
Inherited

Sets the delay (in milliseconds) before an animation executes after the play() function is invoked.

The passed argument must be non-negative or it is ignored.

Parameters
delay

A non-negative number representing animation delay in milliseconds.

Since:

BlackBerry 10.0.0

void setObjectName (Inherited

Sets the objectName property.

Parameters
name

The new name for the object.

Since:

BlackBerry 10.0.0

void setRepeatCount (
  • intrepeatCount)
Inherited

Sets the value of the repeatCount property.

The repeatCount property is the number of times that the animation will be repeated after it started. The passed argument must be positive or it is ignored.

bb::cascades::AnimationRepeatCount::Forever can be used to specify an animation that repeats forever.

Parameters
repeatCount

A positive number representing number of times animation will be repeated.

Since:

BlackBerry 10.0.0

Q_SLOT void setTarget (Inherited

Sets the explicit target for the animation.

Once the operation is completed, ownership of the passed object does not change. The animation does not become a child of the target VisualNode.

Once an animation is playing, changing its properties will not take effect until the next time animation is started.

If an animation has children, setting the explicit target for the animation causes the children's implicit targets to change accordingly (unless they already have an explicit target).

Parameters
target

The explicit target for the animation, or 0 to remove the current target.

Since:

BlackBerry 10.0.0

bb::cascades::AnimationState::Type state ()Inherited

Returns the current state.

Since:

BlackBerry 10.0.0

Q_SLOT void stop ()Inherited

Stops this animation.

If the animation is started again it will restart from the beginning.

Only the root animation in a tree of animations can be stopped explicitly. If this function is called on a child animation, the function is ignored.

Since:

BlackBerry 10.0.0

bb::cascades::VisualNode * target ()Inherited

Returns the explicit target for the animation.

Once the operation is completed, ownership of the animation does not change. This function only works for explicit targets; implicit targets are not returned.

Return:

The explicit target for the animation, or 0 if a target is not set.

Since:

BlackBerry 10.0.0

virtual Q_INVOKABLE QString toDebugString ()Inherited

Returns a debug string representing this object.

Return:

A debug string for the object.

Since:

BlackBerry 10.0.0

Q_INVOKABLE bb::cascades::UIConfig * ui ()Inherited

Returns the UIConfig for this ui object.

The UIConfig can be used to perform unit conversions from design units (du) and snapped design units (sdu) to pixels.

Ownership remains with Cascades.

C++ use:
Container *container1 = Container::create().background(Color::Red);
UIConfig *ui = container1->ui();
container1->setPreferredWidth(ui->du(12));
container1->setPreferredHeight(ui->du(5));

Container *container2 = Container::create().background(Color::Green);
container2->setPreferredWidth(ui->sdu(13.5));
container2->setPreferredHeight(ui->sdu(7.5));

Container *container3 = Container::create().background(Color::Blue);
container3->setPreferredWidth(ui->px(150));
container3->setPreferredHeight(ui->sdu(50));
Return:

The UIConfig for this ui object.

Since:

BlackBerry 10.3.0

Static Public Functions

Builder create (

Creates and returns a builder for creating the group animation.

Using the builder to create an animation:

Button *button = Button::create();
ParallelAnimation *animation = ParallelAnimation::create(button)
    // Translate to X 100
    .add(TranslateTransition::create()
        .fromX(0).toX(100))
    // Fade the opacity from 1.0f to 0.0f
    .add(FadeTransition::create()
        .from(1.0f).to(0.5f))
    .autoDeleted();
animation->play();
Parameters
target

An optional explicit target for the animation.

Return:

A builder for constructing the animation.

Since:

BlackBerry 10.0.0

Protected Functions

(Only has inherited protected functions)

BaseObject (Inherited

Constructs an instance of BaseObject's subclass.

Parameters
parent

An optional parent, defaults to 0.

Since:

BlackBerry 10.0.0

virtual void connectNotify (
  • const char *signal)
Inherited

Overloaded to implement the event mechanism in Cascades.

If this function is overridden, it must be called by the derived class for events to work properly in Cascades.

Parameters
signal

The connected signal.

Since:

BlackBerry 10.0.0

virtual void disconnectNotify (
  • const char *signal)
Inherited

Overloaded to implement the event mechanism in Cascades.

If this function is overridden, it must be called by the derived class for events to work properly in Cascades.

Parameters
signal

The disconnected signal.

Since:

BlackBerry 10.0.0

Signals

(Only has inherited signals)

void creationCompleted ()Inherited

Emitted when this object is instantiated as a result of loading a QML document and creating the root node (only after the root component that caused this instantiation has completed construction), or when the object is being constructed from its builder class.

This signal indicates that the construction and initialization of the object has been completed, the properties are initialized, and any QML binding values have been assigned to the object.

This signal is not emitted when the object is constructed from C++ using the constructor. If the object is constructed using its builder class, the signal is emitted when the the builder class returns the fully constructed object.

This signal can be used when there is an activity that needs to be performed, such as a property state integrity verification after the object is instantiated from a QML document or a builder, but before control is returned to the application.

See also:

QmlDocument

Since:

BlackBerry 10.0.0

void delayChanged (
  • intdelay)
Inherited

Emitted when the delay of the animation changes.

Parameters
delay

The new delay for the animation.

Since:

BlackBerry 10.0.0

void ended ()Inherited

Emitted when the animation has ended.

The animation can be deleted from this signal only using QObject::deleteLater() signal.

This signal is not emitted for child animations.

Since:

BlackBerry 10.0.0

void objectNameChanged (Inherited

This signal is emitted when the objectName property is changed.

Since:

BlackBerry 10.0.0

void repeatCountChanged (
  • intrepeatCount)
Inherited

Emitted when the repeatCount of the animation changes.

Parameters
repeatCount

The new repeat count for the animation.

Since:

BlackBerry 10.0.0

void started ()Inherited

Emitted when the animation is started.

Note that this may happen sometimes after the play() method is invoked.

This signal is not emitted for child animations.

Since:

BlackBerry 10.0.0

void stateChanged (Inherited

Emitted when the state of the animation changes.

Parameters
newState

The new state of the animation.

Since:

BlackBerry 10.0.0

void stopped ()Inherited

Emitted when the animation is stopped.

Note that this may happen sometimes after the stop() method is invoked. It will also be emitted if an animation is stopped because a different animation, implicit or explicit, is started on the same value.

The animation can be deleted from this signal only using QObject::deleteLater() signal.

This signal is not emitted for child animations.

Since:

BlackBerry 10.0.0

void targetChanged (Inherited

Emitted when the target property changed.

Parameters
target

The new target or 0 if it was unset.

Since:

BlackBerry 10.0.0

Last modified: 2014-06-24



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus