A definition of an ImagePaint to use as a background image.

This class is used to define an ImagePaint in QML, which is typically used to add background images to containers.

An ImagePaintDefinition has no visual representation and you therefore have to add it as an attached object. To actually set the background property of a container, you must use the imagePaint property. To specify how and if the image should be repeated over the surface, set the repeatPattern property.

The provided image must have the power of two dimensions in order to be tileable (for example, 4x4, 8x8, 16x16, 32x32, 64x64, 128x128, 256x256, 128x64, 32x16). If image has dimensions that are not to the power of two, the paint will not be rendered and a warning will be printed out to the console.

The image also needs to have the "repeatable: true|false" property set in the asset metadata file. The asset metadata file is an .amd file with the same name as the image itself. This file can also contain nine-slicing attributes, however the tiling of nine-sliced images is not currently supported.

Here's an example of an .amd file called tiled_image.amd that has the repeatable property set to true.

 #RimCascadesAssetMetaData version=1.0
 source: "tiled_image.png"
 repeatable: true

When referencing the image from your application, you reference the .amd file instead of the image itself. Here's an example of how to tile the background image in a container:

 Container {
     id: rootContainer
     background: back.imagePaint
     attachedObjects: [
         ImagePaintDefinition {
             id: back
             repeatPattern: RepeatPattern.XY
             imageSource: "asset:///tiled_image.amd"

And here's how to do the same, but this time using an image tracker.

 Container {
     id: rootContainer
     background: back.imagePaint
     attachedObjects: [
         ImagePaintDefinition {
             id: back
             repeatPattern: RepeatPattern.XY
             image: tracker.image
         ImageTracker {
             id: tracker
             imageSource: "asset:///tiled_image.amd"
See also:





QML properties

image: bb::cascades::Image
imagePaint: bb::cascades::ImagePaint [read-only]
imageSource: QUrl
repeatPattern: bb::cascades::RepeatPattern::Type
objectName: QStringInherited
parent: QObject [read-only]Inherited

Public Functions Index

Imageimage () const
ImagePaintimagePaint () const
QUrlimageSource () const
bb::cascades::RepeatPattern::TyperepeatPattern () const
Q_SLOT voidresetImage ()
Q_SLOT voidresetImageSource ()
Q_SLOT voidresetRepeatPattern ()
Q_SLOT voidsetImageSource (const QUrl &source)
Q_SLOT voidsetRepeatPattern (bb::cascades::RepeatPattern::Type pattern)
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

voidimageChanged (const bb::cascades::Image &image)
voidimagePaintChanged (const bb::cascades::ImagePaint &imagePaint)
voidimageSourceChanged (const QUrl &source)
voidrepeatPatternChanged (bb::cascades::RepeatPattern::Type newRepeatPattern)
voidcreationCompleted ()Inherited
voidobjectNameChanged (const QString &objectName)Inherited


QVariant image

A property containing the image to be used as paint data.

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

If a null image is set or the property is reset the imagePaint property will be set to a null paint.

The default value of this property is a null image.

QVariant imagePaint[read-only]

A read-only property containing the image paint this definition exposes.

If no image paint is set, a null QVariant will be returned. This property changes in response to imageSource or image property being changed.

The imagePaintChanged() signal is emitted when this property changes.

QUrl imageSource

The location of an image to use as paint data.

See also:


bb::cascades::RepeatPattern::Type repeatPattern


Specifies the repeat pattern to be used for the ImagePaint.

The default pattern is RepeatPattern::Fill.

See also:


QString objectNameInherited

This property is overridden from QObject.

See also:



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.


BlackBerry 10.0.0

Public Functions

Image image ()

Returns the ImagePaint associated with the paint definition.


The image paint of the paint definition.

ImagePaint imagePaint ()

Returns the ImagePaint that is associated with the paint definition.


The image paint of the paint definition.

QUrl imageSource ()

Returns the image source.


The source of the displayed image.

bb::cascades::RepeatPattern::Type repeatPattern ()

Returns the associated repeat pattern.


The repeat pattern of the paint.

Q_SLOT void resetImage ()

Resets the image to use to the default value of null image.

Other properties are updated accordingly.

Q_SLOT void resetImageSource ()

Resets the image source to the default value of null QUrl Other properties are updated accordingly.

Q_SLOT void resetRepeatPattern ()

Resets the pattern to use to the default value, which is RepeatPattern:Fill.

Q_SLOT void setImageSource (

Sets the image to use as paint.

This function emits imageChanged() and imageSourceChanged() signals if the currently set image source changes.

An invalid QUrl indicates no image.


The image url.

Q_SLOT void setRepeatPattern (

Sets the pattern to use for this paint.


The pattern to use.

void setObjectName (Inherited

Sets the objectName property.


The new name for the object.


BlackBerry 10.0.0

virtual Q_INVOKABLE QString toDebugString ()Inherited

Returns a debug string representing this object.


A debug string for the object.


BlackBerry 10.0.0

Protected Functions

(Only has inherited protected functions)

BaseObject (Inherited

Constructs an instance of BaseObject's subclass.


An optional parent, defaults to 0.


BlackBerry 10.0.0


void imageChanged (

Emitted when the image used as source for the paint has changed.


The new Image.

void imagePaintChanged (

Emitted when the image paint has changed.


The new ImagePaint.

void imageSourceChanged (

Emitted when the image source has changed.


New image source.

void repeatPatternChanged (

Emitted when the repeatPattern property changes.


Due to a work around for a Qt Core issue with accessing enums from QML the argument of this signal doesn't follow naming convention for signals in which the signal arguments are typically named to match the associated property's name. Use the object's property to access current property value instead of the signal argument to avoid runtime errors (i.e. use repeatPattern instead of newRepeatPattern).


the new repeat pattern.

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:



BlackBerry 10.0.0

void objectNameChanged (Inherited

This signal is emitted when the objectName property is changed.


BlackBerry 10.0.0

Last modified: 2015-03-26

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

comments powered by Disqus