Image views

An ImageView is a control used for displaying images.


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

You can specify an image by using an Image object that is packaged with the application 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'll 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'll need to prepend the path with file:// (eg "file:///accounts/<path_to_image>/<image_name>.<extension>") or your image won't load.

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.

Sizing

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: images.zip

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

main.qml

import bb.cascades 1.0
 
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: 0
                selected: true
            }
            Option {
                id: aspectfill
                text: "Aspect fill"
                value: 1
            }
            Option {
                id: fill
                text: "Fill"
                value: 2
            }
            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
        }
    }
}

ImageViewRecipe.h

#ifndef IMAGEVIEWRECIPE_H_
#define IMAGEVIEWRECIPE_H_

#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
{
    Q_OBJECT

public:

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

public slots:

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

private:

    Container *root;

    SegmentedControl *mySegmentedControl;
    ImageView *myImageView;

};

#endif /* IMAGEVIEWRECIPE_H_ */

ImageViewRecipe.cpp

#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())
                .top(20.0f);
 
    TitleBar *tbar = TitleBar::create().title("ImageView");
    page->setTitleBar(tbar);
 
    // 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()
            .add(bb::cascades::Option::create()
                .text("Aspect fit")
                .value(0)
                .selected(true))
            .add(bb::cascades::Option::create()
                .text("Aspect fill")
                .value(1))
            .add(bb::cascades::Option::create()
                .text("Fill")
                .value(2)); 
 
    // If any Q_ASSERT statement(s) indicate that the slot failed to connect to 
    // the signal, make sure you know exactly why this has happened. This is not
    // normal, and will cause your app to stop working
    bool connectResult;
     
    // Since the variable is not used in the app, this is added to avoid a 
    // compiler warning
    Q_UNUSED(connectResult);
     
    // Connect the selectedOptionChanged() signal to
    // the handleSelectedOptionChanged() slot
    connectResult = connect(mySegmentedControl, 
                      SIGNAL(selectedOptionChanged(bb::cascades::Option*)), 
                      this,
                      SLOT(handleSelectedOptionChanged(bb::cascades::Option*)));
                             
    // This is only available in Debug builds
    Q_ASSERT(connectResult);
                             
    myImageView = ImageView::create()
            .image(Image(QUrl("asset:///images/image_carl_larsson_1898.png")))
            .scalingMethod(ScalingMethod::AspectFit);
 
    root->add(mySegmentedControl);
    root->add(myImageView);
    page->setContent(root);
    app->setScene(page);
 
}

// 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:
        myImageView->setScalingMethod(ScalingMethod::AspectFit);
        break;
    case 1:
        myImageView->setScalingMethod(ScalingMethod::AspectFill);
        break;
    case 2:
        myImageView->setScalingMethod(ScalingMethod::Fill);
        break;
    }
}

main.cpp

#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();
}

Last modified: 2013-12-21

comments powered by Disqus