ImageTracker

#include <bb/cascades/ImageTracker>

Provides access to state and size changes associated with an Image.

Since Image objects are often loaded or modified at runtime, ImageTracker can be used to verify whether they are loaded correctly.

Since the Cascades framework is asynchronous in nature, the state and size of an Image may be unknown when the image tracker is created. It's therefore recommended to listen to the stateChanged(), sizeChanged(), heightChanged(), and widthChanged() signals.

Here's an example in C++ showing how to load an image and display it when it is successfully loaded:

void MyApp::setup() {
    mImageView = new ImageView();
    mImageTracker = new ImageTracker(QUrl("assets/image.png"));

    bool result = connect(mImageTracker,
        SIGNAL(stateChanged(bb::cascades::ResourceState::State)),
        this,
        SLOT(onStateChanged(bb::cascades::ResourceState::State)));

    Q_ASSERT(result);
    Q_UNUSED(result);
  
    // ...
}

void MyApp::onStateChanged(ResourceState::State state)
{
    if(state == ResourceState::Loaded)
    {
        mImageView->setImage(mImageTracker->image());
    }
}

Here's an example in QML showing how to load an image and display it when it is successfully loaded:

ImageView {
    id: myImageView
    attachedObjects: [
        ImageTracker {
            id: tracker
            image: "images/image.png"
      
            onStateChanged: { 
                if (state == ResourceState.Loaded)
                {
                    myImageView.image = tracker.image
                }
            }
        }
    ]
}

Since:

BlackBerry 10.0.0

Inheritance

bb::cascades::BaseObject
bb::cascades::ResourceTracker
bb::cascades::ImageTracker

QML properties

image: bb::cascades::Image
imageSource: QUrl
width: int [read-only]
height: int [read-only]
nineSliceMarginLeft: int [read-only]
nineSliceMarginTop: int [read-only]
nineSliceMarginRight: int [read-only]
nineSliceMarginBottom: int [read-only]
objectName: QStringInherited
parent: QObject [read-only]Inherited
state: bb::cascades::ResourceState::Type [read-only]Inherited

Properties Index

QVariantimage
QUrlimageSource
intwidth [read-only]
intheight [read-only]
intnineSliceMarginLeft [read-only]
intnineSliceMarginTop [read-only]
intnineSliceMarginRight [read-only]
intnineSliceMarginBottom [read-only]
QStringobjectNameInherited
QObjectparent [read-only]Inherited
bb::cascades::ResourceState::Typestate [read-only]Inherited

Public Functions Index

ImageTracker (QObject *parent=0)
ImageTracker (const QUrl &source, QObject *parent=0)
virtual ~ImageTracker ()
voidsetImageSource (const QUrl &source)
QUrlimageSource () const
voidsetImage (const Image &image)
Imageimage () const
intwidth () const
intheight () const
intnineSliceMarginLeft () const
intnineSliceMarginRight () const
intnineSliceMarginTop () const
intnineSliceMarginBottom () const
Q_INVOKABLE boolhasErrors () const Inherited
voidsetObjectName (const QString &name)Inherited
bb::cascades::ResourceState::Typestate () const Inherited
virtual Q_INVOKABLE QStringtoDebugString () const Inherited

Protected Functions Index

Only has inherited protected functions

BaseObject (QObject *parent=0)Inherited

Signals Index

voidimageChanged (const QVariant &image)
voidimageSourceChanged (const QUrl &source)
voidsizeChanged (int width, int height)
voidwidthChanged (int width)
voidheightChanged (int height)
voidnineSliceMarginsChanged (int left, int right, int top, int bottom)
voidnineSliceMarginLeftChanged (int margin)
voidnineSliceMarginTopChanged (int margin)
voidnineSliceMarginRightChanged (int margin)
voidnineSliceMarginBottomChanged (int margin)
voidcreationCompleted ()Inherited
voidobjectNameChanged (const QString &objectName)Inherited
voidstateChanged (bb::cascades::ResourceState::Type newState)Inherited

Properties

QVariant image

A read only property containing the tracked Image.

If no image is being tracked, an empty QVariant will be returned. Writing to this property will change the tracked image and emit the imageChanged() and imageSourceChanged() signals.

Since:

BlackBerry 10.0.0

QUrl imageSource

The source of the tracked Image.

Writing to this property will change the tracked image and emit the imageChanged() and imageSourceChanged() signals.

