Image

Images can come from a number of different sources, the most common of which is as an asset that is packaged with the application. This is the type of image that is commonly used in the user interface.

One of the benefits of packaging an image with the application is that it allows the tool to verify the images and optimize them for the devices they are targeting. Because they are packaged with the application, it should be assumed that they are instantly available, and should never fail to load. If an incorrect name is provided when an asset is created, an null image is returned.

As long as the image is placed in the assets folder in your project, you can refer to it using a relative path to the assets directory (asset:///) followed by the file name. For example:

Image imageAsset = Image(QUrl("asset:///myasset.png"));

The absolute path to the assets directory is file:///app_working_directory/app/native.

Each application has access to its own working directory in the file system. The working directory is where application is started, and is also known as the "current directory" and the "sandbox."

Within the application working directory, there are a number of folders that your application has access to. The data folder (otherwise known as the "home" directory) contains your application's private data. Here's an example of how to use a path relative to the application working directory to load an image from the home directory:

Image image = Image(QUrl("file://" + QDir::homePath() + "/image2.png"));

Your application can also access folders outside the application working directory, in a shared folder. Here's an example of how to load an image from the shared/camera folder (provided that you set the appropriate permissions for it in your bar-descriptor.xml file). In this example, an absolute path is used:

Image image = Image(QUrl("file:///accounts/1000/shared/camera/camera0001.jpg"));

Here are some examples of how to use an Image in QML:

ImageView {
    imageSource: "asset:///myAsset.png"
}

Button {
    imageSource: "images/button.png"
}
   
ImageTracker {
    id: anImage
    imageSource: "asset:///myAsset.png"
}
   
ImageView {
    image: anImage.image
}

When dealing with images that are not assets (i.e. not packaged with the application), it should be assumed that the image might take a considerable time to load, or may not load at all. To account for this, an Image goes through a series of states indicating when the image is loaded and if an error occurred. The state of an image and information about its size are accessible through ImageTracker, which encapsulates the asynchronous parts of the Image.

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

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

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

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

void MyApp::onStateChanged(ResourceTracker::State state)
{
    if(state == ResourceTracker::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
            imageSource: "images/image.png"
       
            onStateChanged: { 
                if (state == ResourceTracker.Loaded)
                {
                    myImageView.image = tracker.image
                }
            }
        }
    ]
}

It's also possible to create images from raw pixel data using ImageData::fromPixels(). In order to create the image from a set of data, all you need to specify is the source of the data, the format of the pixel data (as specified by PixelFormat), the width and height of the image, and the number of bytes per line in the data source.

Here's an example of how to create an image from a random set of pixel data. The pixel format used is RGBX.

int data[8][8];
for (int y=0;y<8;y++) {
    for (int x=0;x<8;x++) {
        data[x][y] = rand();
    }
}
Image m_image = bb::ImageData::fromPixels((
        const unsigned char*)data, 
        bb::PixelFormat::RGBX, 
        8, 8, 8*4);

Image resources can be specified to have nine-slice margins, which can be retrieved using the nineSliceMargin*() methods. A nine-sliced image will, when displayed, be stretched according to nine-slice rules instead of being simply scaled.

sliceMargins: l r t b

#RimCascadesAssetMetaData version=1.0
source: "nine_sliced_background.png"
sliceMargins: 63 62 51 123

In your application, you simply reference the .amd file instead of the image and whenever it's scaled the image will maintain its edges.

ImageView {
    imageSource: "asset:///nine_sliced_background.amd"
    preferredWidth: 500
    preferredHeight: 500
}

In the metadata file, lines beginning with '#' are ignored, and can be used for comments.

Using the ImagePaint (C++) and ImagePaintDefinition (QML) classes you can use images as background fill for a container. The RepeatPattern class determines how/if the image is tiled on the container.

In order for an image to be tileable, it must have the "repeatable: true|false" property set in the asset metadata file. This is the same .amd file that can contain nine-slicing attributes, however the tiling of nine-sliced images is not currently supported.