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  * <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).
  30  *
  31  * Here is an example doing rescaling:
  32  *
  33  * @code
  34  * Dali::ImageAttributes attributes;
  35  * attributes.SetSize( 256, 192 );
  36  * attributes.SetScalingMode( Dali::ImageAttributes::ScaleToFill );
  37  * Dali::Image image = Dali::Image::New( filename, attributes );
  38  * @endcode
  39  *
  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.
  45  *
  46  * The scaling modes and a suggested use-case for each are as follows:
  47  * <ol>
  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.
  52  * </ol>
  53  *
  54  * The dali-demo project contains a full example under <code>examples/image</code>.
  55  *
  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>
  61  *
  62  * @code
  63  * // default : ImageActor::STYLE_QUAD
  64  * myImageActor.SetStyle (Dali::ImageActor::STYLE_NINE_PATCH);
  65  * @endcode
  66  *
  67  *
  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>
  70  *
  71  * @code
  72  * Dali::ImageActor::Border border(0.45,0.15,0.45,0.15);
  73  * myImageActor.SetBorder(border);
  74  * @endcode
  75  *
  76  *
  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.
  79  * @code
  80  * Rect<int> pixel1( myX, myY, myWidth, myHeight );
  81  * if(!myImageActor.IsPixelAreaSet())
  82  * {
  83  *   myImageActor.SetPixelArea( pixel1 );
  84  * }
  85  *
  86  * //Removes the pixel are set
  87  * myImageActor.ClearPixelArea();
  88  * @endcode
  89  *
  90  *
  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
  93  * @code
  94  * myImageActor.SetImage( newImage );
  95  * @endcode
  96  *
  97  * <h2 class="pg">Fade in</h2>
  98  * It's possible to fade in the image gradually when first rendered.
  99  * @code
 100  * if (!myImageActor.GetFadeIn())
 101  * {
 102  *   myImageActor.SetFadeIn(true);
 103  * }
 104  *
 105  * // default : 1 Second
 106  * myImageActor.SetFadeInDuration(seconds);
 107  * @endcode
 108  *
 109  *
 110  *
 111  *
 112  *
 113  * <h1 class="pg">Text Actor</h1>
 114  *
 115  *
 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.
 118  *
 119  * @code
 120  * Dali::TextActor myTextActor = Dali::TextActor::New("Hi");
 121  * std::string str("Hello");
 122  * if (myTextActor.GetText() != str)
 123  * {
 124  *   myTextActor.SetText(str);
 125  * }
 126  * @endcode
 127  *
 128  *
 129  * <h2 class="pg">Fonts</h2>
 130  * It's possible to specify a font for the text displayed by the text actor.
 131  * @code
 132  * Dali::Font freeSerif = Dali::Font::New("FreeSerif", 8);
 133  * myTextActor.SetFont(freeSerif);
 134  * @endcode
 135  *
 136  *
 137  * <h2 class="pg">Ellipsis</h2>
 138  * It is possible to display an ellipsis in the TextActor when the text is truncated.
 139  * @code
 140  * std::string str("...");
 141  * if (myTextActor.GetEllipsis() != str)
 142  * {
 143  *   myTextActor.SetEllipsis(str);
 144  * }
 145  * @endcode
 146  *
 147  * <h2 class="pg">Style</h2>
 148  *
 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.
 150  * @code
 151  * TextStyle style;
 152  * style.SetItalic( true );
 153  *
 154  * myTextActor.SetTextStyle( style );
 155  * @endcode
 156  *
 157  * @see Dali::TextActor::SetTextStyle()
 158  *
 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
 160  * @code
 161  * // default : NONE
 162  * myTextActor.SetTextFitStyle(TextUtilities::EllipsizeRight);
 163  * @endcode
 164  *
 165  * <h2 class="pg">Loading state</h2>
 166  * It is possible to get the font loading status for the text and do processing accordingly.
 167  * @code
 168  * // observe text loading and do some processing when it's done
 169  * if( Dali::ResourceLoadingSucceeded == myTextActor.GetLoadingState() )
 170  * {
 171  *   // text already loaded, Do the processing here
 172  *   OnTextFontLoaded();
 173  * }
 174  * else
 175  * {
 176  *    // text not yet loaded, Connect to the SignalTextAvailable signal and Do the processing when it occurs
 177  *   myTextActor.SignalTextAvailable().Connect(this, &MyClass::OnTextFontLoaded);
 178  * }
 179  * @endcode
 180  *
 181  *
 182  *
 183  *
 184  * <h1 class="pg">Mesh Actor</h1>
 185  *
 186  * <h2 class="pg">Construction</h2>
 187  * The mesh actor is created by passing a reference to Dali::Mesh object
 188  *
 189  * @code
 190  * Dali::Mesh mesh = Dali::Mesh::New();
 191  * Dali::MeshActor myMeshActor = Dali::MeshActor::New(mesh);
 192  * @endcode
 193
 194  *
 195  * <h2 class="pg">Modifying material</h2>
 196  * The developer can change the material of mesh actor using the material entity name.
 197  *
 198  * @code
 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);
 203  *
 204  * @endcode
 205  *
 206  *
 207  */
 208