If no image is tracked this property will be read as an empty string.

Since:

BlackBerry 10.0.0

int width[read-only]

A read only property containing the image width.

Writing to this property will cause the widthChanged() and sizeChanged() signals to be emitted.

If the width is unknown a width of 0 is returned.

Since:

BlackBerry 10.0.0

int height[read-only]

Read only property holding the image height.

Writing to this property will cause the heightChanged() and sizeChanged() signals to be emitted.

If the height is unknown a height of 0 is returned.

Since:

BlackBerry 10.0.0

int nineSliceMarginLeft[read-only]

Read only property holding the left nine-slice margin of the image.

The value is not guaranteed to be valid until the nineSliceMarginsChanged or nineSliceMarginLeftChanged signal is emitted. If the margin is unknown, or if the image is not a nine-slice image a value of 0 is returned.

See Image for more information about nine-slice margins.

Since:

BlackBerry 10.0.0

int nineSliceMarginTop[read-only]

Read only property holding the right nine-slice margin of the image.

The value is not guaranteed to be valid until the nineSliceMarginsChanged or nineSliceMarginTopChanged signal is emitted. If the margin is unknown, or if the image is not a nine-slice image a value of 0 is returned.

See Image for more information about nine-slice margins.

Since:

BlackBerry 10.0.0

int nineSliceMarginRight[read-only]

Read only property holding the top nine-slice margin of the image.

The value is not guaranteed to be valid until the nineSliceMarginsChanged or nineSliceMarginTopChanged signal is emitted. If the margin is unknown, or if the image is not a nine-slice image a value of 0 is returned.

See Image for more information about nine-slice margins.

Since:

BlackBerry 10.0.0

int nineSliceMarginBottom[read-only]

Read only property holding the bottom nine-slice margin of the image.

The value is not guaranteed to be valid until the nineSliceMarginsChanged or nineSliceMarginBottomChanged signal is emitted. If the margin is unknown, or if the image is not a nine-slice image a value of 0 is returned.

See Image for more information about nine-slice margins.

Since:

BlackBerry 10.0.0

QString objectNameInherited

This property is overridden from QObject.

As the objectName property is overridden from the QObject class, this signal will not be emitted if setObjectName() function is called directly on QObject.

The default value of this property is QString::null.

See:

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

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

The current state for the resource.

Default state is Unknown.

When the state changes, the stateChanged() signal will be emitted.

Since:

BlackBerry 10.0.0

Public Functions

