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