1 /*! \page image-actor Image Actors
4 * <h1 class="pg">Overview</h1>
5 * The Dali::ImageActor inherits from Dali::Actor and provide means to display resources like Images on the stage.
6 * All the Dali::Actor methods can be called on them.<br>
8 * - <b>ImageActor:</b> An actor for displaying Images. It allows the developer to display a Dali::Image object on the stage.<br>
10 * <h1 class="pg">Image Actor</h1>
12 * <h2 class="pg">Construction</h2>
13 * The Image Actor is constructed by passing a Dali::Image object
16 * Dali::Image image = Image::New(myImageFilename);
17 * Dali::ImageActor myImageActor = ImageActor::New(image);
20 * <h3 class="pg">Resizing at Load Time</h3>
21 * An application loading images from an external source will often want to
22 * display those images at a lower resolution than their native ones.
23 * To support this, %Dali can resize an image at load time so that its in-memory
24 * copy uses less space and its visual quality benefits from being prefiltered.
25 * There are four algorithms which can be used to fit an image to a desired
26 * rectangle, a desired width or a desired height
27 * (see Dali::ImageAttributes::ScalingMode).
29 * Here is an example doing rescaling:
32 * Dali::ImageAttributes attributes;
33 * attributes.SetSize( 256, 192 );
34 * attributes.SetScalingMode( Dali::ImageAttributes::ScaleToFill );
35 * Dali::Image image = Dali::Image::New( filename, attributes );
38 * This example sets the size and scaling mode appropriately for a large thumbnail
39 * on an Dali::ImageAttributes instance and passes that to Dali::Image construction.
40 * In general, to enable scaling on load, set-up a Dali::ImageAttributes object with
41 * a non-zero width or height and one of the four scaling modes, and pass it into a
42 * Dali::Image creator function as shown above.
44 * The scaling modes and a suggested use-case for each are as follows:
46 * <li> Dali::ImageAttributes::ShrinkToFit Full-screen image display: Limit loaded image resolution to device resolution.
47 * <li> Dali::ImageAttributes::ScaleToFill Thumbnail gallery grid: Limit loaded image resolution to screen tile.
48 * <li> Dali::ImageAttributes::FitWidth Image columns: Limit loaded image resolution to column.
49 * <li> Dali::ImageAttributes::FitHeight Image rows: Limit loaded image resolution to row height.
52 * The dali-demo project contains a full example under <code>examples/image</code>.
54 * <h2 class="pg">Style</h2>
55 * The Actor can render an image in two different ways.<br>
56 * -# STYLE_QUAD: A simple flat quad style for rendering images.<br>
57 * -# STYLE_NINE_PATCH: This style gives the flexibility to stretch images by dividing it into 9 sections.
58 * The four corners are not scaled; the four edges are scaled in one axis, and the middle is scaled in both axes.<br>
61 * // default : ImageActor::STYLE_QUAD
62 * myImageActor.SetStyle (Dali::ImageActor::STYLE_NINE_PATCH);
66 * <h2 class="pg">Border</h2>
67 * The border is used in the ImageActor::STYLE_NINE_PATCH. It defines the border values of the image for stretching.<br>
70 * Dali::ImageActor::Border border(0.45,0.15,0.45,0.15);
71 * myImageActor.SetBorder(border);
75 * <h2 class="pg">Pixel area</h2>
76 * The area of the image to be displayed by the Image Actor can be set by setting the Pixel area. Pixel area is relative to the top-left (0,0) of the image.
78 * Rect<int> pixel1( myX, myY, myWidth, myHeight );
79 * if(!myImageActor.IsPixelAreaSet())
81 * myImageActor.SetPixelArea( pixel1 );
84 * //Removes the pixel are set
85 * myImageActor.ClearPixelArea();
89 * <h2 class="pg">Changing the image</h2>
90 * The Image Actor needs a reference to a Dali::Image object on creation. However the Image object can be later changed by calling DaliActor:SetImage
92 * myImageActor.SetImage( newImage );