1 /*! \page image-text-mesh-actor Image, Text and Mesh actors
4 * <h1 class="pg">Overview</h1>
5 * The Dali::ImageActor, Dali::TextActor, Dali::MeshActor are inherited from Dali::Actor and provide means to display resources like Images, Text and Geometries (Triangle meshes) 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>
9 * - <b>TextActor:</b> An actor for displaying text.<br>
10 * - <b>MeshActor:</b> An actor for displaying one or more mesh geometries. It may have children, which may be plain actors or other mesh actors.<br>
12 * <h1 class="pg">Image Actor</h1>
14 * <h2 class="pg">Construction</h2>
15 * The Image Actor is constructed by passing a Dali::Image object
18 * Dali::Image image = Image::New(myImageFilename);
19 * Dali::ImageActor myImageActor = ImageActor::New(image);
22 * <h3 class="pg">Resizing at Load Time</h3>
23 * An application loading images from an external source will often want to
24 * display those images at a lower resolution than their native ones.
25 * To support this, %Dali can resize an image at load time so that its in-memory
26 * copy uses less space and its visual quality benefits from being prefiltered.
27 * There are four algorithms which can be used to fit an image to a desired
28 * rectangle, a desired width or a desired height
29 * (see Dali::ImageAttributes::ScalingMode).
31 * Here is an example doing rescaling:
34 * Dali::ImageAttributes attributes;
35 * attributes.SetSize( 256, 192 );
36 * attributes.SetScalingMode( Dali::ImageAttributes::ScaleToFill );
37 * Dali::Image image = Dali::Image::New( filename, attributes );
40 * This example sets the size and scaling mode appropriately for a large thumbnail
41 * on an Dali::ImageAttributes instance and passes that to Dali::Image construction.
42 * In general, to enable scaling on load, set-up a Dali::ImageAttributes object with
43 * a non-zero width or height and one of the four scaling modes, and pass it into a
44 * Dali::Image creator function as shown above.
46 * The scaling modes and a suggested use-case for each are as follows:
48 * <li> Dali::ImageAttributes::ShrinkToFit Full-screen image display: Limit loaded image resolution to device resolution.
49 * <li> Dali::ImageAttributes::ScaleToFill Thumbnail gallery grid: Limit loaded image resolution to screen tile.
50 * <li> Dali::ImageAttributes::FitWidth Image columns: Limit loaded image resolution to column.
51 * <li> Dali::ImageAttributes::FitHeight Image rows: Limit loaded image resolution to row height.
54 * The dali-demo project contains a full example under <code>examples/image</code>.
56 * <h2 class="pg">Style</h2>
57 * The Actor can render an image in two different ways.<br>
58 * -# STYLE_QUAD: A simple flat quad style for rendering images.<br>
59 * -# STYLE_NINE_PATCH: This style gives the flexibility to stretch images by dividing it into 9 sections.
60 * The four corners are not scaled; the four edges are scaled in one axis, and the middle is scaled in both axes.<br>
63 * // default : ImageActor::STYLE_QUAD
64 * myImageActor.SetStyle (Dali::ImageActor::STYLE_NINE_PATCH);
68 * <h2 class="pg">Border</h2>
69 * The border is used in the ImageActor::STYLE_NINE_PATCH. It defines the border values of the image for stretching.<br>
72 * Dali::ImageActor::Border border(0.45,0.15,0.45,0.15);
73 * myImageActor.SetBorder(border);
77 * <h2 class="pg">Pixel area</h2>
78 * 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.
80 * Rect<int> pixel1( myX, myY, myWidth, myHeight );
81 * if(!myImageActor.IsPixelAreaSet())
83 * myImageActor.SetPixelArea( pixel1 );
86 * //Removes the pixel are set
87 * myImageActor.ClearPixelArea();
91 * <h2 class="pg">Changing the image</h2>
92 * 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
94 * myImageActor.SetImage( newImage );
97 * <h2 class="pg">Fade in</h2>
98 * It's possible to fade in the image gradually when first rendered.
100 * if (!myImageActor.GetFadeIn())
102 * myImageActor.SetFadeIn(true);
105 * // default : 1 Second
106 * myImageActor.SetFadeInDuration(seconds);
113 * <h1 class="pg">Text Actor</h1>
116 * <h2 class="pg">Displaying Text</h2>
117 * The text displayed by the text actor is initialised/set on construction, which can be changed later.
120 * Dali::TextActor myTextActor = Dali::TextActor::New("Hi");
121 * std::string str("Hello");
122 * if (myTextActor.GetText() != str)
124 * myTextActor.SetText(str);
129 * <h2 class="pg">Fonts</h2>
130 * It's possible to specify a font for the text displayed by the text actor.
132 * Dali::Font freeSerif = Dali::Font::New("FreeSerif", 8);
133 * myTextActor.SetFont(freeSerif);
137 * <h2 class="pg">Ellipsis</h2>
138 * It is possible to display an ellipsis in the TextActor when the text is truncated.
140 * std::string str("...");
141 * if (myTextActor.GetEllipsis() != str)
143 * myTextActor.SetEllipsis(str);
147 * <h2 class="pg">Style</h2>
149 * By calling the Dali::TextActor::SetTextStyle or by passing a Dali::TextStyle to the constructor, it's possible to define styling parameters such as color, font, size, outline, glow, shadow, italics or bold.
152 * style.SetItalic( true );
154 * myTextActor.SetTextStyle( style );
157 * @see Dali::TextActor::SetTextStyle()
159 * It is possible to specify the text fit style for the text actor. The developer can specify whether the ellipsis should appear on the left, centre, or at the end
162 * myTextActor.SetTextFitStyle(TextUtilities::EllipsizeRight);
165 * <h2 class="pg">Loading state</h2>
166 * It is possible to get the font loading status for the text and do processing accordingly.
168 * // observe text loading and do some processing when it's done
169 * if( Dali::ResourceLoadingSucceeded == myTextActor.GetLoadingState() )
171 * // text already loaded, Do the processing here
172 * OnTextFontLoaded();
176 * // text not yet loaded, Connect to the SignalTextAvailable signal and Do the processing when it occurs
177 * myTextActor.SignalTextAvailable().Connect(this, &MyClass::OnTextFontLoaded);
184 * <h1 class="pg">Mesh Actor</h1>
186 * <h2 class="pg">Construction</h2>
187 * The mesh actor is created by passing a reference to Dali::Mesh object
190 * Dali::Mesh mesh = Dali::Mesh::New();
191 * Dali::MeshActor myMeshActor = Dali::MeshActor::New(mesh);
195 * <h2 class="pg">Modifying material</h2>
196 * The developer can change the material of mesh actor using the material entity name.
199 * Dali::Image image = Dali::Image::New(myTextureFile);
200 * myCustomMaterial = Dali::Material::New("CustomMaterial");
201 * myCustomMaterial.SetDiffuseTexture(image);
202 * Dali::MeshActor::SetMaterial(myMeshActor, materialEntityNameInModel, 0, myCustomMaterial);