docs/content/programming-guide/image-text-mesh-actor.h

   1 /*! \page image-text-mesh-actor Image, Text and Mesh actors
   2  *
   3  *
   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>
   7  *
   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>
  11  *
  12  * <h1 class="pg">Image Actor</h1>
  13  *
  14  * <h2 class="pg">Construction</h2>
  15  * The Image Actor is constructed by passing a Dali::Image object
  16  *
  17  * @code
  18  * Dali::Image image = Image::New(myImageFilename);
  19  * Dali::ImageActor myImageActor = ImageActor::New(image);
  20  * @endcode
  21  *
  22  *
  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>
  28  *
  29  * @code
  30  * // default : ImageActor::STYLE_QUAD
  31  * myImageActor.SetStyle (Dali::ImageActor::STYLE_NINE_PATCH);
  32  * @endcode
  33  *
  34  *
  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>
  37  *
  38  * @code
  39  * Dali::ImageActor::Border border(0.45,0.15,0.45,0.15);
  40  * myImageActor.SetBorder(border);
  41  * @endcode
  42  *
  43  *
  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.
  46  * @code
  47  * Rect<int> pixel1( myX, myY, myWidth, myHeight );
  48  * if(!myImageActor.IsPixelAreaSet())
  49  * {
  50  *   myImageActor.SetPixelArea( pixel1 );
  51  * }
  52  *
  53  * //Removes the pixel are set
  54  * myImageActor.ClearPixelArea();
  55  * @endcode
  56  *
  57  *
  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
  60  * @code
  61  * myImageActor.SetImage( newImage );
  62  * @endcode
  63  *
  64  * <h2 class="pg">Fade in</h2>
  65  * It's possible to fade in the image gradually when first rendered.
  66  * @code
  67  * if (!myImageActor.GetFadeIn())
  68  * {
  69  *   myImageActor.SetFadeIn(true);
  70  * }
  71  *
  72  * // default : 1 Second
  73  * myImageActor.SetFadeInDuration(seconds);
  74  * @endcode
  75  *
  76  *
  77  *
  78  *
  79  *
  80  * <h1 class="pg">Text Actor</h1>
  81  *
  82  *
  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.
  85  *
  86  * @code
  87  * Dali::TextActor myTextActor = Dali::TextActor::New("Hi");
  88  * std::string str("Hello");
  89  * if (myTextActor.GetText() != str)
  90  * {
  91  *   myTextActor.SetText(str);
  92  * }
  93  * @endcode
  94  *
  95  *
  96  * <h2 class="pg">Fonts</h2>
  97  * It's possible to specify a font for the text displayed by the text actor.
  98  * @code
  99  * Dali::Font freeSerif = Dali::Font::New("FreeSerif", 8);
 100  * myTextActor.SetFont(freeSerif);
 101  * @endcode
 102  *
 103  *
 104  * <h2 class="pg">Ellipsis</h2>
 105  * It is possible to display an ellipsis in the TextActor when the text is truncated.
 106  * @code
 107  * std::string str("...");
 108  * if (myTextActor.GetEllipsis() != str)
 109  * {
 110  *   myTextActor.SetEllipsis(str);
 111  * }
 112  * @endcode
 113  *
 114  * <h2 class="pg">Style</h2>
 115  *
 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.
 117  * @code
 118  * TextStyle style;
 119  * style.SetItalic( true );
 120  *
 121  * myTextActor.SetTextStyle( style );
 122  * @endcode
 123  *
 124  * @see Dali::TextActor::SetTextStyle()
 125  *
 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
 127  * @code
 128  * // default : NONE
 129  * myTextActor.SetTextFitStyle(TextUtilities::EllipsizeRight);
 130  * @endcode
 131  *
 132  * <h2 class="pg">Loading state</h2>
 133  * It is possible to get the font loading status for the text and do processing accordingly.
 134  * @code
 135  * // observe text loading and do some processing when it's done
 136  * if( Dali::ResourceLoadingSucceeded == myTextActor.GetLoadingState() )
 137  * {
 138  *   // text already loaded, Do the processing here
 139  *   OnTextFontLoaded();
 140  * }
 141  * else
 142  * {
 143  *    // text not yet loaded, Connect to the SignalTextAvailable signal and Do the processing when it occurs
 144  *   myTextActor.SignalTextAvailable().Connect(this, &MyClass::OnTextFontLoaded);
 145  * }
 146  * @endcode
 147  *
 148  *
 149  *
 150  *
 151  * <h1 class="pg">Mesh Actor</h1>
 152  *
 153  * <h2 class="pg">Construction</h2>
 154  * The mesh actor is created by passing a reference to Dali::Mesh object
 155  *
 156  * @code
 157  * Dali::Mesh mesh = Dali::Mesh::New();
 158  * Dali::MeshActor myMeshActor = Dali::MeshActor::New(mesh);
 159  * @endcode
 160
 161  *
 162  * <h2 class="pg">Modifying material</h2>
 163  * The developer can change the material of mesh actor using the material entity name.
 164  *
 165  * @code
 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);
 170  *
 171  * @endcode
 172  *
 173  *
 174  */
 175