Dali 3D User Interface Engine
Image Views

Overview

The Dali::Toolkit::ImageView inherits from Dali::Toolkit::Control and provide means to display resources like Images on the stage.

Image View

Construction

The Image View is constructed by passing a Dali::Image object or by a url path.

Loading from a url path

Image View will load a file from a given url path. Using a url path is the prefered way of displaying an image as the Dali engine can do optimsations to reuse shaders and perform automatic image atlassing.
This can be a path to a image file:

Dali::Toolkit::ImageView myImageView = ImageView::New( "source-image-url.png" );

A path to a nine-patch/n-patch image file:

Dali::Toolkit::ImageView myImageView = ImageView::New( "source-image-url.9.png" );

Loading from a Image handle

Dali::Image is an abstract base class with multiple derived classes.

The IMAGE property

the IMAGE property allows you to change many aspects of the image that is renderered. This property can either be a string for a image url path or a Property::Map that specifies the image in more detail.

Renderers

You can specify a specific renderer instead of using the default Image Renderer, e.g to use the Border Renderer.

Property::Map renderer;
renderer.Insert("rendererType","border");
renderer.Insert("borderColor",COLOR::RED);
renderer.Insert("borderSize",20.f);
myImageView.SetProperty( Control::Property::IMAGE, renderer);

Resizing at Load Time

An application loading images from an external source will often want to display those images at a lower resolution than their native ones. To support this, DALi can resize an image at load time so that its in-memory copy uses less space and its visual quality benefits from being prefiltered. There are four algorithms which can be used to fit an image to a desired rectangle, a desired width or a desired height (see Dali::FittingMode).

Here is an example doing rescaling:

Property::Map imageProperty;
imageProperty.Insert("imageUrl", "source-image-url.png");
imageProperty.Insert("imageFittingMode", "scaleToFill");
imageProperty.Insert("fitWidth", 240);
imageProperty.Insert("fitHeight", 240);
myImageView.SetProperty( Control::Property::IMAGE, imageProperty);

This example sets the size and fitting mode appropriately for a large thumbnail during Dali::ResourceImage construction. In general, to enable scaling on load, pass a non-zero width or height and one of the four fitting modes to the Dali::ResourceImage creator function as shown above.

The fitting modes and a suggested use-case for each are as follows:

  1. "shrinkToFit" Full-screen image display: Limit loaded image resolution to device resolution but show all of image.
  2. "scaleToFill" Thumbnail gallery grid: Limit loaded image resolution to screen tile, filling whole tile but losing a few pixels to match the tile shape.
  3. "fitWidth" Image columns: Limit loaded image resolution to column.
  4. "fitHeight" Image rows: Limit loaded image resolution to row height.

The dali-demo project contains a full example under examples/image-scaling-and-filtering and a specific sampling mode example under examples/image-scaling-irregular-grid.

There are more details on this topic in the Rescaling Images section.

Style

The Actor can render an image in only as a quad or as a nine-patch/n-patch image. This is done by using a nine-patch filename naming scheme of ending with a ".9" or a ".#". There is no special treatment if the file encodes a nine-patch image or n-patch image as long as it has either ".9" or ".#" the image will be correctly loaded.

Dali::Toolkit::ImageView myImageView1 = Dali::Toolkit::ImageView::New("source-to-nine-patch-image.9.png");
Dali::Toolkit::ImageView myImageView2 = Dali::Toolkit::ImageView::New("source-to-nine-patch-image.#.png");

Changing the image

The Image View can be changed by calling Dali::Toolkit::ImageView::SetImage methods or by changing the IMAGE property.

myImageActor.SetImage( newImage );
Dali Docs Home
Read more about Dali