RotateTransition

Since: BlackBerry 10.0.0

#include <bb/cascades/RotateTransition>

An animation that rotates a VisualNode around its z-axis.

When rotating a visual node, you specify the beginning and ending of the transition by using the fromAngleZ and toAngleZ properties. The values of the to and from properties represent the degrees of a circle. The duration of the animation and the easing curve are specified by the AbstractTransition::duration and AbstractTransition::easingCurve properties, respectively.

When both the fromAngleZ and toAngleZ properties are specified, the transition will run as normal in the specified duration, using the specified easing curve.

If only the fromAngleZ property is specified, the transition will run from the value specified by fromAngleZ to the value of the VisualNode::rotationZ property at the time the animation was started.

If only the toAngleZ property is specified, the transition will run from the current value of the VisualNode::rotationZ property at the time animation started to the toAngleZ that was specified.

By not specifying a to or from property, the actual value remains undefined. So, you should not attempt to read the value unless the corresponding isSet function is set to true (for example, isToAngleZSet()).

While a property is being animated, its value does not change. It's only when the animation is completed that the animated property is updated with a new value. If you need access to the intermediate values for an animated property, you can be notified of changes through the VisualNode::rotationZChanging signal. However, because of the frequency that this signal is triggered, performance issues can arise, so it should only be used when absolutely necessary.

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

Here's an example of how to create a transition that animates the rotationZ property of a Slider from 90 to 270 in 1000 milliseconds.

Slider *slider = Slider::create();
RotateTransition *transition = RotateTransition::create(slider)
    .fromAngleZ(90)
    .toAngleZ(270)
    .duration(1000);
transition->play();
In this example, the transition animates the rotationZ property of the slider from its current value to 180 using StockCurve::CubicIn curve. Once the transition is complete it is auto-deleted.
Slider *slider2 = Slider::create();
RotateTransition *transition2 = RotateTransition::create(slider2)
    .toAngleZ(180)
    .easingCurve(StockCurve::CubicIn)
    .autoDeleted(true);
transition2->play();
In QML, you add animations to a control's animations list, which represents all of the animations that apply to the control. When you want to start the animation, you simply call its play() function. Here's how to create a button that, when clicked, rotates 180 degrees over the course of three seconds:
Button {
    text: "Rotate me"
    animations: [
        RotateTransition {
            id: rotateAnimation
            toAngleZ: 180
            duration: 3000
        }
    ]
    onClicked: {
        rotateAnimation.play();
    }
}


Overview

QML properties

fromAngleZ: float
fromAngleZSet: bool [read-only]
toAngleZ: float
toAngleZSet: bool [read-only]
attachedObjects: QDeclarativeListProperty< QObject > [read-only]Inherited
delay: intInherited
duration: intInherited
easingCurve: bb::cascades::EasingCurveInherited
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

Properties Index

Public Static Attributes Index

Only has inherited public static attributes

const intRepeatForeverInherited

Public Functions Index

RotateTransition ()
virtual ~RotateTransition ()
floatfromAngleZ () const
boolisFromAngleZSet () const
boolisToAngleZSet () const
Q_SLOT voidresetFromAngleZ ()
Q_SLOT voidresetToAngleZ ()
Q_SLOT voidsetFromAngleZ (float value)
Q_SLOT voidsetToAngleZ (float value)
floattoAngleZ () const
intdelay () const Inherited
intduration () const Inherited
QVarianteasingCurve () 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_INVOKABLE voidresetDuration ()Inherited
Q_INVOKABLE voidresetEasingCurve ()Inherited
Q_SLOT voidresetRepeatCount ()Inherited
Q_SLOT voidresetTarget ()Inherited
voidsetDelay (int delay)Inherited
Q_SLOT voidsetDuration (int duration)Inherited
Q_SLOT voidsetEasingCurve (const bb::cascades::EasingCurve &curve)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

voidfromAngleZChanged (float fromAngleZ)
voidtoAngleZChanged (float toAngleZ)
voidcreationCompleted ()Inherited
voiddelayChanged (int delay)Inherited
voiddurationChanged (int duration)Inherited
voideasingCurveChanged (const QVariant &easingCurve)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

float fromAngleZ

Specifies the value that the VisualNode::rotationZ property is animated from.

Since:

BlackBerry 10.0.0

bool fromAngleZSet[read-only]

Indicates whether the fromAngleZ property of the transition is set.

If true the fromAngleZ property been set for this transition; if false the fromAngleZ property is not set.

By default, fromAngleZSet is false meaning fromAngleZ has not been set.

Since:

BlackBerry 10.0.0

float toAngleZ

Specifies the value that the VisualNode::rotationZ property is animated to.

If the animation was playing when this property is set the change will not take effect until the next time the animation is started.

By default the value of this property is not set.

Since:

BlackBerry 10.0.0

bool toAngleZSet[read-only]

Indicates whether the toAngleZ property of the transition is set.

If true the toAngleZ property been set for this transition; if false the toAngleZ property is not set.

