docs/content/programming-guide/image-view.h

   1 /*! \page image-view Image Views
   2  *
   3  *
   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>
   6  *
   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>
   8  *
   9  * <h1 class="pg">Image View</h1>
  10  *
  11  * <h2 class="pg">Construction</h2>
  12  * The Image View is constructed by passing a Dali::Image object or by a url path.<br>
  13  *
  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:
  18  * @code
  19  * Dali::Toolkit::ImageView myImageView = ImageView::New( "source-image-url.png" );
  20  * @endcode
  21  *
  22  * A path to a nine-patch/n-patch image file:
  23  * @code
  24  * Dali::Toolkit::ImageView myImageView = ImageView::New( "source-image-url.9.png" );
  25  * @endcode
  26  *
  27  * <h3 class="pg">Loading from a Image handle</h3>
  28  * Dali::Image is an abstract base class with multiple derived classes.
  29  *
  30  * @code
  31  * Dali::Image image = BufferImage::New( 100, 100 );
  32  * Dali::Toolkit::ImageView myImageView = Toolkit::ImageView::New( image );
  33  * @endcode
  34  *
  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.
  39  *
  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.
  42  *
  43  * @code
  44  * Property::Map renderer;
  45  * renderer.Insert("rendererType","border");
  46  * renderer.Insert("borderColor",COLOR::RED);
  47  * renderer.Insert("borderSize",20.f);
  48  *
  49  * Dali::Toolkit::ImageView myImageView = Dali::Toolkit::ImageView::New();
  50  * myImageView.SetProperty( Control::Property::IMAGE, renderer);
  51  * @endcode
  52
  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
  58  * prefiltered.
  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).
  62  *
  63  * Here is an example doing rescaling:
  64  *
  65  * @code
  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);
  73
  74  * @endcode
  75  *
  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
  80  * as shown above.
  81  *
  82  * The fitting modes and a suggested use-case for each are as follows:
  83  * <ol>
  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.
  88  * </ol>
  89  *
  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>.
  94  *
  95  * There are more details on this topic in the
  96  * \link resourceimagescaling Rescaling Images \endlink
  97  * section.
  98  *
  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>
 102  * @code
 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");
 105  * @endcode
 106  *
 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.
 109  * @code
 110  * myImageActor.SetImage( newImage );
 111  * @endcode
 112  *
 113  */