dali-toolkit/public-api/controls/text-controls/text-label.h

   1 #ifndef __DALI_TOOLKIT_TEXT_LABEL_H__
   2 #define __DALI_TOOLKIT_TEXT_LABEL_H__
   3
   4 /*
   5  * Copyright (c) 2017 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 // INTERNAL INCLUDES
  22 #include <dali-toolkit/public-api/controls/control.h>
  23
  24 namespace Dali
  25 {
  26
  27 namespace Toolkit
  28 {
  29
  30 namespace Internal DALI_INTERNAL
  31 {
  32 class TextLabel;
  33 }
  34 /**
  35  * @addtogroup dali_toolkit_controls_text_controls
  36  * @{
  37  */
  38
  39 /**
  40  * @brief A control which renders a short text string.
  41  *
  42  * Text labels are lightweight, non-editable and do not respond to user input.
  43  *
  44  * @section TextLabelProperties Properties
  45  * |%Property enum                    |String name          |Type            |Writable|Animatable|
  46  * |----------------------------------|---------------------|----------------|--------|----------|
  47  * | Property::RENDERING_BACKEND      | renderingBackend    |  INTEGER       | O      | X        |
  48  * | Property::TEXT                   | text                |  STRING        | O      | X        |
  49  * | Property::FONT_FAMILY            | fontFamily          |  STRING        | O      | X        |
  50  * | Property::FONT_STYLE             | fontStyle           |  STRING or MAP | O      | X        |
  51  * | Property::POINT_SIZE             | pointSize           |  FLOAT         | O      | X        |
  52  * | Property::MULTI_LINE             | multiLine           |  BOOLEAN       | O      | X        |
  53  * | Property::HORIZONTAL_ALIGNMENT   | horizontalAlignment |  STRING        | O      | X        |
  54  * | Property::VERTICAL_ALIGNMENT     | verticalAlignment   |  STRING        | O      | X        |
  55  * | Property::TEXT_COLOR             | textColor           |  VECTOR4       | O      | X        |
  56  * | Property::ENABLE_MARKUP          | enableMarkup        |  BOOLEAN       | O      | X        |
  57  * | Property::ENABLE_AUTO_SCROLL     | enableAutoScroll    |  BOOLEAN       | O      | X        |
  58  * | Property::AUTO_SCROLL_SPEED      | autoScrollSpeed     |  INTEGER       | O      | X        |
  59  * | Property::AUTO_SCROLL_LOOP_COUNT | autoScrollLoopCount |  INTEGER       | O      | X        |
  60  * | Property::AUTO_SCROLL_GAP        | autoScrollGap       |  INTEGER       | O      | X        |
  61  * | Property::SHADOW                 | shadow              |  STRING or MAP | O      | X        |
  62  * | Property::UNDERLINE              | underline           |  STRING or MAP | O      | X        |
  63  *
  64  * @SINCE_1_0.0
  65  */
  66 class DALI_IMPORT_API TextLabel : public Control
  67 {
  68 public:
  69
  70   /**
  71    * @brief Enumeration for the start and end property ranges for this control.
  72    * @SINCE_1_0.0
  73    */
  74   enum PropertyRange
  75   {
  76     PROPERTY_START_INDEX = Control::CONTROL_PROPERTY_END_INDEX + 1, ///< @SINCE_1_0.0
  77     PROPERTY_END_INDEX =   PROPERTY_START_INDEX + 1000,             ///< Reserve property indices @SINCE_1_0.0
  78
  79     ANIMATABLE_PROPERTY_START_INDEX = ANIMATABLE_PROPERTY_REGISTRATION_START_INDEX, ///< @SINCE_1_2.60
  80     ANIMATABLE_PROPERTY_END_INDEX =   ANIMATABLE_PROPERTY_REGISTRATION_START_INDEX + 1000 ///< Reserve animatable property indices @SINCE_1_2.60
  81   };
  82
  83   /**
  84    * @brief Enumeration for the instance of properties belonging to the TextLabel class.
  85    * @SINCE_1_0.0
  86    */
  87   struct Property
  88   {
  89     /**
  90      * @brief Enumeration for the instance of properties belonging to the TextLabel class.
  91      * @SINCE_1_0.0
  92      */
  93     enum
  94     {
  95       ///////////////////////////////////////////////////////////////////////////////
  96       // Event side (non-animatable) properties
  97       ///////////////////////////////////////////////////////////////////////////////
  98
  99       /**
 100        * @DEPRECATED_1_2.53 No longer be supported and will be ignored.
 101        * @brief The type of rendering e.g. bitmap-based.
 102        * @details Name "renderingBackend", type Property::INT.
 103        * @SINCE_1_0.0
 104        */
 105       RENDERING_BACKEND = PROPERTY_START_INDEX,
 106
 107       /**
 108        * @brief The text to display in UTF-8 format.
 109        * @details Name "text", type Property::STRING.
 110        * @SINCE_1_0.0
 111        */
 112       TEXT,
 113
 114       /**
 115        * @brief The requested font family to use.
 116        * @details Name "fontFamily", type Property::STRING.
 117        * @SINCE_1_0.0
 118        */
 119       FONT_FAMILY,
 120
 121       /**
 122        * @brief The requested font style to use.
 123        * @details Name "fontStyle", type Property::STRING or Property::MAP.
 124        * @SINCE_1_2.13
 125        */
 126       FONT_STYLE,
 127
 128       /**
 129        * @brief The size of font in points.
 130        * @details Name "pointSize", type Property::FLOAT.
 131        *          Conversion from Pixel size to Point size:
 132        *           Point size = Pixel size * 72 / DPI
 133        * @SINCE_1_0.0
 134        */
 135       POINT_SIZE,
 136
 137       /**
 138        * @brief The single-line or multi-line layout option.
 139        * @details Name "multiLine", type Property::BOOLEAN.
 140        * @SINCE_1_0.0
 141        * @note Default is false.
 142        */
 143       MULTI_LINE,
 144
 145       /**
 146        * @brief The line horizontal alignment.
 147        * @details Name "horizontalAlignment", type Property::STRING or type HorizontalAlignment::Type (Property::INTEGER)
 148        *          Values "BEGIN", "CENTER", "END", default BEGIN.
 149        * @note Return type is Property::STRING
 150        * @SINCE_1_0.0
 151        */
 152       HORIZONTAL_ALIGNMENT,
 153
 154       /**
 155        * @brief The line vertical alignment.
 156        * @details Name "verticalAlignment", type Property::STRING or type VerticalAlignment::Type (Property::INTEGER).
 157        *          Values "TOP",   "CENTER", "BOTTOM" @SINCE_1_0.0, default TOP.
 158        * @note Return type is Property::STRING
 159        * @SINCE_1_0.0
 160        */
 161       VERTICAL_ALIGNMENT,
 162
 163       /**
 164        * @DEPRECATED_1_2.60 Use the new enum value of TEXT_COLOR instead.
 165        * @brief The color of the text.
 166        * @details Name "unusedPropertyTextColor", type Property::VECTOR4.
 167        * @SINCE_1_0.0
 168        */
 169       UNUSED_PROPERTY_TEXT_COLOR,
 170
 171       /**
 172        * @DEPRECATED_1_1.37 Use SHADOW instead
 173        * @brief The drop shadow offset 0 indicates no shadow.
 174        * @details Name "shadowOffset", type Property::VECTOR2.
 175        */
 176       SHADOW_OFFSET,
 177
 178       /**
 179        * @DEPRECATED_1_1.37 Use SHADOW instead
 180        * @brief The color of a drop shadow.
 181        * @details Name "shadowColor", type Property::VECTOR4
 182        */
 183       SHADOW_COLOR,
 184
 185       /**
 186        * @DEPRECATED_1_1.37 Use UNDERLINE instead
 187        * @brief The underline enabled flag.
 188        * @details Name "underlineEnabled", type Property::BOOLEAN.
 189        */
 190       UNDERLINE_ENABLED,
 191
 192       /**
 193        * @DEPRECATED_1_1.37 Use UNDERLINE instead
 194        * @brief The color of the underline.
 195        * @details Name "underlineColor", type Property::VECTOR4.
 196        */
 197       UNDERLINE_COLOR,
 198
 199       /**
 200        * @DEPRECATED_1_1.37 Use UNDERLINE instead
 201        * @brief Overrides the underline height from font metrics.
 202        * @details Name "underlineHeight", type Property::FLOAT.
 203        */
 204       UNDERLINE_HEIGHT,
 205
 206       /**
 207        * @brief Whether the mark-up processing is enabled.
 208        * @details Name "enableMarkup", type Property::BOOLEAN.
 209        * @SINCE_1_0.0
 210        * @note Default is false.
 211        */
 212       ENABLE_MARKUP,
 213
 214       /**
 215        * @brief Starts or stops auto scrolling.
 216        * @details Name "enableAutoScroll", type Property::BOOLEAN.
 217        * @SINCE_1_1.35
 218        * @note Default is false.
 219        */
 220       ENABLE_AUTO_SCROLL,
 221
 222       /**
 223        * @brief Sets the speed of scrolling in pixels per second.
 224        * @details Name "autoScrollSpeed", type Property::INT.
 225        * @SINCE_1_1.35
 226        * @note Default in style sheet.
 227        */
 228       AUTO_SCROLL_SPEED,
 229
 230       /**
 231        * @brief Number of complete loops when scrolling enabled.
 232        * @details Name "autoScrollLoopCount", type Property::INT.
 233        * @SINCE_1_1.35
 234        * @note Default in style sheet.
 235        */
 236       AUTO_SCROLL_LOOP_COUNT,
 237
 238       /**
 239        * @brief Gap before scrolling wraps.
 240        * @details Name "autoScrollGap", type Property::INT.
 241        * @SINCE_1_1.35
 242        * @note Default in style sheet but can be overridden to prevent same text being shown at start and end.
 243        * @note Displayed gap size is not guaranteed if the text length plus gap exceeds the maximum texture size (i.e. GL_MAX_TEXTURE_SIZE).
 244        */
 245       AUTO_SCROLL_GAP,
 246
 247       /**
 248        * @brief The default extra space between lines in points.
 249        * @details Name "lineSpacing", type Property::FLOAT.
 250        * @SINCE_1_1.37
 251        */
 252       LINE_SPACING,
 253
 254       /**
 255        * @brief The default underline parameters.
 256        * @details Name "underline", type Property::MAP.
 257        *
 258        * The underline map contains the following keys:
 259        *
 260        * | %Property Name       | Type     | Required | Description                                                                                                        |
 261        * |----------------------|----------|----------|--------------------------------------------------------------------------------------------------------------------|
 262        * | enable               | BOOLEAN  | No       | True to enable the underline or false to disable (the default value is false)                                      |
 263        * | color                | VECTOR4  | No       | The color of the underline (the default value is Color::BLACK)                                                     |
 264        * | height               | FLOAT    | No       | The height of the underline (the default value is 0)                                                               |
 265        *
 266        * @SINCE_1_2.13
 267        */
 268       UNDERLINE,
 269
 270       /**
 271        * @brief The default shadow parameters.
 272        * @details Name "shadow", type Property::MAP.
 273        *
 274        * The shadow map contains the following keys:
 275        *
 276        * | %Property Name       | Type     | Required | Description                                                                                                        |
 277        * |----------------------|----------|----------|--------------------------------------------------------------------------------------------------------------------|
 278        * | color                | VECTOR4  | No       | The color of the shadow (the default value is Color::BLACK)                                                        |
 279        * | offset               | VECTOR2  | No       | The offset from the text to draw the shadow in the X and Y axes (the default value is 0 which means no shadow)     |
 280        * | blurRadius           | FLOAT    | No       | The radius of blur to be applied to the shadow (the default value is 0 which means no blur)                        |
 281        *
 282        * @SINCE_1_2.13
 283        */
 284       SHADOW,
 285
 286       /**
 287        * @brief The default emboss parameters.
 288        * @details Name "emboss", type Property::MAP.
 289        * @SINCE_1_2.13
 290        */
 291       EMBOSS,
 292
 293       /**
 294        * @brief The default outline parameters.
 295        * @details Name "outline", type Property::MAP.
 296        *
 297        * The outline map contains the following keys:
 298        *
 299        * | %Property Name       | Type     | Required | Description                                                                                                        |
 300        * |----------------------|----------|----------|--------------------------------------------------------------------------------------------------------------------|
 301        * | color                | VECTOR4  | No       | The color of the outline (the default value is Color::WHITE)                                                       |
 302        * | width                | INTEGER  | No       | The width of the outline (the default value is 0 which means no outline)                                           |
 303        *
 304        * @SINCE_1_2.13
 305        */
 306       OUTLINE,
 307
 308       /**
 309        * @brief The size of font in pixels.
 310        * @details Name "pixelSize", type Property::FLOAT.
 311        *          Conversion from Point size to Pixel size:
 312        *            Pixel size = Point size * DPI / 72
 313        * @SINCE_1_2.60
 314        */
 315       PIXEL_SIZE,
 316
 317       /**
 318        * @brief Whether we should show the ellipsis if required.
 319        * @details Name "ellipsis", type Property::BOOLEAN.
 320        * @SINCE_1_2.60
 321        */
 322       ELLIPSIS,
 323
 324       /**
 325        * @brief The amount of time to delay the starting time of auto scrolling and further loops.
 326        * @details Name "autoScrollLoopDelay", type Property::FLOAT.
 327        * @SINCE_1_2.60
 328        */
 329       AUTO_SCROLL_LOOP_DELAY,
 330
 331       /**
 332        * @brief The auto scrolling stop behaviour.
 333        * @details Name "autoScrollStopMode", type AutoScrollStopMode::Type (Property::INTEGER) or Property::STRING.
 334        * @SINCE_1_2.60
 335        * @note Default is AutoScrollStopMode::FINISH_LOOP.
 336        * @see AutoScrollStopMode::Type
 337        */
 338       AUTO_SCROLL_STOP_MODE,
 339
 340       /*
 341        * @brief The line count of text.
 342        * @details name "lineCount", type Property::INTEGER.
 343        * @SINCE_1_2.60
 344        * @note This property is read-only.
 345        */
 346       LINE_COUNT,
 347
 348       /**
 349        * @brief Line wrap mode when text lines are greater than the layout width.
 350        * @details Name "lineWrapMode", type Text::LineWrap::Mode (Text::Property::INTEGER) or Property::STRING.
 351        * @SINCE_1_2.60
 352        * @note Default is Text::LineWrap::WORD.
 353        * @note Return type is Text::LineWrap::Mode (Text::Property::INTEGER).
 354        * @see Text::LineWrap
 355        */
 356       LINE_WRAP_MODE,
 357
 358       ///////////////////////////////////////////////////////////////////////////////
 359       // Animatable Properties
 360       ///////////////////////////////////////////////////////////////////////////////
 361
 362       /**
 363        * @brief The color of the text.
 364        * @details Name "textColor", type Property::VECTOR4.
 365        * @SINCE_1_2.60
 366        */
 367       TEXT_COLOR = ANIMATABLE_PROPERTY_START_INDEX,
 368
 369       /**
 370        * @brief The red component of the text color.
 371        * @details Name "textColorRed", type Property::FLOAT.
 372        * @SINCE_1_2.60
 373        * @see TEXT_COLOR
 374        */
 375       TEXT_COLOR_RED,
 376
 377       /**
 378        * @brief The green component of the text color.
 379        * @details Name "textColorGreen", type Property::FLOAT.
 380        * @SINCE_1_2.60
 381        * @see TEXT_COLOR
 382        */
 383       TEXT_COLOR_GREEN,
 384
 385       /**
 386        * @brief The blue component of the text color.
 387        * @details Name "textColorBlue", type Property::FLOAT.
 388        * @SINCE_1_2.60
 389        * @see TEXT_COLOR
 390        */
 391       TEXT_COLOR_BLUE,
 392
 393       /**
 394        * @brief The alpha component of the text color.
 395        * @details Name "textColorAlpha", type Property::FLOAT.
 396        * @SINCE_1_2.60
 397        * @see TEXT_COLOR
 398        */
 399       TEXT_COLOR_ALPHA,
 400     };
 401   };
 402
 403   /**
 404    * @brief The enumerations used for auto scroll stop mode.
 405    * @SINCE_1_2.60
 406    * @see Property::AUTO_SCROLL_STOP_MODE.
 407    */
 408   struct AutoScrollStopMode
 409   {
 410     /**
 411      * @brief The enumerations used for auto scroll stop mode.
 412      * @SINCE_1_2.60
 413      * @see Property::AUTO_SCROLL_STOP_MODE.
 414      */
 415     enum Type
 416     {
 417       FINISH_LOOP = 0,  ///< Stop animation after current loop finishes. @SINCE_1_2.60
 418       IMMEDIATE         ///< Stop animation immediately and reset position. @SINCE_1_2.60
 419     };
 420   };
 421
 422   /**
 423    * @brief Creates the TextLabel control.
 424    *
 425    * @SINCE_1_0.0
 426    * @return A handle to the TextLabel control
 427    */
 428   static TextLabel New();
 429
 430   /**
 431    * @brief Creates the TextLabel control.
 432    *
 433    * @SINCE_1_0.0
 434    * @param[in] text The text to display
 435    * @return A handle to the TextLabel control
 436    */
 437   static TextLabel New( const std::string& text );
 438
 439   /**
 440    * @brief Creates an empty handle.
 441    * @SINCE_1_0.0
 442    */
 443   TextLabel();
 444
 445   /**
 446    * @brief Copy constructor.
 447    *
 448    * @SINCE_1_0.0
 449    * @param[in] handle The handle to copy from
 450    */
 451   TextLabel( const TextLabel& handle );
 452
 453   /**
 454    * @brief Assignment operator.
 455    *
 456    * @SINCE_1_0.0
 457    * @param[in] handle The handle to copy from
 458    * @return A reference to this
 459    */
 460   TextLabel& operator=( const TextLabel& handle );
 461
 462   /**
 463    * @brief Destructor.
 464    *
 465    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 466    * @SINCE_1_0.0
 467    */
 468   ~TextLabel();
 469
 470   /**
 471    * @brief Downcasts a handle to TextLabel.
 472    *
 473    * If the BaseHandle points is a TextLabel, the downcast returns a valid handle.
 474    * If not, the returned handle is left empty.
 475    *
 476    * @SINCE_1_0.0
 477    * @param[in] handle Handle to an object
 478    * @return Handle to a TextLabel or an empty handle
 479    */
 480   static TextLabel DownCast( BaseHandle handle );
 481
 482 public: // Not intended for application developers
 483
 484   /// @cond internal
 485   /**
 486    * @brief Creates a handle using the Toolkit::Internal implementation.
 487    *
 488    * @SINCE_1_0.0
 489    * @param[in] implementation The Control implementation
 490    */
 491   DALI_INTERNAL TextLabel( Internal::TextLabel& implementation );
 492
 493   /**
 494    * @brief Allows the creation of this Control from an Internal::CustomActor pointer.
 495    *
 496    * @SINCE_1_0.0
 497    * @param[in] internal A pointer to the internal CustomActor
 498    */
 499   explicit DALI_INTERNAL TextLabel( Dali::Internal::CustomActor* internal );
 500   /// @endcond
 501 };
 502
 503 /**
 504  * @}
 505  */
 506 } // namespace Toolkit
 507
 508 } // namespace Dali
 509
 510 #endif // __DALI_TOOLKIT_TEXT_LABEL_H__