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) 2015 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      | 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      | O      | X        |
  62  * | Property::UNDERLINE              | underline           |  STRING      | O      | X        |
  63  *
  64  * @SINCE_1_0.0
  65  */
  66 class DALI_IMPORT_API TextLabel : public Control
  67 {
  68 public:
  69
  70   /**
  71    * @brief 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
  80   /**
  81    * @brief An enumeration of properties belonging to the TextLabel class.
  82    * @SINCE_1_0.0
  83    */
  84   struct Property
  85   {
  86     enum
  87     {
  88       /**
  89        * @brief The type of rendering e.g. bitmap-based
  90        * @details name "renderingBackend", type INT, default RENDERING_SHARED_ATLAS
  91        * @SINCE_1_0.0
  92        */
  93       RENDERING_BACKEND = PROPERTY_START_INDEX,
  94
  95       /**
  96        * @brief The text to display in UTF-8 format,
  97        * @details name "text", type STRING
  98        * @SINCE_1_0.0
  99        */
 100       TEXT,
 101
 102       /**
 103        * @brief The requested font family to use,
 104        * @details name "fontFamily", type 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 STRING
 112        * @SINCE_1_0.0
 113        */
 114       FONT_STYLE,
 115
 116       /**
 117        * @brief The size of font in points
 118        * @details name "pointSize", type FLOAT
 119        * @SINCE_1_0.0
 120        */
 121       POINT_SIZE,
 122
 123       /**
 124        * @brief The single-line or multi-line layout option
 125        * @details name "multiLine", type BOOLEAN, default false
 126        * @SINCE_1_0.0
 127        */
 128       MULTI_LINE,
 129
 130       /**
 131        * @brief The line horizontal alignment
 132        * @details name "horizontalAlignment", type STRING,  values "BEGIN", "CENTER", "END", default BEGIN
 133        * @SINCE_1_0.0
 134        */
 135       HORIZONTAL_ALIGNMENT,
 136
 137       /**
 138        * @brief The line vertical alignment
 139        * @details name "verticalAlignment", type STRING,  values "TOP",   "CENTER", "BOTTOM" @SINCE_1_0.0, default TOP
 140        * @SINCE_1_0.0
 141        */
 142       VERTICAL_ALIGNMENT,
 143
 144       /**
 145        * @brief The color of the text
 146        * @details name "textColor", type VECTOR4
 147        * @SINCE_1_0.0
 148        */
 149       TEXT_COLOR,
 150
 151       /**
 152        * @brief The drop shadow offset 0 indicates no shadow
 153        * @details name "shadowOffset", type VECTOR2
 154        * @DEPRECATED_1_1.37 Use SHADOW instead
 155        */
 156       SHADOW_OFFSET,
 157
 158       /**
 159        * @brief The color of a drop shadow
 160        * @details name "shadowColor", type VECTOR4
 161        * @DEPRECATED_1_1.37 Use SHADOW instead
 162        */
 163       SHADOW_COLOR,
 164
 165       /**
 166        * @brief The underline enabled flag
 167        * @details name "underlineEnabled", type BOOLEAN
 168        * @DEPRECATED_1_1.37 Use UNDERLINE instead
 169        */
 170       UNDERLINE_ENABLED,
 171
 172       /**
 173        * @brief The color of the underline
 174        * @details name "underlineColor", type VECTOR4
 175        * @DEPRECATED_1_1.37 Use UNDERLINE instead
 176        */
 177       UNDERLINE_COLOR,
 178
 179       /**
 180        * @brief Overrides the underline height from font metrics
 181        * @details name "underlineHeight", type FLOAT
 182        * @DEPRECATED_1_1.37 Use UNDERLINE instead
 183        */
 184       UNDERLINE_HEIGHT,
 185
 186       /**
 187        * @brief  Whether the mark-up processing is enabled
 188        * @details name "enableMarkup", type BOOLEAN
 189        * @SINCE_1_0.0
 190        */
 191       ENABLE_MARKUP,
 192
 193       /**
 194        * @brief  Start or stop auto scrolling,
 195        * @details name "enableAutoScroll", type BOOLEAN, default is false
 196        * @SINCE_1_1.35
 197        */
 198       ENABLE_AUTO_SCROLL,
 199
 200       /**
 201        * @brief Sets the speed of scrolling in pixels per second,
 202        * @details name "autoScrollSpeed", type INT, default in style sheet
 203        * @SINCE_1_1.35
 204        */
 205       AUTO_SCROLL_SPEED,
 206
 207       /**
 208        * @brief  Number of complete loops when scrolling enabled
 209        * @details name "autoScrollLoopCount", type INT, default in style sheet
 210        * @SINCE_1_1.35
 211        */
 212       AUTO_SCROLL_LOOP_COUNT,
 213
 214       /**
 215        * @brief  Gap before before scrolling wraps
 216        * @details name "autoScrollGap", type INT, default in style sheet but can be overridden to prevent same text being show at start and end.
 217        * @SINCE_1_1.35
 218        */
 219       AUTO_SCROLL_GAP,
 220
 221       /**
 222        * @brief The default extra space between lines in points.
 223        * @details name "lineSpacing", type FLOAT.
 224        * @SINCE_1_1.37
 225        */
 226       LINE_SPACING,
 227
 228       /**
 229        * @brief The default underline parameters.
 230        * @details name "underline", type STRING.
 231        * @SINCE_1_1.37
 232        */
 233       UNDERLINE,
 234
 235       /**
 236        * @brief The default shadow parameters.
 237        * @details name "shadow", type STRING.
 238        * @SINCE_1_1.37
 239        */
 240       SHADOW,
 241
 242       /**
 243        * @brief The default emboss parameters.
 244        * @details name "emboss", type STRING.
 245        * @SINCE_1_1.37
 246        */
 247       EMBOSS,
 248
 249       /**
 250        * @brief The default outline parameters.
 251        * @details name "outline", type STRING.
 252        * @SINCE_1_1.37
 253        */
 254       OUTLINE,
 255     };
 256   };
 257
 258   /**
 259    * @brief Create the TextLabel control.
 260    *
 261    * @SINCE_1_0.0
 262    * @return A handle to the TextLabel control.
 263    */
 264   static TextLabel New();
 265
 266   /**
 267    * @brief Create the TextLabel control.
 268    *
 269    * @SINCE_1_0.0
 270    * @param[in] text The text to display.
 271    * @return A handle to the TextLabel control.
 272    */
 273   static TextLabel New( const std::string& text );
 274
 275   /**
 276    * @brief Creates an empty handle.
 277    * @SINCE_1_0.0
 278    */
 279   TextLabel();
 280
 281   /**
 282    * @brief Copy constructor.
 283    *
 284    * @SINCE_1_0.0
 285    * @param[in] handle The handle to copy from.
 286    */
 287   TextLabel( const TextLabel& handle );
 288
 289   /**
 290    * @brief Assignment operator.
 291    *
 292    * @SINCE_1_0.0
 293    * @param[in] handle The handle to copy from.
 294    * @return A reference to this.
 295    */
 296   TextLabel& operator=( const TextLabel& handle );
 297
 298   /**
 299    * @brief Destructor
 300    *
 301    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 302    * @SINCE_1_0.0
 303    */
 304   ~TextLabel();
 305
 306   /**
 307    * @brief Downcast a handle to TextLabel.
 308    *
 309    * If the BaseHandle points is a TextLabel the downcast returns a valid handle.
 310    * If not the returned handle is left empty.
 311    *
 312    * @SINCE_1_0.0
 313    * @param[in] handle Handle to an object
 314    * @return handle to a TextLabel or an empty handle
 315    */
 316   static TextLabel DownCast( BaseHandle handle );
 317
 318 public: // Not intended for application developers
 319
 320   /// @cond internal
 321   /**
 322    * @brief Creates a handle using the Toolkit::Internal implementation.
 323    *
 324    * @SINCE_1_0.0
 325    * @param[in] implementation The Control implementation.
 326    */
 327   DALI_INTERNAL TextLabel( Internal::TextLabel& implementation );
 328
 329   /**
 330    * @brief Allows the creation of this Control from an Internal::CustomActor pointer.
 331    *
 332    * @SINCE_1_0.0
 333    * @param[in]  internal  A pointer to the internal CustomActor.
 334    */
 335   explicit DALI_INTERNAL TextLabel( Dali::Internal::CustomActor* internal );
 336   /// @endcond
 337 };
 338
 339 /**
 340  * @}
 341  */
 342 } // namespace Toolkit
 343
 344 } // namespace Dali
 345
 346 #endif // __DALI_TOOLKIT_TEXT_LABEL_H__