By default, toAngleZSet is false meaning toAngleZ has not been set.

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

int durationInherited

The duration of the transition (in milliseconds).

Since:

BlackBerry 10.0.0

QVariant easingCurveInherited

Specifies the easing curve for this transition.

If the animation was playing when this property is set the change will not take effect until the next time the animation is started.

The default value of this attribute is StockCurve::CubicIn

To assign a value to the easingCurve property from JavaScript, use the assignment operator instead of calling the setter method directly

See also:

EasingCurve

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

RotateTransition ()

Creates a RotateTransition object with unspecified to and from properties.

Since:

BlackBerry 10.0.0

virtual~RotateTransition ()

Destructor.

Since:

BlackBerry 10.0.0

float fromAngleZ ()

Returns the value of the fromAngleZ property of this transition if it is set.

A valid value is returned if the fromAngleZSet property is set to true, otherwise the default value of 0 is returned.

Return:

The value of fromAngleZ attribute if specified, 0 otherwise.

Since:

BlackBerry 10.0.0

bool isFromAngleZSet ()

Indicates whether the fromAngleZSet property of the transition is set.

Return:

true the fromAngleZSet property is set, false otherwise.

Since:

BlackBerry 10.0.0

bool isToAngleZSet ()

Indicates whether the toAngleZSet property of the transition is set.

Return:

true the toAngleZSet property is set, false otherwise

Since:

BlackBerry 10.0.0

Q_SLOT void resetFromAngleZ ()

Resets the fromAngleZ property to its default value of 0.

Once reset, the property is marked as unset from the point of view of the transition. Resetting this property will also change the value of fromAngleZSet property to false.

Since:

BlackBerry 10.0.0

Q_SLOT void resetToAngleZ ()

Resets the toAngleZ property to its default value of 0.

Once reset, the property is marked as unset from the point of view of the transition. Resetting this property will also change the value of toAngleZSet property to false.

Since:

BlackBerry 10.0.0

Q_SLOT void setFromAngleZ (
  • floatvalue)

Sets the fromAngleZ property of this transition.

Setting a value of the property will also change the value of fromAngleZSet property to true.

Parameters
value

the new value of fromAngleZ attribute

Since:

BlackBerry 10.0.0

Q_SLOT void setToAngleZ (
  • floatvalue)

Sets the toAngleZ property of this transition.

Setting a value of the property will also change the value of the toAngleZSet property to true.

Parameters
value

the new value of toAngleZ attribute

Since:

BlackBerry 10.0.0

float toAngleZ ()

Returns the value of toAngleZ property of this transition if it is set.

A valid value is returned if the toAngleZSet property is set to true, otherwise the default value of 0 is returned.

Return:

The value of toAngleZ attribute if specified, 0 otherwise.

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

int duration ()Inherited

Returns the duration of this transition.

Return:

A positive number indicating the duration of the transition, in milliseconds.

Since:

BlackBerry 10.0.0

QVariant easingCurve ()Inherited

Returns a QVariant containing the easingCurve for the transition.

Return:

A QVariant containing current easing curve for this transition.

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_INVOKABLE void resetDuration ()Inherited

Resets the duration property to its default value of 300 milliseconds.

Since:

BlackBerry 10.0.0

Q_INVOKABLE void resetEasingCurve ()Inherited

Resets the easingCurve to its default value of StockCurve::CubicIn.

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

Q_SLOT void setDuration (
  • intduration)
Inherited

Sets the duration for the transition, in millseconds.

Passed argument must be non-negative or it is ignored. A duration of 0 indicates an instantaneous transition.

Parameters
duration

A non-negative value in milliseconds.

Since:

BlackBerry 10.0.0

Q_SLOT void setEasingCurve (Inherited

Sets the value of the easingCurve for the transition.

The passed value must be an EasingCurve or one of its subclasses, or the passed value will be ignored and a warning will be printed on the console.

Parameters
curve

A derivative of EasingCurve.

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 with an optional explicit target.

Using the builder to create the transition:

Slider *slider = Slider::create();
RotateTransition *transition = RotateTransition::create(slider)
    .fromAngleZ(90)
    .toAngleZ(270)
    .duration(1000);
transition->play();
Parameters
target

An optional explicit target for the transition.

Return:

A builder for creating the transition.

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

void fromAngleZChanged (
  • floatfromAngleZ)

Emitted when the fromAngleZ property of the transition changes.

Parameters
fromAngleZ

The new fromAngleZ for the transition.

Since:

BlackBerry 10.0.0

void toAngleZChanged (
  • floattoAngleZ)

Emitted when the toAngleZ of the transition changes.

Parameters
toAngleZ

The new toAngleZ for the transition.

Since:

BlackBerry 10.0.0

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 durationChanged (
  • intduration)
Inherited

Emitted when the duration of the transition changes.

Parameters
duration

The new duration for the transition.

Since:

BlackBerry 10.0.0

void easingCurveChanged (Inherited

Emitted when the easingCurve of the transition changes.

Parameters
easingCurve

The new easingCurve for the transition.

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