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_FRAMEWORK
  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  * 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;
  62
  63   //Signal Names
  64   static const char* const SIGNAL_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    * Create an uninitialized TextActor handle. This can be initialised with TextActor::New().
  92    * Calling member functions with an uninitialized handle is not allowed.
  93    */
  94   TextActor();
  95
  96   /**
  97    * Create a TextActor object with no text
  98    * @return A handle to a newly allocated Dali resource.
  99    */
 100   static TextActor New();
 101
 102   /**
 103    * Create a TextActor object with LeftToRight text and font detection
 104    * @param [in] text          The text which will be displayed
 105    * @return A handle to a newly allocated Dali resource.
 106    */
 107   static TextActor New(const std::string& text);
 108
 109   /**
 110    * @copydoc New(const std::string& text)
 111    */
 112   static TextActor New(const Text& text);
 113
 114   /**
 115    * Create a TextActor object with LeftToRight text
 116    * @param [in] text          The text which will be displayed
 117    * @param [in] fontDetection Try to detect font in case text is not supported with current one.
 118    * @return A handle to a newly allocated Dali resource.
 119    */
 120   static TextActor New(const std::string& text, bool fontDetection);
 121
 122   /**
 123    * @copydoc New(const std::string& text, bool fontDetection)
 124    */
 125   static TextActor New(const Text& text, bool fontDetection);
 126
 127   /**
 128    * Create a TextActor object
 129    * @param [in] text          The text which will be displayed
 130    * @param [in] fontDetection Try to detect font in case text is not supported with current one.
 131    * @param [in] isLeftToRight Text is displayed from left to right if true, otherwise from right to left.
 132    * @return A handle to a newly allocated Dali resource.
 133    */
 134   static TextActor New(const std::string& text, bool fontDetection, bool isLeftToRight);
 135
 136   /**
 137    * @copydoc New(const std::string& text, bool fontDetection, bool isLeftToRight)
 138    */
 139   static TextActor New(const Text& text, bool fontDetection, bool isLeftToRight);
 140
 141   /**
 142    * Create a TextActor object with LeftToRight text and font detection
 143    * @param [in] text          The text which will be displayed
 144    * @param [in] font          The font which will be used for the text
 145    * @return A handle to a newly allocated Dali resource.
 146    */
 147   static TextActor New(const std::string& text, Font font);
 148
 149   /**
 150    * @copydoc New(const std::string& text, Font font)
 151    */
 152   static TextActor New(const Text& text, Font font);
 153
 154   /**
 155    * Create a TextActor object with LeftToRight text
 156    * @param [in] text          The text which will be displayed
 157    * @param [in] font          The font which will be used for the text
 158    * @param [in] fontDetection Try to detect font in case text is not supported with current one.
 159    * @return A handle to a newly allocated Dali resource.
 160    */
 161   static TextActor New(const std::string& text, Font font, bool fontDetection);
 162
 163   /**
 164    * @copydoc New(const std::string& text, Font font, bool fontDetection)
 165    */
 166   static TextActor New(const Text& text, Font font, bool fontDetection);
 167
 168   /**
 169    * Create a TextActor object
 170    * @param [in] text          The text which will be displayed
 171    * @param [in] font          The font which will be used for the text
 172    * @param [in] fontDetection Try to detect font in case text is not supported with current one.
 173    * @param [in] isLeftToRight Text is displayed from left to right if true, otherwise from right to left.
 174    * @return A handle to a newly allocated Dali resource.
 175    */
 176   static TextActor New(const std::string& text, Font font, bool fontDetection, bool isLeftToRight);
 177
 178   /**
 179    * @copydoc New(const std::string& text, Font font, bool fontDetection, bool isLeftToRight)
 180    */
 181   static TextActor New(const Text& text, Font font, bool fontDetection, bool isLeftToRight);
 182
 183   /**
 184    * Create a TextActor object
 185    * @param [in] text          The text which will be displayed
 186    * @param [in] style         The style which will be used for the text
 187    * @param [in] fontDetection Try to detect font in case text is not supported with current one.
 188    * @param [in] isLeftToRight Text is displayed from left to right if true, otherwise from right to left.
 189    * @return A handle to a newly allocated Dali resource.
 190    */
 191   static TextActor New(const Text& text, const TextStyle& style, bool fontDetection, bool isLeftToRight);
 192
 193   /**
 194    * Downcast an Object handle to TextActor. If handle points to a TextActor the
 195    * downcast produces valid handle. If not the returned handle is left uninitialized.
 196    * @param[in] handle to An object
 197    * @return handle to a TextActor or an uninitialized handle
 198    */
 199   static TextActor DownCast( BaseHandle handle );
 200
 201   /**
 202    * Virtual destructor.
 203    * Dali::Object derived classes typically do not contain member data.
 204    */
 205   virtual ~TextActor();
 206
 207   /**
 208    * @copydoc Dali::BaseHandle::operator=
 209    */
 210   using BaseHandle::operator=;
 211
 212   /**
 213    * Get the text label displayed by the actor
 214    * @pre The text actor has been initialized.
 215    * @return The text label
 216    */
 217   std::string GetText() const;
 218
 219   /**
 220    * Set the text label displayed by the actor
 221    * @pre The text actor has been initialized.
 222    * @param [in] text The new text label
 223    */
 224   void SetText(const std::string& text);
 225
 226   /**
 227    * @copydoc  SetText(const std::string& text)
 228    */
 229   void SetText(const Text& text);
 230
 231   /**
 232    * Set text to the natural size of the text string
 233    * After this method the text actor always uses the natural size of the text
 234    * when SetText is called unless SetSize is called to override the size.
 235    */
 236   void SetToNaturalSize();
 237
 238   /**
 239    * Get the font used to display the text label displayed by the actor
 240    * @pre The text actor has been initialized.
 241    * @return The font currently in use
 242    */
 243   Font GetFont() const;
 244
 245   /**
 246    * Set the font used to display the text label displayed by the actor
 247    * @pre The text actor has been initialized.
 248    * @param [in] font The new font
 249    */
 250   void SetFont(Font& font);
 251
 252   // styling and effects
 253
 254   /**
 255    * Set the gradient color
 256    * This is the color associated with the gradient end point.
 257    * @param[in] color The gradient color (end-point color)
 258    */
 259   void SetGradientColor( const Vector4& color );
 260
 261   /**
 262    * Get the gradient color
 263    * This is the color associated with the gradient end point.
 264    * @return The gradient color (end-point color)
 265    */
 266   Vector4 GetGradientColor() const;
 267
 268   /**
 269    * Set the gradient start point.
 270    * This is a 2D position between the coordinate range:
 271    * 0.0,0.0 (Left,Top) to 1.0,1.0 (Right,Bottom) within
 272    * the outputted Text. Actor::COLOR will represent this point
 273    * in the gradient.
 274    * @param[in] position The relative position of the gradient start point.
 275    */
 276   void SetGradientStartPoint( const Vector2& position );
 277
 278   /**
 279    * Get the gradient start point.
 280    * @return The relative position of the gradient start point.
 281    */
 282   Vector2 GetGradientStartPoint() const;
 283
 284   /**
 285    * Set the gradient end point.
 286    * This is a 2D position between the coordinate range:
 287    * 0.0,0.0 (Left,Top) to 1.0,1.0 (Right,Bottom) within
 288    * the outputted Text. TextActor::GRADIENT_COLOR will represent
 289    * this point in the gradient.
 290    * @param[in] position The relative position of the gradient end point.
 291    */
 292   void SetGradientEndPoint( const Vector2& position );
 293
 294   /**
 295    * Get the gradient end point.
 296    * @return The relative position of the gradient end point.
 297    */
 298   Vector2 GetGradientEndPoint() const;
 299
 300   /**
 301    * Sets text style.
 302    * @param[in] style The text style.
 303    */
 304   void SetTextStyle( const TextStyle& style );
 305
 306   /**
 307    * Retrieves a copy of the text style.
 308    * @return The text style.
 309    */
 310   TextStyle GetTextStyle() const;
 311
 312   /**
 313    * Set the text color. This is blended with the Actor color
 314    * @param[in] color The text color (Default: WHITE)
 315    */
 316   void SetTextColor( const Vector4& color );
 317
 318   /**
 319    * Get the text color.
 320    * @return The text color.
 321    */
 322   Vector4 GetTextColor() const;
 323
 324   /**
 325    * Set soft edge smoothing
 326    * @param[in] smoothEdge Specify the distance field value for the center of the text edge.
 327    *                   0 <= smoothEdge <= 1
 328    */
 329   void SetSmoothEdge(const float smoothEdge = TextStyle::DEFAULT_SMOOTH_EDGE_DISTANCE_FIELD);
 330
 331   /**
 332    * Set text outlining
 333    * @param[in] enable  Set to true to enable text outlining.
 334    * @param[in] color   Outline color.
 335    * @param[in] thickness Thickness of outline. The outline thickness is determined by two parameters.
 336    *                      thickness[0] Specifies the distance field value for the center of the outline.
 337    *                      thickness[1] Specifies the softness/width/anti-aliasing of the outlines inner edge.
 338    *                      SetSmoothEdge() specifies the smoothness/anti-aliasing of the text outer edge.
 339    *                      0 <= smoothEdge[0] <= 1.
 340    *                      0 <= smoothEdge[1] <= 1.
 341    */
 342   void SetOutline(const bool enable, const Vector4& color, const Vector2& thickness = TextStyle::DEFAULT_OUTLINE_THICKNESS);
 343
 344   /**
 345    * Set text glow
 346    * @param[in] enable  Set to true to enable text outer glow.
 347    * @param[in] color   Glow color.
 348    * @param[in] intensity Determines the amount of glow around text.
 349    *                      The edge of the text is at the value set with SetSmoothEdge().
 350    *                      SetSmoothEdge() The distance field value at which the glow becomes fully transparent.
 351    */
 352   void SetGlow(const bool enable, const Vector4& color, const float intensity = TextStyle::DEFAULT_GLOW_INTENSITY);
 353
 354   /**
 355    * Set text shadow
 356    * @param[in] enable  Set to true to enable text drop shadow.
 357    * @param[in] color   Shadow color
 358    * @param[in] offset  Offset in pixels. To avoid cropping of the drop shadow limit the offset to PointSize / 3.5
 359    * @param[in] size    Size of shadow in pixels. 0 means the shadow is the same size as the text.
 360    */
 361   void SetShadow(const bool enable, const Vector4& color, const Vector2& offset = TextStyle::DEFAULT_SHADOW_OFFSET,
 362                  const float size = TextStyle::DEFAULT_SHADOW_SIZE );
 363
 364   /**
 365    * Enable italics on the text actor, the text will be sheared by the given angle.
 366    * @param[in] enabled True will enable italics, false disable it.
 367    * @param[in] angle Italics angle in degrees.
 368    */
 369   void SetItalics( const bool enabled, const Degree& angle = TextStyle::DEFAULT_ITALICS_ANGLE );
 370
 371   /**
 372    * Enable italics on the text actor, the text will be sheared by the given angle.
 373    * @param[in] enabled True will enable italics, false disable it.
 374    * @param[in] angle Italics angle in radians.
 375    */
 376   void SetItalics( const bool enabled, const Radian& angle );
 377
 378   /**
 379    * Get text italics for the actor.
 380    * @returns True if italics is enabled.
 381    */
 382   bool GetItalics() const;
 383
 384   /**
 385    * Get text italics angle.
 386    * @returns Angle as a Radian.
 387    */
 388   const Radian& GetItalicsAngle() const;
 389
 390   /**
 391    * Set text underline.
 392    * @param[in] enable Boolean indicating if the text should be underlined or not.
 393    */
 394   void SetUnderline( bool enable );
 395
 396   /**
 397    * Get text underline.
 398    * @return  Boolean indicating if the text should be underlined or not.
 399    */
 400   bool GetUnderline() const;
 401
 402   /**
 403    * Set text weight.
 404    * @param weight Text weight.
 405    */
 406   void SetWeight( TextStyle::Weight weight );
 407
 408   /**
 409    * Get text weight.
 410    * @return Text weight.
 411    */
 412   TextStyle::Weight GetWeight() const;
 413
 414   /**
 415    * Try to detect font in case text is not supported with current one.
 416    * @param [in] value true or false
 417    */
 418   void SetFontDetectionAutomatic(bool value);
 419
 420   /**
 421    * Query whether TextActor is using automatic font detection.
 422    * @return true or false
 423    */
 424   bool IsFontDetectionAutomatic() const;
 425
 426   /**
 427    * Query whether the font has been loaded and built. Should be used by the application to determine whether the
 428    * font is ready to be queried for metrics
 429    * @return The loading state, either Loading, Success or Failed.
 430    */
 431   LoadingState GetLoadingState() const;
 432
 433   /**
 434    * Emitted when text loads successfully and is available for displaying, or when the loading fails.
 435    * @return A signal object to Connect() with.
 436    */
 437   TextSignalV2& TextAvailableSignal();
 438
 439 public: // Not intended for use by Application developers
 440
 441   /**
 442    * This constructor is used by Dali New() methods
 443    * @param [in] actor A pointer to a newly allocated Dali resource
 444    */
 445   explicit DALI_INTERNAL TextActor(Internal::TextActor* actor);
 446 };
 447
 448 } // namespace Dali
 449
 450 /**
 451  * @}
 452  */
 453 #endif // __DALI_TEXT_ACTOR_H__