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);
23 * <h2 class="pg">Style</h2>
24 * The Actor can render an image in two different ways.<br>
25 * -# STYLE_QUAD: A simple flat quad style for redering image.<br>
26 * -# STYLE_NINE_PATCH: This style gives the flexibility to stretch images by dividing it into 9 sections.
27 * The four corners are unscaled; the four edges are scaled in one axis, and the middle is scaled in both axes.<br>
30 * // default : ImageActor::STYLE_QUAD
31 * myImageActor.SetStyle (Dali::ImageActor::STYLE_NINE_PATCH);
35 * <h2 class="pg">Border</h2>
36 * The border is used in the ImageActor::STYLE_NINE_PATCH. It defines the border values of the image for stretching.<br>
39 * Dali::ImageActor::Border border(0.45,0.15,0.45,0.15);
40 * myImageActor.SetBorder(border);
44 * <h2 class="pg">Pixel area</h2>
45 * 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.
47 * Rect<int> pixel1( myX, myY, myWidth, myHeight );
48 * if(!myImageActor.IsPixelAreaSet())
50 * myImageActor.SetPixelArea( pixel1 );
53 * //Removes the pixel are set
54 * myImageActor.ClearPixelArea();
58 * <h2 class="pg">Changing the image</h2>
59 * 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
61 * myImageActor.SetImage( newImage );
64 * <h2 class="pg">Fade in</h2>
65 * It's possible to fade in the image gradually when first rendered.
67 * if (!myImageActor.GetFadeIn())
69 * myImageActor.SetFadeIn(true);
72 * // default : 1 Second
73 * myImageActor.SetFadeInDuration(seconds);
80 * <h1 class="pg">Text Actor</h1>
83 * <h2 class="pg">Displaying Text</h2>
84 * The text displayed by the text actor is initialised/set on construction, which can be changed later.
87 * Dali::TextActor myTextActor = Dali::TextActor::New("Hi");
88 * std::string str("Hello");
89 * if (myTextActor.GetText() != str)
91 * myTextActor.SetText(str);
96 * <h2 class="pg">Fonts</h2>
97 * It's possible to specify a font for the text displayed by the text actor.
99 * Dali::Font freeSerif = Dali::Font::New("FreeSerif", 8);
100 * myTextActor.SetFont(freeSerif);
104 * <h2 class="pg">Ellipsis</h2>
105 * It is possible to display an ellipsis in the TextActor when the text is truncated.
107 * std::string str("...");
108 * if (myTextActor.GetEllipsis() != str)
110 * myTextActor.SetEllipsis(str);
114 * <h2 class="pg">Style</h2>
116 * 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.
119 * style.SetItalic( true );
121 * myTextActor.SetTextStyle( style );
124 * @see Dali::TextActor::SetTextStyle()
126 * 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
129 * myTextActor.SetTextFitStyle(TextUtilities::EllipsizeRight);
132 * <h2 class="pg">Loading state</h2>
133 * It is possible to get the font loading status for the text and do processing accordingly.
135 * // observe text loading and do some processing when it's done
136 * if( Dali::ResourceLoadingSucceeded == myTextActor.GetLoadingState() )
138 * // text already loaded, Do the processing here
139 * OnTextFontLoaded();
143 * // text not yet loaded, Connect to the SignalTextAvailable signal and Do the processing when it occurs
144 * myTextActor.SignalTextAvailable().Connect(this, &MyClass::OnTextFontLoaded);
151 * <h1 class="pg">Mesh Actor</h1>
153 * <h2 class="pg">Construction</h2>
154 * The mesh actor is created by passing a reference to Dali::Mesh object
157 * Dali::Mesh mesh = Dali::Mesh::New();
158 * Dali::MeshActor myMeshActor = Dali::MeshActor::New(mesh);
162 * <h2 class="pg">Modifying material</h2>
163 * The developer can change the material of mesh actor using the material entity name.
166 * Dali::Image image = Dali::Image::New(myTextureFile);
167 * myCustomMaterial = Dali::Material::New("CustomMaterial");
168 * myCustomMaterial.SetDiffuseTexture(image);
169 * Dali::MeshActor::SetMaterial(myMeshActor, materialEntityNameInModel, 0, myCustomMaterial);