capi/dali/public-api/text/text-style.h

   1 #ifndef __DALI_TEXT_STYLE_H__
   2 #define __DALI_TEXT_STYLE_H__
   3
   4 /*
   5  * Copyright (c) 2014 Samsung Electronics Co., Ltd.
   6  *
   7  * Licensed under the Apache License, Version 2.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://www.apache.org/licenses/LICENSE-2.0
  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_TEXT_MODULE
  23  * @{
  24  */
  25
  26 // EXTERNAL INCLUDES
  27 #include <string>
  28
  29 // INTERNAL INCLUDES
  30 #include <dali/public-api/text/font.h>
  31
  32 namespace Dali DALI_IMPORT_API
  33 {
  34
  35 /**
  36  * @brief Encapsulates style properties for text, such as weight, italics, underline, shadow, etc.
  37  */
  38 class TextStyle
  39 {
  40 public:
  41   /**
  42    * @brief Mask used to set text styles.
  43    */
  44   enum Mask
  45   {
  46     FONT =      1 << 0, ///< Sets the given font family.
  47     STYLE =     1 << 1, ///< Sets the given font style.
  48     SIZE =      1 << 2, ///< Sets the given font point size.
  49     WEIGHT =    1 << 3, ///< Sets the given font weight to bold.
  50     COLOR =     1 << 4, ///< Sets the given text color.
  51     ITALICS =   1 << 5, ///< Sets italics.
  52     UNDERLINE = 1 << 6, ///< Sets underline.
  53     SHADOW =    1 << 7, ///< Sets shadow.
  54     GLOW =      1 << 8, ///< Sets glow.
  55     OUTLINE =   1 << 9, ///< Sets outline
  56     ALL =      -1       ///< Sets all given style parameters.
  57   };
  58
  59   /**
  60    * @brief Enumeration of various text weights.
  61    */
  62   enum Weight
  63   {
  64     THIN = 0,
  65     EXTRALIGHT,
  66     LIGHT,
  67     BOOK,
  68     REGULAR,
  69     MEDIUM,
  70     DEMIBOLD,
  71     BOLD,
  72     EXTRABOLD,
  73     BLACK,
  74     EXTRABLACK
  75   };
  76
  77 public:
  78   static const Degree  DEFAULT_ITALICS_ANGLE;              ///< Default angle used for text italics. @see SetItalics()
  79   static const float   DEFAULT_UNDERLINE_THICKNESS;        ///< Default underline's thickness.
  80   static const float   DEFAULT_UNDERLINE_POSITION;         ///< Default underline's position.
  81   static const Vector4 DEFAULT_TEXT_COLOR;                 ///< Default color for the text (white)
  82   static const Vector4 DEFAULT_SHADOW_COLOR;               ///< Default color for the shadow (black)
  83   static const Vector2 DEFAULT_SHADOW_OFFSET;              ///< Default offset used for text shadow. @see SetShadow()
  84   static const float   DEFAULT_SHADOW_SIZE;                ///< Default size of text shadow. @see SetShadow()
  85   static const Vector4 DEFAULT_GLOW_COLOR;                 ///< Default color for the glow (white)
  86   static const float   DEFAULT_GLOW_INTENSITY;             ///< Default intensity used for text glow. @see SetGlow()
  87   static const float   DEFAULT_SMOOTH_EDGE_DISTANCE_FIELD; ///< Default distance field used for edge smooth. @see SetSmoothEdge()
  88   static const Vector4 DEFAULT_OUTLINE_COLOR;              ///< Default color for the outline (white)
  89   static const Vector2 DEFAULT_OUTLINE_THICKNESS;          ///< Default thickness used for text outline. @see SetOutline()
  90   static const Vector4 DEFAULT_GRADIENT_COLOR;             ///< Default gradient color
  91   static const Vector2 DEFAULT_GRADIENT_START_POINT;       ///< Default gradient start point
  92   static const Vector2 DEFAULT_GRADIENT_END_POINT;         ///< Default gradient end point
  93
  94 public:
  95
  96   /**
  97    * @brief Default constructor.
  98    *
  99    * The style created used a default font @see Dali::Font, color is white, and is neither underlined nor italics.
 100    */
 101   TextStyle();
 102
 103   /**
 104    * @brief Copy constructor.
 105    *
 106    * @param[in] textStyle The text style to be copied.
 107    */
 108   TextStyle( const TextStyle& textStyle );
 109
 110   /**
 111    * @brief Destructor.
 112    */
 113   virtual ~TextStyle();
 114
 115   /**
 116    * @brief Assignment operator.
 117    *
 118    * @param[in] textStyle The text style to be assigned.
 119    * @return A reference to this
 120    */
 121   TextStyle& operator=( const TextStyle& textStyle );
 122
 123   /**
 124    * @brief Equality operator.
 125    *
 126    * @param [in] textStyle The text style to be compared.
 127    * @return true if the style is identical
 128    */
 129   bool operator==( const TextStyle& textStyle ) const;
 130
 131   /**
 132    * @brief Inequality operator.
 133    *
 134    * @param [in] textStyle The text style to be compared.
 135    * @return true if the text style is not identical
 136    */
 137   bool operator!=( const TextStyle& textStyle ) const;
 138
 139   /**
 140    * @brief Copies from the given text style those parameters specified in the given mask.
 141    *
 142    *
 143    * @param[in] textStyle The given text style.
 144    * @param[in] mask Specifies which text style parameters are going to be copied. By default all parateres are copied.
 145    */
 146   void Copy( const TextStyle& textStyle, const Mask mask = ALL );
 147
 148   /**
 149    * @brief Retrieves the font name.
 150    *
 151    * @return The font name.
 152    */
 153   const std::string& GetFontName() const;
 154
 155   /**
 156    * @brief Sets the font name.
 157    *
 158    * @param[in] fontName
 159    */
 160   void SetFontName( const std::string& fontName );
 161
 162   /**
 163    * @brief Retrieves the font style.
 164    *
 165    * @return The font style.
 166    */
 167   const std::string& GetFontStyle() const;
 168
 169   /**
 170    * @brief Sets the font style.
 171    *
 172    * @param[in] fontStyle
 173    */
 174   void SetFontStyle( const std::string& fontStyle );
 175
 176   /**
 177    * @brief Retrieves the font point size.
 178    *
 179    * @return the point size.
 180    */
 181   PointSize GetFontPointSize() const;
 182
 183   /**
 184    * @brief Sets the font point size.
 185    *
 186    * @param[in] fontPointSize The font point size.
 187    */
 188   void SetFontPointSize( PointSize fontPointSize );
 189
 190   /**
 191    * @brief Retrieves the style weight.
 192    *
 193    * @return The style weight.
 194    */
 195   Weight GetWeight() const;
 196
 197   /**
 198    * @brief Sets the style weight.
 199    *
 200    * @param[in] weight The style weight
 201    */
 202   void SetWeight( Weight weight );
 203
 204   /**
 205    * @brief Retrieves the text color.
 206    *
 207    * @return The text color.
 208    */
 209   const Vector4& GetTextColor() const;
 210
 211   /**
 212    * @brief Sets the text color.
 213    *
 214    * @param[in] textColor The text color
 215    */
 216   void SetTextColor( const Vector4& textColor );
 217
 218   /**
 219    * @brief Whether the style italics option is enabled or not.
 220    *
 221    * @return \e true if italics is enabled.
 222    */
 223   bool GetItalics() const;
 224
 225   /**
 226    * @brief Sets the italics option.
 227    *
 228    * @param[in] italics The italics option.
 229    */
 230   void SetItalics( bool italics );
 231
 232   /**
 233    * @brief Retrieves the italics angle.
 234    *
 235    * @return \e The italics angle in degree.
 236    */
 237   Degree GetItalicsAngle() const;
 238
 239   /**
 240    * @brief Sets the italics angle.
 241    *
 242    * @param[in] angle The italics angle in degree.
 243    */
 244   void SetItalicsAngle( Degree angle );
 245
 246   /**
 247    * @brief Whether the style underline option is enabled or not.
 248    *
 249    * @return \e true if underline is enabled.
 250    */
 251   bool GetUnderline() const;
 252
 253   /**
 254    * @brief Sets the underline option.
 255    *
 256    * @param[in] underline The underline option.
 257    */
 258   void SetUnderline( bool underline );
 259
 260   /**
 261    * @brief Retrieves the underline thickness.
 262    *
 263    * @return The underline thickness.
 264    */
 265   float GetUnderlineThickness() const;
 266
 267   /**
 268    * @brief Sets the underline thickness.
 269    *
 270    * @param[in] thickness The underline thickness.
 271    */
 272   void SetUnderlineThickness( float thickness );
 273
 274   /**
 275    * @brief Retrieves the underline position.
 276    *
 277    * @return The underline position.
 278    */
 279   float GetUnderlinePosition() const;
 280
 281   /**
 282    * @brief Sets the underline position.
 283    *
 284    * @param[in] position The underline position.
 285    */
 286   void SetUnderlinePosition( float position );
 287
 288   /**
 289    * @brief Whether the style shadow option is enabled or not.
 290    *
 291    * @return \e true if shadow is enabled.
 292    */
 293   bool GetShadow() const;
 294
 295   /**
 296    * @brief Retrieves the shadow color.
 297    *
 298    * @return The shadow color.
 299    */
 300   const Vector4& GetShadowColor() const;
 301
 302   /**
 303    * @brief Retrieves the shadow offset
 304    * @return The shadow offset.
 305    *
 306    */
 307   const Vector2& GetShadowOffset() const;
 308
 309   /**
 310    * @brief Retrieves the shadow size
 311    * @return The shadow size.
 312    *
 313    */
 314   float GetShadowSize() const;
 315
 316   /**
 317    * @brief Sets the shadow option.
 318    *
 319    * @param[in] shadow        The shadow option.
 320    * @param[in] shadowColor   The color of the shadow
 321    * @param[in] shadowOffset  Offset in pixels.
 322    * @param[in] shadowSize    Size of shadow in pixels. 0 means the shadow is the same size as the text.
 323    */
 324   void SetShadow( bool shadow,
 325                   const Vector4& shadowColor = DEFAULT_SHADOW_COLOR,
 326                   const Vector2& shadowOffset = DEFAULT_SHADOW_OFFSET,
 327                   const float shadowSize = DEFAULT_SHADOW_SIZE );
 328
 329   /**
 330    * @brief Whether the glow option is enabled or not.
 331    *
 332    * @return \e true if glow is enabled.
 333    */
 334   bool GetGlow() const;
 335
 336   /**
 337    * @brief Retrieves the glow color.
 338    *
 339    * @return The glow color.
 340    */
 341   const Vector4& GetGlowColor() const;
 342
 343   /**
 344    * @brief Retrieve the glow intensity.
 345    *
 346    * @return The glow intensity.
 347    */
 348   float GetGlowIntensity() const;
 349
 350   /**
 351    * @brief Sets the glow option and color.
 352    *
 353    * @param[in] glow The glow option.
 354    * @param[in] glowColor The color of the glow.
 355    * @param[in] glowIntensity Determines the amount of glow around text.
 356    *                          The edge of the text is at the value set with smoothEdge.
 357    *                          SetSmoothEdge() The distance field value at which the glow becomes fully transparent.
 358    */
 359   void SetGlow( bool glow, const Vector4& glowColor = DEFAULT_GLOW_COLOR, float glowIntensity = DEFAULT_GLOW_INTENSITY );
 360
 361   /**
 362    * @brief Retrieves the soft smooth edge.
 363    *
 364    * @return The soft smooth edge.
 365    */
 366   float GetSmoothEdge() const;
 367
 368   /**
 369    * @brief Set soft edge smoothing.
 370    *
 371    * @param[in] smoothEdge Specify the distance field value for the center of the text edge.
 372    *            0 <= smoothEdge <= 1
 373    */
 374   void SetSmoothEdge( float smoothEdge = DEFAULT_SMOOTH_EDGE_DISTANCE_FIELD );
 375
 376   /**
 377    * @brief Whether the outline option is enabled or not.
 378    *
 379    * @return \e true if outline is enabled.
 380    */
 381   bool GetOutline() const;
 382
 383   /**
 384    * @brief Retrieves the outline color.
 385    *
 386    * @return The outline color.
 387    */
 388   const Vector4& GetOutlineColor() const;
 389
 390   /**
 391    * @brief Retrieves the outline thickness.
 392    *
 393    * @return The outline thickness.
 394    */
 395   const Vector2& GetOutlineThickness() const;
 396
 397   /**
 398    * @brief Sets the outline option and color.
 399    *
 400    * @param[in] outline The outline option.
 401    * @param[in] outlineColor The color of the outline.
 402    * @param[in] outlineThickness Thickness of outline. The outline thickness is determined by two parameters.
 403    *                             outlineThickness[0] Specifies the distance field value for the center of the outline.
 404    *                             outlineThickness[1] Specifies the softness/width/anti-aliasing of the outlines inner edge.
 405    *                             SetSmoothEdge() specifies the smoothness/anti-aliasing of the text outer edge.
 406    *                             0 <= smoothEdge[0] <= 1.
 407    *                             0 <= smoothEdge[1] <= 1.
 408    */
 409   void SetOutline( bool outline, const Vector4& outlineColor = DEFAULT_OUTLINE_COLOR, const Vector2& outlineThickness = DEFAULT_OUTLINE_THICKNESS );
 410
 411 private:
 412   struct Impl;
 413   Impl* mImpl; ///< Implementation pointer
 414
 415   /**
 416    * @brief Creates A TextStyle::Impl object when needed
 417    */
 418   void CreateImplementationJustInTime();
 419
 420 };
 421
 422 } // namespace Dali
 423
 424 /**
 425  * @}
 426  */
 427 #endif // __DALI_TEXT_STYLE_H__