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