ImageAnimator

Since: BlackBerry 10.0.0

#include <bb/cascades/ImageAnimator>

A class that can be used to control the animation of an animated image (typically a .gif animation).

Here's how to use the image animator in C++:

 ImageView *iv = new ImageView();
 iv->setImageSource(QUrl("foo.gif"));
 ImageAnimator *ic = new ImageAnimator();
 ic->setAnimatedImage(iv->image()); // attach image
 ic->setStarted(true);

Here's how to use the image animator from QML:

 Container {
     ImageView {
         id: imageView
         imageSource: "foo.gif"
         attachedObjects: [
             ImageAnimator {
                 id: imageAnimator
                 animatedImage: imageView.image
                 started: true
             }
         ]
     }
 }


Overview

Inheritance

bb::cascades::BaseObject
bb::cascades::ImageAnimator

QML properties

animatedImage: bb::cascades::Image
playing: bool
running: bool [read-only]
started: bool
objectName: QStringInherited
parent: QObject [read-only]Inherited

Properties Index

QVariantanimatedImage
boolplaying
boolrunning [read-only]
boolstarted
QStringobjectNameInherited
QObjectparent [read-only]Inherited

Public Functions Index

ImageAnimator (QObject *parent=0)
virtual ~ImageAnimator ()
bb::cascades::ImageanimatedImage () const
boolisPlaying () const
boolisRunning () const
boolisStarted () const
Q_SLOT voidresetAnimatedImage ()
Q_SLOT voidresetPlaying ()
Q_SLOT voidresetStarted ()
Q_SLOT voidsetAnimatedImage (const bb::cascades::Image &image)
Q_SLOT voidsetPlaying (bool playing)
Q_SLOT voidsetStarted (bool started)
Q_SLOT voidstart ()
Q_SLOT voidstop ()
Q_SLOT voidstopAt (bb::cascades::ImageAnimatorAnchor::Type anchor, bb::cascades::ImageAnimatorSeekMode::Type seekMode=bb::cascades::ImageAnimatorSeekMode::Default)
voidsetObjectName (const QString &name)Inherited
virtual Q_INVOKABLE QStringtoDebugString () const Inherited

Protected Functions Index

Only has inherited protected functions

BaseObject (QObject *parent=0)Inherited

Signals Index

voidanimatedImageChanged (const bb::cascades::Image &animatedImage)
voidplayingChanged (bool playing)
voidrunningChanged (bool running)
voidstartedChanged (bool started)
voidcreationCompleted ()Inherited
voidobjectNameChanged (const QString &objectName)Inherited

Properties

QVariant animatedImage

The image that the animator is currently controlling.

Since:

BlackBerry 10.0.0

bool playing

Specifies whether the attached image should animate or not.

This property is deprecated in favor of the started property

Deprecated

Use the started property instead

Since:

BlackBerry 10.0.0

bool running[read-only]

A read-only property that specifies whether the attached image is currently animating or not.

When this property is changed the runningChanged() signal will be emitted.

Due to the asynchronous nature of Cascades, changing the started property or invoking play(), stop() or stopAt() will not change this property immediately. This property will only be changed after the image has actually stopped animating.

Since:

BlackBerry 10.0.0

bool started

Specifies whether the attached image should animate or not.

Changing this property informs the attached image to start or stop playing, and emits the startedChanged() signal.

Setting this property to true has the same effect as invoking play(). Setting it to false has the same effect as invoking stop() or stopAt(ImageAnimatorAnchor::CurrentFrame, ImageAnimatorSeekMode::Immediate). Invoking play(), stop() or stopAt() will change this property immediately.

When an ImageAnimator is created, this property will have the value false, which means that any image attached to an unaltered animator will pause.

Due to the asynchronous nature of Cascades this property does not indicate whether the attached image is currently animating or not, but rather, if the image has been informed that it should animate or not. The running property can be used to find out if the currently attached image is actually animating.

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

Public Functions

