Image views

An ImageView is a control that's used for displaying images.

You can specify an image by using an Image object that's packaged with the app or a path to the location of an image in the project.

Remote image paths (for example, "http://<domain>/<image_name>.<extension>") can't be used in an ImageView.

You need to pay close attention to the format of the file path you specify for an ImageView.

If you are specifying an image from the assets directory, the format is: “asset:///<folder>/<image_name>.<extension>.

If you specify an image from anywhere else in the file system, you need to prepend the path with file:// (for example, "file:///accounts/<path_to_image>/<image_name>.<extension>") or your image won't load.

Screens showing the Aspect Fill, Aspect Fit, and Fill image scaling methods.

The scalingMethod property can be used to define how an image is scaled to fit the ImageView. The available types are:

If an Image object or path is specified while the app is running, an implicit animation is triggered that causes the image to fade into view. You can use the loadEffect property to choose how an image is shown after loading.


Using images

In Cascades, you have two types of images: images that are assets (packaged with an app) and external images (generated by the app, or coming from other sources).

Typically, image assets are used for images that are used to build your UI (for example, backgrounds, icons, borders, and so on) because of the almost instant availability of the image. To learn how to use images that are packaged with your app, see Image assets.

External images are images that are downloaded remotely or generated by the app (for example, contact profile pictures, camera pictures, and so on). To learn how to use images that aren't packaged with your app, see External images.

Image view example

The following example uses a SegmentedControl to demonstrate the different scaling methods available for an ImageView. The SegmentedControl has three options: Aspect fit, Aspect fill, and Fill.

When the app starts, the default scaling method is AspectFit. Selecting either Aspect fill or Fill in the SegmentedControl changes the scaling method to the respective setting. Selecting Aspect fit resets the scaling method to its default.

You can download the images for the sample here:

Animation showing different scaling methods being applied to an image by selecting different options in a SegmentedControl.


import bb.cascades 1.3

Page {
    titleBar: TitleBar {
        title: "ImageView"
    Container { 
        // Create a SegmentedControl with 
        // three options corresponding to the different 
        // scaling methods available. The 'Aspect fit' 
        // option is selected by default when the app is 
        // started 
        SegmentedControl { 
            id: sc1 
            Option { 
                id: aspectfit 
                text: "Aspect fit" 
                value: ScalingMethod.AspectFit 
                selected: true 
            Option { 
                id: aspectfill 
                text: "Aspect fill" 
                value: ScalingMethod.AspectFill 
            Option { 
                id: fill 
                text: "Fill" 
                value: ScalingMethod.Fill 
            onSelectedOptionChanged: { 
                // Use the value of the selected option to 
                // select the scaling method enumeration 
                imageview1.scalingMethod = selectedOption.value; 
        // Create an ImageView and set the image source
        ImageView {
            id: imageview1
            horizontalAlignment: HorizontalAlignment.Center
            imageSource: "asset:///images/image_carl_larsson_1898.png"
            scalingMethod: ScalingMethod.AspectFit



#include <bb/cascades/Page>
#include <bb/cascades/Container>
#include <QObject>
#include <bb/cascades/SegmentedControl>
#include <bb/cascades/ImageView>

namespace bb { namespace cascades { class Application; }}

using namespace bb::cascades;

class ImageViewRecipe : public QObject


    ImageViewRecipe(bb::cascades::Application *app);
        virtual ~ImageViewRecipe() {}

public slots:

void handleSelectedOptionChanged
	(bb::cascades::Option *selectedOption);


    Container *root;

    SegmentedControl *mySegmentedControl;
    ImageView *myImageView;




#include "ImageViewRecipe.h"
#include <bb/cascades/Application>
#include <bb/cascades/Container>
#include <bb/cascades/StackLayout>
#include <bb/cascades/Page>
#include <bb/cascades/TitleBar>
#include <bb/cascades/SegmentedControl>
#include <bb/cascades/ImageView>
#include <bb/cascades/ScalingMethod>

using namespace bb::cascades;

ImageViewRecipe::ImageViewRecipe(bb::cascades::Application *app)
: QObject(app)
    // Create a Container and set the layout
    Page *page = new Page();

    root = Container::create()
                .layout(new StackLayout())

    TitleBar *tbar = TitleBar::create().title("ImageView");

    // Create a SegmentedControl with
    // three options corresponding to the different
    // scaling methods available. The 'Aspect fit'
    // option is selected by default when the app is
    // started
    mySegmentedControl = SegmentedControl::create()
                .text("Aspect fit")
                .text("Aspect fill")

    // If any Q_ASSERT statement(s) indicate that the slot failed to connect to
    // the signal, make sure you know exactly why this failure has happened.
    // This error is not normal and will cause your app to stop working
    bool connectResult;

    // Since the variable is not used in the app, this line is added to avoid a
    // compiler warning

    // Connect the selectedOptionChanged() signal to
    // the handleSelectedOptionChanged() slot
    connectResult = connect(mySegmentedControl,

    // The Q_ASSERT macro is only available in Debug builds

    myImageView = ImageView::create()



// Create the handleSelectedOptionChanged() slot
// to capture the selectedOptionChanged() signal emitted
// by the SegmentedControl
void ImageViewRecipe::handleSelectedOptionChanged
    (bb::cascades::Option *selectedOption)
    // Use a switch case to change the scaling method based
    // on the selected option.
    switch (selectedOption->value().toInt()) {
    case 0:
    case 1:
    case 2:


#include "ImageViewRecipe.h" 
#include <bb/cascades/Application>
#include <Qt/qdeclarativedebug.h>
using namespace bb::cascades;
Q_DECL_EXPORT int main(int argc, char **argv)
    Application app(argc, argv);
    new ImageViewRecipe(&app);
    return Application::exec();

Not applicable

Last modified: 2015-05-07

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

comments powered by Disqus