ImageTracker (

Constructs an image tracker without a tracked object. 

ImageTracker *imageTracker = new ImageTracker(parent);
Parameters
parent

The parent of this object.
Since:

BlackBerry 10.0.0

ImageTracker (

Constructs an image with the tracked image source. 

ImageTracker *imageTracker = new ImageTracker("a_image.png", parent);
Parameters
source

The source of this object.

parent

The parent of this object.
Since:

BlackBerry 10.0.0

virtual~ImageTracker ()

Destructor.

void setImageSource (

Sets an image to be tracked.

If an image is already being tracked, the new image will replace the current image and cause the imageSourceChanged() signal to be emitted.

Parameters
source

The image source to track.
Since:

BlackBerry 10.0.0

QUrl imageSource ()

Returns the source of the tracked image.

If no image is being tracked an empty QString will be returned.

Return:

The source of the tracked image.

Since:

BlackBerry 10.0.0

void setImage (

Sets an image to be tracked.

If an image is already being tracked, the new image will replace the current image and cause the imageChanged() signal to be emitted.

Parameters
image

The image to track.
Since:

BlackBerry 10.0.0

Image image ()

Returns the tracked image.

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

Return:

The tracked image, or a null image if no image is being tracked.

Since:

BlackBerry 10.0.0

int width ()

Returns the width in pixels.

Return:

The width in pixels if available, otherwise 0.

Since:

BlackBerry 10.0.0

int height ()

Returns the height in pixels.

Return:

The height in pixels if available, otherwise 0.

Since:

BlackBerry 10.0.0

int nineSliceMarginLeft ()

Returns the left nine-slice margin of the current image.

If the image is empty, or if the image is not a nine-slice image, all nine-slice margins are 0.

Return:

The left nine-slice margin of the current image, or 0 if the image is empty, or not a nine-slice image.

Since:

BlackBerry 10.0.0

int nineSliceMarginRight ()

Returns the right nine-slice margin of the current image.

If the image is empty, or if the image is not a nine-slice image, all nine-slice margins are 0.

Return:

The right nine-slice margin of the current image, or 0 if the image is empty, or not a nine-slice image.

Since:

BlackBerry 10.0.0

int nineSliceMarginTop ()

Returns the top nine-slice margin of the current image.

If the image is empty, or if the image is not a nine-slice image, all nine-slice margins are 0.

Return:

The top nine-slice margin of the current image, or 0 if the image is empty, or not a nine-slice image.

Since:

BlackBerry 10.0.0

int nineSliceMarginBottom ()

Returns the bottom nine-slice margin of the current image.

If the image is empty, or if the image is not a nine-slice image, all nine-slice margins are 0.

Return:

The bottom nine-slice margin of the current image, or 0 if the image is empty, or not a nine-slice image.

Since:

BlackBerry 10.0.0

Q_INVOKABLE bool hasErrors ()Inherited

Determines whether the resource is in one of the error states.

Return:

true if the image is in any error state, false otherwise.

See:

ResourceTracker::State

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

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

Returns the current resource state.

Return:

Current resource state.

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 imageChanged (

Emitted when the tracked image has changed.

Parameters
image

QVariant containing the new Image.
Since:

BlackBerry 10.0.0

void imageSourceChanged (

Emitted when the tracked source has changed.

Parameters
source

New image source.
Since:

BlackBerry 10.0.0

void sizeChanged (
  • intwidth,
  • intheight )

Emitted when the size has changed.

For example, this will happen when the tracked image is changed.

Parameters
width

The width of the loaded image in pixels.

height

The height of the loaded image in pixels.
Since:

BlackBerry 10.0.0

void widthChanged (
  • intwidth)

Emitted when the width has changed.

For example, this will happen when the tracked image is changed.

Parameters
width

The width of the loaded image in pixels.
Since:

BlackBerry 10.0.0

void heightChanged (
  • intheight)

Emitted when the height has changed.

For example, this will happen when the tracked image is changed.

Parameters
height

The height of the loaded image in pixels.
Since:

BlackBerry 10.0.0

void nineSliceMarginsChanged (
  • intleft,
  • intright,
  • inttop,
  • intbottom )

Emitted when the nine-slice margins have been changed.

This will for example happen when the tracked image is changed.

Parameters
left

The left nine-slice margin of the loaded image in pixels

right

The right nine-slice margin of the loaded image in pixels

top

The top nine-slice margin of the loaded image in pixels

bottom

The bottom nine-slice margin of the loaded image in pixels
Since:

BlackBerry 10.0.0

void nineSliceMarginLeftChanged (
  • intmargin)

Emitted when the left nine-slice margins has changed.

This will for example happen when the tracked image is changed.

Parameters
margin

The left nine-slice margin of the loaded image in pixels
Since:

BlackBerry 10.0.0

void nineSliceMarginTopChanged (
  • intmargin)

Emitted when the top nine-slice margins has changed.

This will for example happen when the tracked image is changed.

Parameters
margin

The top nine-slice margin of the loaded image in pixels
Since:

BlackBerry 10.0.0

void nineSliceMarginRightChanged (
  • intmargin)

Emitted when the right nine-slice margins has changed.

This will for example happen when the tracked image is changed.

Parameters
margin

The right nine-slice margin of the loaded image in pixels
Since:

BlackBerry 10.0.0

void nineSliceMarginBottomChanged (
  • intmargin)

Emitted when the bottom nine-slice margins has changed.

This will for example happen when the tracked image is changed.

Parameters
margin

The bottom nine-slice margin of the loaded image in pixels
Since:

BlackBerry 10.0.0

void creationCompleted ()Inherited

This signal is emitted only when this object is instantiated as a result of loading a QML document and creating the root node, or when an object is being constructed using its builder class.

This signal is emitted only 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 is emitted to indicate 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:

QmlDocument

Since:

BlackBerry 10.0.0

void objectNameChanged (Inherited

This signal is emitted when the objectName property is changed.

See:

QObject, BaseObject::objectName.

Since:

BlackBerry 10.0.0

void stateChanged (Inherited

Emitted when the state is changed for this resource.

Parameters
newState

The new state.
Since:

BlackBerry 10.0.0