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 optimisations 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  * A path to a svg image file:
  28  * @code
  29  * Dali::Toolkit::ImageView myImageView = ImageView::New( "source-image-url.svg" );
  30  * @endcode
  31  *
  32  * <h3 class="pg">Loading from a Image handle</h3>
  33  * Dali::Image is an abstract base class with multiple derived classes.
  34  *
  35  * @code
  36  * Dali::Image image = BufferImage::New( 100, 100 );
  37  * Dali::Toolkit::ImageView myImageView = Toolkit::ImageView::New( image );
  38  * @endcode
  39  *
  40  * <h3 class="pg">The IMAGE property</h3>
  41  * the IMAGE property allows you to change many aspects of the image that is rendered.
  42  * This property can either be a string for a image url path or a Property::Map that specifies
  43  * the image in more detail.
  44  *
  45  * <h3 class="pg">Visuals</h3>
  46  * You can specify a specific visual instead of using the default Image Visual, e.g to use the Border Visual.
  47  *
  48  * @code
  49  * Property::Map visual;
  50  * visual.Insert( Visual::Property::Type,Visual::BORDER );
  51  * visual.Insert( BorderVisual::Property::COLOR, COLOR::RED );
  52  * visual.Insert( BorderVisual::Property::SIZE, 20.f );
  53  *
  54  * Dali::Toolkit::ImageView myImageView = Dali::Toolkit::ImageView::New();
  55  * myImageView.SetProperty( Control::Property::IMAGE, visual );
  56  * @endcode
  57
  58  * <h3 class="pg">Resizing at Load Time</h3>
  59  * An application loading images from an external source will often want to
  60  * display those images at a lower resolution than their native ones.
  61  * To support this, DALi can resize an image at load time so that its
  62  * in-memory copy uses less space and its visual quality benefits from being
  63  * prefiltered.
  64  * There are four algorithms which can be used to fit an image to a desired
  65  * rectangle, a desired width or a desired height
  66  * (see Dali::FittingMode).
  67  *
  68  * Here is an example doing rescaling:
  69  *
  70  * @code
  71  * Property::Map imageProperty;
  72  * imageProperty.Insert("url", "source-image-url.png");
  73  * imageProperty.Insert("fittingMode", "SCALE_TO_FILL");
  74  * imageProperty.Insert("desiredWidth", 240);
  75  * imageProperty.Insert("desiredHeight", 240);
  76  * Dali::Toolkit::ImageView myImageView = Dali::Toolkit::ImageView::New();
  77  * myImageView.SetProperty( Control::Property::IMAGE, imageProperty);
  78
  79  * @endcode
  80  *
  81  * This example sets the size and fitting mode appropriately for a large thumbnail
  82  * during Dali::ResourceImage construction.
  83  * In general, to enable scaling on load, pass a non-zero width or height and
  84  * one of the four fitting modes to the Dali::ResourceImage creator function
  85  * as shown above.
  86  *
  87  * The fitting modes and a suggested use-case for each are as follows:
  88  * <ol>
  89  *   <li> "SHRINK_TO_FIT" Full-screen image display: Limit loaded image resolution to device resolution but show all of image.
  90  *   <li> "SCALE_TO_FILL" Thumbnail gallery grid: Limit loaded image resolution to screen tile, filling whole tile but losing a few pixels to match the tile shape.
  91  *   <li> "FIT_WIDTH" Image columns: Limit loaded image resolution to column.
  92  *   <li> "FIT_HEIGHT" Image rows: Limit loaded image resolution to row height.
  93  * </ol>
  94  *
  95  * The dali-demo project contains a full example under
  96  * <code>examples/image-scaling-and-filtering</code>
  97  * and a specific sampling mode example under
  98  * <code>examples/image-scaling-irregular-grid</code>.
  99  *
 100  * There are more details on this topic in the
 101  * \link resourceimagescaling Rescaling Images \endlink
 102  * section.
 103  *
 104  * <h2 class="pg">Style</h2>
 105  * 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
 106  * 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>
 107  * @code
 108  * Dali::Toolkit::ImageView myImageView1 = Dali::Toolkit::ImageView::New("source-to-nine-patch-image.9.png");
 109  * Dali::Toolkit::ImageView myImageView2 = Dali::Toolkit::ImageView::New("source-to-nine-patch-image.#.png");
 110  * @endcode
 111  *
 112  * <h2 class="pg">Changing the image</h2>
 113  * The Image View can be changed by calling Dali::Toolkit::ImageView::SetImage methods or by changing the IMAGE property.
 114  * @code
 115  * myImageView.SetImage( newImage );
 116  * @endcode
 117  *
 118  */