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