capi/dali/public-api/actors/text-actor.h

   1 #ifndef __DALI_TEXT_ACTOR_H__
   2 #define __DALI_TEXT_ACTOR_H__
   3
   4 //
   5 // Copyright (c) 2014 Samsung Electronics Co., Ltd.
   6 //
   7 // Licensed under the Flora License, Version 1.0 (the License);
   8 // you may not use this file except in compliance with the License.
   9 // You may obtain a copy of the License at
  10 //
  11 //     http://floralicense.org/license/
  12 //
  13 // Unless required by applicable law or agreed to in writing, software
  14 // distributed under the License is distributed on an AS IS BASIS,
  15 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16 // See the License for the specific language governing permissions and
  17 // limitations under the License.
  18 //
  19
  20
  21 /**
  22  * @addtogroup CAPI_DALI_ACTORS_MODULE
  23  * @{
  24  */
  25
  26 // EXTERNAL INCLUDES
  27 #include <string>
  28
  29 // INTERNAL INCLUDES
  30 #include <dali/public-api/actors/renderable-actor.h>
  31 #include <dali/public-api/common/loading-state.h>
  32 #include <dali/public-api/common/constants.h>
  33 #include <dali/public-api/math/vector2.h>
  34 #include <dali/public-api/text/text-style.h>
  35 #include <dali/public-api/text/text.h>
  36
  37 namespace Dali DALI_IMPORT_API
  38 {
  39
  40 class Font;
  41
  42 namespace Internal DALI_INTERNAL
  43 {
  44 class TextActor;
  45 }
  46
  47 /**
  48  * @brief TextActor is a basic actor for displaying a text label
  49  *
  50  * By default the text actor always uses the natural size of the text when SetText is called,
  51  * unless SetSize is called to override the size or size is animated to some other size.
  52  * Natural size for TextActor is the same as the size returned by Font::MeasureText( string )
  53  * using the font that the TextActor is using.
  54  *
  55  * By default CullFaceMode is set to CullNone to enable the TextActor to be viewed from all angles.
  56  */
  57 class DALI_IMPORT_API TextActor : public RenderableActor
  58 {
  59 public:
  60
  61   typedef SignalV2< void (TextActor) > TextSignalV2;     ///< Text available signal type
  62
  63   //Signal Names
  64   static const char* const SIGNAL_TEXT_LOADING_FINISHED; ///< name "text-loading-finished"
  65
  66   // Default Properties; additional to RenderableActor properties
  67   static const Property::Index TEXT;                              ///< name "text"                     type STRING
  68   static const Property::Index FONT;                              ///< name "font"                     type STRING
  69   static const Property::Index FONT_STYLE;                        ///< name "font-style"               type STRING
  70   static const Property::Index OUTLINE_ENABLE;                    ///< name "outline-enable"           type BOOLEAN
  71   static const Property::Index OUTLINE_COLOR;                     ///< name "outline-color"            type VECTOR4
  72   static const Property::Index OUTLINE_THICKNESS_WIDTH;           ///< name "outline-thickness-width"  type VECTOR2
  73   static const Property::Index SMOOTH_EDGE;                       ///< name "smooth-edge"              type FLOAT
  74   static const Property::Index GLOW_ENABLE;                       ///< name "glow-enable"              type BOOLEAN
  75   static const Property::Index GLOW_COLOR;                        ///< name "glow-color"               type VECTOR4
  76   static const Property::Index GLOW_INTENSITY;                    ///< name "glow-intensity"           type FLOAT
  77   static const Property::Index SHADOW_ENABLE;                     ///< name "shadow-enable"            type BOOLEAN
  78   static const Property::Index SHADOW_COLOR;                      ///< name "shadow-color"             type VECTOR4
  79   static const Property::Index SHADOW_OFFSET;                     ///< name "shadow-offset"            type VECTOR2
  80   static const Property::Index ITALICS_ANGLE;                     ///< name "italics-angle"            type FLOAT
  81   static const Property::Index UNDERLINE;                         ///< name "underline"                type BOOLEAN
  82   static const Property::Index WEIGHT;                            ///< name "weight"                   type INTEGER
  83   static const Property::Index FONT_DETECTION_AUTOMATIC;          ///< name "font-detection-automatic" type BOOLEAN
  84   static const Property::Index GRADIENT_COLOR;                    ///< name "gradient-color"           type VECTOR4
  85   static const Property::Index GRADIENT_START_POINT;              ///< name "gradient-start-point"     type VECTOR2
  86   static const Property::Index GRADIENT_END_POINT;                ///< name "gradient-end-point"       type VECTOR2
  87   static const Property::Index SHADOW_SIZE;                       ///< name "shadow-size"              type FLOAT
  88   static const Property::Index TEXT_COLOR;                        ///< name "text-color"               type VECTOR4
  89
  90   /**
  91    * @brief Create an uninitialized TextActor handle.
  92    *
  93    * This can be initialised with TextActor::New().
  94    * Calling member functions with an uninitialized handle is not allowed.
  95    */
  96   TextActor();
  97
  98   /**
  99    * @brief Create a TextActor object with no text.
 100    *
 101    * @return A handle to a newly allocated Dali resource.
 102    */
 103   static TextActor New();
 104
 105   /**
 106    * @brief Create a TextActor object with LeftToRight text and font detection
 107    *
 108    * @param [in] text          The text which will be displayed
 109    * @return A handle to a newly allocated Dali resource.
 110    */
 111   static TextActor New(const std::string& text);
 112
 113   /**
 114    * @copydoc New(const std::string& text)
 115    */
 116   static TextActor New(const Text& text);
 117
 118   /**
 119    * @brief Create a TextActor object with LeftToRight text.
 120    *
 121    * @param [in] text          The text which will be displayed
 122    * @param [in] fontDetection Try to detect font in case text is not supported with current one.
 123    * @return A handle to a newly allocated Dali resource.
 124    */
 125   static TextActor New(const std::string& text, bool fontDetection);
 126
 127   /**
 128    * @copydoc New(const std::string& text, bool fontDetection)
 129    */
 130   static TextActor New(const Text& text, bool fontDetection);
 131
 132   /**
 133    * @brief Create a TextActor object.
 134    *
 135    * @param [in] text          The text which will be displayed
 136    * @param [in] fontDetection Try to detect font in case text is not supported with current one.
 137    * @param [in] isLeftToRight Text is displayed from left to right if true, otherwise from right to left.
 138    * @return A handle to a newly allocated Dali resource.
 139    */
 140   static TextActor New(const std::string& text, bool fontDetection, bool isLeftToRight);
 141
 142   /**
 143    * @copydoc New(const std::string& text, bool fontDetection, bool isLeftToRight)
 144    */
 145   static TextActor New(const Text& text, bool fontDetection, bool isLeftToRight);
 146
 147   /**
 148    * @brief Create a TextActor object with LeftToRight text and font detection.
 149    *
 150    * @param [in] text          The text which will be displayed
 151    * @param [in] font          The font which will be used for the text
 152    * @return A handle to a newly allocated Dali resource.
 153    */
 154   static TextActor New(const std::string& text, Font font);
 155
 156   /**
 157    * @copydoc New(const std::string& text, Font font)
 158    */
 159   static TextActor New(const Text& text, Font font);
 160
 161   /**
 162    * @brief Create a TextActor object with LeftToRight text.
 163    *
 164    * @param [in] text          The text which will be displayed
 165    * @param [in] font          The font which will be used for the text
 166    * @param [in] fontDetection Try to detect font in case text is not supported with current one.
 167    * @return A handle to a newly allocated Dali resource.
 168    */
 169   static TextActor New(const std::string& text, Font font, bool fontDetection);
 170
 171   /**
 172    * @copydoc New(const std::string& text, Font font, bool fontDetection)
 173    */
 174   static TextActor New(const Text& text, Font font, bool fontDetection);
 175
 176   /**
 177    * @brief Create a TextActor object.
 178    *
 179    * @param [in] text          The text which will be displayed
 180    * @param [in] font          The font which will be used for the text
 181    * @param [in] fontDetection Try to detect font in case text is not supported with current one.
 182    * @param [in] isLeftToRight Text is displayed from left to right if true, otherwise from right to left.
 183    * @return A handle to a newly allocated Dali resource.
 184    */
 185   static TextActor New(const std::string& text, Font font, bool fontDetection, bool isLeftToRight);
 186
 187   /**
 188    * @copydoc New(const std::string& text, Font font, bool fontDetection, bool isLeftToRight)
 189    */
 190   static TextActor New(const Text& text, Font font, bool fontDetection, bool isLeftToRight);
 191
 192   /**
 193    * @brief Create a TextActor object.
 194    *
 195    * @param [in] text          The text which will be displayed
 196    * @param [in] style         The style which will be used for the text
 197    * @param [in] fontDetection Try to detect font in case text is not supported with current one.
 198    * @param [in] isLeftToRight Text is displayed from left to right if true, otherwise from right to left.
 199    * @return A handle to a newly allocated Dali resource.
 200    */
 201   static TextActor New(const Text& text, const TextStyle& style, bool fontDetection, bool isLeftToRight);
 202
 203   /**
 204    * @brief Downcast an Object handle to TextActor.
 205    *
 206    * If handle points to a TextActor the downcast produces valid
 207    * handle. If not the returned handle is left uninitialized.
 208    * @param[in] handle to An object
 209    * @return handle to a TextActor or an uninitialized handle
 210    */
 211   static TextActor DownCast( BaseHandle handle );
 212
 213   /**
 214    * @brief Virtual destructor.
 215    *
 216    * Dali::Object derived classes typically do not contain member data.
 217    */
 218   virtual ~TextActor();
 219
 220   /**
 221    * @copydoc Dali::BaseHandle::operator=
 222    */
 223   using BaseHandle::operator=;
 224
 225   /**
 226    * @brief Get the text label displayed by the actor.
 227    *
 228    * @pre The text actor has been initialized.
 229    * @return The text label
 230    */
 231   std::string GetText() const;
 232
 233   /**
 234    * @brief Set the text label displayed by the actor.
 235    *
 236    * @pre The text actor has been initialized.
 237    * @param [in] text The new text label
 238    */
 239   void SetText(const std::string& text);
 240
 241   /**
 242    * @copydoc  SetText(const std::string& text)
 243    */
 244   void SetText(const Text& text);
 245
 246   /**
 247    * @brief Set text to the natural size of the text string.
 248    *
 249    * After this method the text actor always uses the natural size of the text
 250    * when SetText is called unless SetSize is called to override the size.
 251    */
 252   void SetToNaturalSize();
 253
 254   /**
 255    * @brief Get the font used to display the text label displayed by the actor.
 256    *
 257    * @pre The text actor has been initialized.
 258    * @return The font currently in use
 259    */
 260   Font GetFont() const;
 261
 262   /**
 263    * @brief Set the font used to display the text label displayed by the actor.
 264    *
 265    * @pre The text actor has been initialized.
 266    * @param [in] font The new font
 267    */
 268   void SetFont(Font& font);
 269
 270   // styling and effects
 271
 272   /**
 273    * @brief Set the gradient color.
 274    *
 275    * This is the color associated with the gradient end point.
 276    * @param[in] color The gradient color (end-point color)
 277    */
 278   void SetGradientColor( const Vector4& color );
 279
 280   /**
 281    * @brief Get the gradient color.
 282    *
 283    * This is the color associated with the gradient end point.
 284    * @return The gradient color (end-point color)
 285    */
 286   Vector4 GetGradientColor() const;
 287
 288   /**
 289    * @brief Set the gradient start point.
 290    *
 291    * This is a 2D position between the coordinate range:
 292    * 0.0,0.0 (Left,Top) to 1.0,1.0 (Right,Bottom) within
 293    * the outputted Text. Actor::COLOR will represent this point
 294    * in the gradient.
 295    * @param[in] position The relative position of the gradient start point.
 296    */
 297   void SetGradientStartPoint( const Vector2& position );
 298
 299   /**
 300    * @brief Get the gradient start point.
 301    *
 302    * @return The relative position of the gradient start point.
 303    */
 304   Vector2 GetGradientStartPoint() const;
 305
 306   /**
 307    * @brief Set the gradient end point.
 308    *
 309    * This is a 2D position between the coordinate range:
 310    * 0.0,0.0 (Left,Top) to 1.0,1.0 (Right,Bottom) within
 311    * the outputted Text. TextActor::GRADIENT_COLOR will represent
 312    * this point in the gradient.
 313    * @param[in] position The relative position of the gradient end point.
 314    */
 315   void SetGradientEndPoint( const Vector2& position );
 316
 317   /**
 318    * @brief Get the gradient end point.
 319    *
 320    * @return The relative position of the gradient end point.
 321    */
 322   Vector2 GetGradientEndPoint() const;
 323
 324   /**
 325    * @brief Sets text style.
 326    *
 327    * @param[in] style The text style.
 328    */
 329   void SetTextStyle( const TextStyle& style );
 330
 331   /**
 332    * @brief Retrieves a copy of the text style.
 333    *
 334    * @return The text style.
 335    */
 336   TextStyle GetTextStyle() const;
 337
 338   /**
 339    * @brief Set the text color.
 340    *
 341    * This is blended with the Actor color
 342    * @param[in] color The text color (Default: WHITE)
 343    */
 344   void SetTextColor( const Vector4& color );
 345
 346   /**
 347    * @brief Get the text color.
 348    *
 349    * @return The text color.
 350    */
 351   Vector4 GetTextColor() const;
 352
 353   /**
 354    * @brief Set soft edge smoothing.
 355    *
 356    * @param[in] smoothEdge Specify the distance field value for the center of the text edge.
 357    *                   0 <= smoothEdge <= 1
 358    */
 359   void SetSmoothEdge(const float smoothEdge = TextStyle::DEFAULT_SMOOTH_EDGE_DISTANCE_FIELD);
 360
 361   /**
 362    * @brief Set text outlining.
 363    *
 364    * @param[in] enable  Set to true to enable text outlining.
 365    * @param[in] color   Outline color.
 366    * @param[in] thickness Thickness of outline. The outline thickness is determined by two parameters.
 367    *                      thickness[0] Specifies the distance field value for the center of the outline.
 368    *                      thickness[1] Specifies the softness/width/anti-aliasing of the outlines inner edge.
 369    *                      SetSmoothEdge() specifies the smoothness/anti-aliasing of the text outer edge.
 370    *                      0 <= smoothEdge[0] <= 1.
 371    *                      0 <= smoothEdge[1] <= 1.
 372    */
 373   void SetOutline(const bool enable, const Vector4& color, const Vector2& thickness = TextStyle::DEFAULT_OUTLINE_THICKNESS);
 374
 375   /**
 376    * @brief Set text glow.
 377    *
 378    * @param[in] enable  Set to true to enable text outer glow.
 379    * @param[in] color   Glow color.
 380    * @param[in] intensity Determines the amount of glow around text.
 381    *                      The edge of the text is at the value set with SetSmoothEdge().
 382    *                      SetSmoothEdge() The distance field value at which the glow becomes fully transparent.
 383    */
 384   void SetGlow(const bool enable, const Vector4& color, const float intensity = TextStyle::DEFAULT_GLOW_INTENSITY);
 385
 386   /**
 387    * @brief Set text shadow.
 388    *
 389    * @param[in] enable  Set to true to enable text drop shadow.
 390    * @param[in] color   Shadow color
 391    * @param[in] offset  Offset in pixels. To avoid cropping of the drop shadow limit the offset to PointSize / 3.5
 392    * @param[in] size    Size of shadow in pixels. 0 means the shadow is the same size as the text.
 393    */
 394   void SetShadow(const bool enable, const Vector4& color, const Vector2& offset = TextStyle::DEFAULT_SHADOW_OFFSET,
 395                  const float size = TextStyle::DEFAULT_SHADOW_SIZE );
 396
 397   /**
 398    * @brief Enable italics on the text actor, the text will be sheared by the given angle.
 399    *
 400    * @param[in] enabled True will enable italics, false disable it.
 401    * @param[in] angle Italics angle in degrees.
 402    */
 403   void SetItalics( const bool enabled, const Degree& angle = TextStyle::DEFAULT_ITALICS_ANGLE );
 404
 405   /**
 406    * @brief Enable italics on the text actor, the text will be sheared by the given angle.
 407    *
 408    * @param[in] enabled True will enable italics, false disable it.
 409    * @param[in] angle Italics angle in radians.
 410    */
 411   void SetItalics( const bool enabled, const Radian& angle );
 412
 413   /**
 414    * @brief Get text italics for the actor.
 415    *
 416    * @returns True if italics is enabled.
 417    */
 418   bool GetItalics() const;
 419
 420   /**
 421    * @brief Get text italics angle.
 422    *
 423    * @returns Angle as a Radian.
 424    */
 425   const Radian& GetItalicsAngle() const;
 426
 427   /**
 428    * @brief Set text underline.
 429    *
 430    * @param[in] enable Boolean indicating if the text should be underlined or not.
 431    */
 432   void SetUnderline( bool enable );
 433
 434   /**
 435    * @brief Get text underline.
 436    *
 437    * @return  Boolean indicating if the text should be underlined or not.
 438    */
 439   bool GetUnderline() const;
 440
 441   /**
 442    * @brief Set text weight.
 443    *
 444    * @param weight Text weight.
 445    */
 446   void SetWeight( TextStyle::Weight weight );
 447
 448   /**
 449    * @brief Get text weight.
 450    *
 451    * @return Text weight.
 452    */
 453   TextStyle::Weight GetWeight() const;
 454
 455   /**
 456    * @brief Try to detect font in case text is not supported with current one.
 457    *
 458    * @param [in] value true or false
 459    */
 460   void SetFontDetectionAutomatic(bool value);
 461
 462   /**
 463    * @brief Query whether TextActor is using automatic font detection.
 464    *
 465    * @return true or false
 466    */
 467   bool IsFontDetectionAutomatic() const;
 468
 469   /**
 470    * @brief Query whether the font has been loaded and built.
 471    *
 472    * Should be used by the application to determine whether the font
 473    * is ready to be queried for metrics
 474    * @return The loading state, either Loading, Success or Failed.
 475    */
 476   LoadingState GetLoadingState() const;
 477
 478   /**
 479    * @brief Emitted when text loads successfully and is available for displaying, or when the loading fails.
 480    *
 481    * @return A signal object to Connect() with.
 482    */
 483   TextSignalV2& TextAvailableSignal();
 484
 485 public: // Not intended for use by Application developers
 486
 487   /**
 488    * @brief This constructor is used by Dali New() methods
 489    * e
 490    * @param [in] actor A pointer to a newly allocated Dali resource
 491    */
 492   explicit DALI_INTERNAL TextActor(Internal::TextActor* actor);
 493 };
 494
 495 } // namespace Dali
 496
 497 /**
 498  * @}
 499  */
 500 #endif // __DALI_TEXT_ACTOR_H__