ImageAnimator (

Constructs an ImageAnimator.

Parameters
parent

The parent of this object.

Since:

BlackBerry 10.0.0

virtual~ImageAnimator ()

Destructor.

bb::cascades::Image animatedImage ()

Returns the currently attached image.

If no image is attached a null image will be returned.

Return:

The currently attached image, or a null image if no image is being animated.

Since:

BlackBerry 10.0.0

bool isPlaying ()

Returns the started state of the animator.

Deprecated

in favor of isStarted()

Return:

The started state of the animator.

Since:

BlackBerry 10.0.0

bool isRunning ()

Returns the running state of the animator.

Return:

The running state of the animator.

Since:

BlackBerry 10.0.0

bool isStarted ()

Returns the started state of the animator.

Return:

The started state of the animator.

Since:

BlackBerry 10.0.0

Q_SLOT void resetAnimatedImage ()

Resets the attached image to a null image.

This will detach the currently attached image and attach a null image to the animator.

Since:

BlackBerry 10.0.0

Q_SLOT void resetPlaying ()

Resets the started state of the animator.

Deprecated

in favor of resetStarted().

Since:

BlackBerry 10.0.0

Q_SLOT void resetStarted ()

Stops the animation by resetting the started state to false.

Since:

BlackBerry 10.0.0

Q_SLOT void setAnimatedImage (

Sets an image on the animator.

When this function is called, the started state of the animator will be pushed to the image. The running state of the image will be pushed to the animator.

An image can only be attached to one animator. If the image was already attached to an animator when this method is called, the image is detached from the old animator and attached to this one. A null image will be attached to the old animator.

When attaching a new image to an animator, the old image does not lose the started state that was pushed to it by the animator, but you cannot control it any longer with the animator.

Parameters
image

to attach to the animator

Since:

BlackBerry 10.0.0

Q_SLOT void setPlaying (
  • boolplaying)

Sets the started state of the animator.

Deprecated

in favor of setStarted()

Parameters
playing

true to start the animation, false to stop it.

Since:

BlackBerry 10.0.0

Q_SLOT void setStarted (
  • boolstarted)

Sets the started state of the animator.

Parameters
started

If true the animation is started and if false the animation is stopped.

Since:

BlackBerry 10.0.0

Q_SLOT void start ()

Starts the animation of the attached image.

Calling this function has the same effect as calling setStarted(true).

Since:

BlackBerry 10.0.0

Q_SLOT void stop ()

Stops the animation of the attached image.

Calling this function has the same effect as calling setStarted(false).

Since:

BlackBerry 10.0.0

Q_SLOT void stopAt (

Stops the animation of the attached image in a specified way.

This function can be used to stop the animation of the attached image at specific points in the animation.

How to use this function and how it relates to the started and running properties is illustrated in the following examples:

Example 1:
  1. Invoke stopAt(ImageAnimatorAnchor::CurrentFrame, ImageAnimatorSeekMode::Immediate) or invoke stopAt(ImageAnimatorAnchor::CurrentFrame, ImageAnimatorSeekMode::Animate) while animation is running.

  2. startedChanged(false) will be emitted immediately.

  3. Cascades will stop the animation as soon as possible on the frame the animation is currently on and then runningChanged(false) will be emitted.

Example 2:
  1. Invoke stopAt(ImageAnimatorAnchor::FirstFrame, ImageAnimatorSeekMode::Immediate) while animation is running.

  2. startedChanged(false) will be emitted immediately.

  3. Cascades will stop the animation as soon as possible, jumping to the first frame of the image animation and then runningChanged(false) will be emitted.

Example 3:
  1. Invoke stopAt(ImageAnimatorAnchor::LastFrame, ImageAnimatorSeekMode::Immediate) while animation is running.

  2. startedChanged(false) will be emitted immediately.

  3. Cascades will stop the animation as soon as possible, jumping to the first frame of the image animation and then runningChanged(false) will be emitted.

Example 4:
  1. Invoke stopAt(ImageAnimatorAnchor::FirstFrame, ImageAnimatorSeekMode::Animate) while animation is running.

  2. startedChanged(false) will be emitted immediately.

  3. Cascades will continue to run the animation until the first frame is shown, at which point runningChanged(false) will be emitted.

Example 5:
  1. Invoke stopAt(ImageAnimatorAnchor::LastFrame, ImageAnimatorSeekMode::Animate) while animation is running.

  2. startedChanged(false) will be emitted immediately.

  3. Cascades will continue to run the animation until the last frame is shown, at which point runningChanged(false) will be emitted.

Example 6:
  1. Invoke stopAt(ImageAnimatorAnchor::FirstFrame, ImageAnimatorSeekMode::Animate) while animation is not running and the first frame is not currently showing.

  2. Cascades will emit runningChanged(true), run the animation until the first frame is shown, at which point runningChanged(false) will be emitted.

Example 7:
  1. Invoke stopAt(ImageAnimatorAnchor::LastFrame, ImageAnimatorSeekMode::Animate) while animation is not running and the last frame is not currently showing.

  2. Cascades will emit runningChanged(true), run the animation until the last frame is shown, at which point runningChanged(false) will be emitted.

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

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

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

Signals

void animatedImageChanged (

Emitted when the attached image changes.

Parameters
animatedImage

The new Image that was attached to the animator

Since:

BlackBerry 10.0.0

void playingChanged (
  • boolplaying)

Emitted when the started state of the animator changes.

Deprecated

in favor or startedChanged()

Parameters
playing

The new started state of the animator.

Since:

BlackBerry 10.0.0

void runningChanged (
  • boolrunning)

Emitted when the running state of the animator changes.

Parameters
running

The new running state of the animator.

Since:

BlackBerry 10.0.0

void startedChanged (
  • boolstarted)

Emitted when the started state of the animator changes.

Parameters
started

The new started state of the animator.

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 objectNameChanged (Inherited

This signal is emitted when the objectName property is changed.

Since:

BlackBerry 10.0.0

Last modified: 2014-09-30



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

comments powered by Disqus