1 /*! \page image-view Image Views
4 * <h1 class="pg">Overview</h1>
5 * The Dali::Toolkit::ImageView inherits from Dali::Toolkit::Control and provide means to display resources like Images on the stage.<br>
7 * - <b>ImageView:</b> An actor for displaying Images. It allows the developer to display a Dali::Image object or an image from a url path on the stage.<br>
9 * <h1 class="pg">Image View</h1>
11 * <h2 class="pg">Construction</h2>
12 * The Image View is constructed by passing a Dali::Image object or by a url path.<br>
14 * <h3 class="pg">Loading from a url path</h3>
15 * 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
16 * reuse shaders and perform automatic image atlassing.<br>
17 * This can be a path to a image file:
19 * Dali::Toolkit::ImageView myImageView = ImageView::New( "source-image-url.png" );
22 * A path to a nine-patch/n-patch image file:
24 * Dali::Toolkit::ImageView myImageView = ImageView::New( "source-image-url.9.png" );
27 * <h3 class="pg">Loading from a Image handle</h3>
28 * Dali::Image is an abstract base class with multiple derived classes.
31 * Dali::Image image = BufferImage::New( 100, 100 );
32 * Dali::Toolkit::ImageView myImageView = Toolkit::ImageView::New( image );
35 * <h3 class="pg">The IMAGE property</h3>
36 * the IMAGE property allows you to change many aspects of the image that is renderered.
37 * This property can either be a string for a image url path or a Property::Map that specifies
38 * the image in more detail.
40 * <h3 class="pg">Renderers</h3>
41 * You can specify a specific renderer instead of using the default Image Renderer, e.g to use the Border Renderer.
44 * Property::Map renderer;
45 * renderer.Insert("rendererType","borderRenderer");
46 * renderer.Insert("borderColor",COLOR::RED);
47 * renderer.Insert("borderSize",20.f);
49 * Dali::Toolkit::ImageView myImageView = Dali::Toolkit::ImageView::New();
50 * myImageView.SetProperty( Control::Property::IMAGE, renderer);
53 * <h3 class="pg">Resizing at Load Time</h3>
54 * An application loading images from an external source will often want to
55 * display those images at a lower resolution than their native ones.
56 * To support this, DALi can resize an image at load time so that its
57 * in-memory copy uses less space and its visual quality benefits from being
59 * There are four algorithms which can be used to fit an image to a desired
60 * rectangle, a desired width or a desired height
61 * (see Dali::FittingMode).
63 * Here is an example doing rescaling:
66 * Property::Map imageProperty;
67 * imageProperty.Insert("imageUrl", "source-image-url.png");
68 * imageProperty.Insert("imageFittingMode", "scaleToFill");
69 * imageProperty.Insert("fitWidth", 240);
70 * imageProperty.Insert("fitHeight", 240);
71 * Dali::Toolkit::ImageView myImageView = Dali::Toolkit::ImageView::New();
72 * myImageView.SetProperty( Control::Property::IMAGE, imageProperty);
76 * This example sets the size and fitting mode appropriately for a large thumbnail
77 * during Dali::ResourceImage construction.
78 * In general, to enable scaling on load, pass a non-zero width or height and
79 * one of the four fitting modes to the Dali::ResourceImage creator function
82 * The fitting modes and a suggested use-case for each are as follows:
84 * <li> "shrinkToFit" Full-screen image display: Limit loaded image resolution to device resolution but show all of image.
85 * <li> "scaleToFill" Thumbnail gallery grid: Limit loaded image resolution to screen tile, filling whole tile but losing a few pixels to match the tile shape.
86 * <li> "fitWidth" Image columns: Limit loaded image resolution to column.
87 * <li> "fitHeight" Image rows: Limit loaded image resolution to row height.
90 * The dali-demo project contains a full example under
91 * <code>examples/image-scaling-and-filtering</code>
92 * and a specific sampling mode example under
93 * <code>examples/image-scaling-irregular-grid</code>.
95 * There are more details on this topic in the
96 * \link resourceimagescaling Rescaling Images \endlink
99 * <h2 class="pg">Style</h2>
100 * 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
101 * 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.<br>
103 * Dali::Toolkit::ImageView myImageView1 = Dali::Toolkit::ImageView::New("source-to-nine-patch-image.9.png");
104 * Dali::Toolkit::ImageView myImageView2 = Dali::Toolkit::ImageView::New("source-to-nine-patch-image.#.png");
107 * <h2 class="pg">Changing the image</h2>
108 * The Image View can be changed by calling Dali::Toolkit::ImageView::SetImage methods or by changing the IMAGE property.
110 * myImageActor.SetImage( newImage );