(TextField) Moved INPUT_COLOR to the end of the enums to ensure binary compatibility...
[platform/core/uifw/dali-toolkit.git] / dali-toolkit / public-api / controls / text-controls / text-field.h
index 1ce8b7a..9b6453d 100644 (file)
@@ -20,7 +20,6 @@
 
 // INTERNAL INCLUDES
 #include <dali-toolkit/public-api/controls/control.h>
-#include <dali-toolkit/public-api/text/rendering/text-renderer.h>
 
 namespace Dali
 {
@@ -32,33 +31,95 @@ namespace Internal DALI_INTERNAL
 {
 class TextField;
 }
+/**
+ * @addtogroup dali_toolkit_controls_text_controls
+ * @{
+ */
 
 /**
  * @brief A control which provides a single-line editable text field.
+ *
+ *  * Signals
+ * | %Signal Name         | Method                                              |
+ * |----------------------|-----------------------------------------------------|
+ * | textChanged          | @ref TextChangedSignal()                            |
+ * | maxLengthReached     | @ref MaxLengthReachedSignal()                       |
+ *
  */
 class DALI_IMPORT_API TextField : public Control
 {
 public:
 
-  // Property indices
-  static const Property::Index PROPERTY_PLACEHOLDER_TEXT;       ///< name "placeholder-text",       type STRING
-  static const Property::Index PROPERTY_TEXT;                   ///< name "text",                   type STRING
-  static const Property::Index PROPERTY_CURSOR_IMAGE;           ///< name "cursor-image",           type STRING
-  static const Property::Index PROPERTY_PRIMARY_CURSOR_COLOR;   ///< name "primary-cursor-color",   type VECTOR4
-  static const Property::Index PROPERTY_SECONDARY_CURSOR_COLOR; ///< name "secondary-cursor-color", type VECTOR4
-  static const Property::Index PROPERTY_ENABLE_CURSOR_BLINK;    ///< name "enable-cursor-blink",    type BOOLEAN
-  static const Property::Index PROPERTY_CURSOR_BLINK_INTERVAL;  ///< name "cursor-blink-interval",  type FLOAT
-  static const Property::Index PROPERTY_CURSOR_BLINK_DURATION;  ///< name "cursor-blink-duration",  type FLOAT
-
-  // Property names
-  static const std::string PLACEHOLDER_TEXT_PROPERTY_NAME;       ///< Property, name "placeholder-text",       type STRING
-  static const std::string TEXT_PROPERTY_NAME;                   ///< Property, name "text",                   type STRING
-  static const std::string CURSOR_IMAGE_PROPERTY_NAME;           ///< Property, name "cursor-image",           type STRING
-  static const std::string PRIMARY_CURSOR_COLOR_PROPERTY_NAME;   ///< Property, name "primary-cursor-color",   type VECTOR4
-  static const std::string SECONDARY_CURSOR_COLOR_PROPERTY_NAME; ///< Property, name "secondary-cursor-color", type VECTOR4
-  static const std::string ENABLE_CURSOR_BLINK_PROPERTY_NAME;    ///< Property, name "enable-cursor-blink",    type BOOLEAN
-  static const std::string CURSOR_BLINK_INTERVAL_PROPERTY_NAME;  ///< Property, name "cursor-blink-interval",  type FLOAT
-  static const std::string CURSOR_BLINK_DURATION_PROPERTY_NAME;  ///< Property, name "cursor-blink-duration",  type FLOAT
+  /**
+   * @brief The start and end property ranges for this control.
+   */
+  enum PropertyRange
+  {
+    PROPERTY_START_INDEX = Control::CONTROL_PROPERTY_END_INDEX + 1,
+    PROPERTY_END_INDEX =   PROPERTY_START_INDEX + 1000              ///< Reserve property indices
+  };
+
+  /**
+   * @brief An enumeration of properties belonging to the TextLabel class.
+   */
+  struct Property
+  {
+    enum
+    {
+      RENDERING_BACKEND = PROPERTY_START_INDEX, ///< name "renderingBackend",                    The type or rendering e.g. bitmap-based,                                  type INT
+      TEXT,                                     ///< name "text",                                The text to display in UTF-8 format,                                      type STRING
+      PLACEHOLDER_TEXT,                         ///< name "placeholderText",                     The text to display when the TextField is empty and inactive,             type STRING
+      PLACEHOLDER_TEXT_FOCUSED,                 ///< name "placeholderTextFocused",              The text to display when the TextField is empty with key-input focus,     type STRING
+      FONT_FAMILY,                              ///< name "fontFamily",                          The requested font family,                                                type STRING
+      FONT_STYLE,                               ///< name "fontStyle",                           The requested font style,                                                 type STRING
+      POINT_SIZE,                               ///< name "pointSize",                           The size of font in points,                                               type FLOAT
+      MAX_LENGTH,                               ///< name "maxLength"                            The maximum number of characters that can be inserted,                    type INTEGER
+      EXCEED_POLICY,                            ///< name "exceedPolicy"                         Specifies how the text is truncated when it does not fit,                 type INTEGER
+      HORIZONTAL_ALIGNMENT,                     ///< name "horizontalAlignment",                 The line horizontal alignment,                                            type STRING,  values "BEGIN", "CENTER", "END"
+      VERTICAL_ALIGNMENT,                       ///< name "verticalAlignment",                   The line vertical alignment,                                              type STRING,  values   "TOP",   "CENTER",   "BOTTOM"
+      TEXT_COLOR,                               ///< name "textColor",                           The text color,                                                           type VECTOR4
+      PLACEHOLDER_TEXT_COLOR,                   ///< name "placeholderTextColor",                The placeholder-text color,                                               type VECTOR4
+      SHADOW_OFFSET,                            ///< name "shadowOffset",                        The drop shadow offset 0 indicates no shadow,                             type VECTOR2
+      SHADOW_COLOR,                             ///< name "shadowColor",                         The color of a drop shadow,                                               type VECTOR4
+      PRIMARY_CURSOR_COLOR,                     ///< name "primaryCursorColor",                  The color to apply to the primary cursor,                                 type VECTOR4
+      SECONDARY_CURSOR_COLOR,                   ///< name "secondaryCursorColor",                The color to apply to the secondary cursor,                               type VECTOR4
+      ENABLE_CURSOR_BLINK,                      ///< name "enableCursorBlink",                   Whether the cursor should blink or not,                                   type BOOLEAN
+      CURSOR_BLINK_INTERVAL,                    ///< name "cursorBlinkInterval",                 The time interval in seconds between cursor on/off states,                type FLOAT
+      CURSOR_BLINK_DURATION,                    ///< name "cursorBlinkDuration",                 The cursor will stop blinking after this number of seconds (if non-zero), type FLOAT
+      CURSOR_WIDTH,                             ///< name "cursorWidth",                         The cursor width,                                                         type INTEGER
+      GRAB_HANDLE_IMAGE,                        ///< name "grabHandleImage",                     The image to display for the grab handle,                                 type STRING
+      GRAB_HANDLE_PRESSED_IMAGE,                ///< name "grabHandlePressedImage",              The image to display when the grab handle is pressed,                     type STRING
+      SCROLL_THRESHOLD,                         ///< name "scrollThreshold"                      Scrolling will occur if the cursor is this close to the control border,   type FLOAT
+      SCROLL_SPEED,                             ///< name "scrollSpeed"                          The scroll speed in pixels per second,                                    type FLOAT
+      SELECTION_HANDLE_IMAGE_LEFT,              ///< name "selectionHandleImageLeft",            The image to display for the left selection handle,                       type MAP
+      SELECTION_HANDLE_IMAGE_RIGHT,             ///< name "selectionHandleImageRight",           The image to display for the right selection handle,                      type MAP
+      SELECTION_HANDLE_PRESSED_IMAGE_LEFT,      ///< name "selectionHandlePressedImageLeft",     The image to display when the left selection handle is pressed,           type MAP
+      SELECTION_HANDLE_PRESSED_IMAGE_RIGHT,     ///< name "selectionHandlePressedImageRight",    The image to display when the right selection handle is pressed,          type MAP
+      SELECTION_HANDLE_MARKER_IMAGE_LEFT,       ///< name "selectionHandleMarkerImageLeft",      The image to display for the left selection handle marker,                type MAP
+      SELECTION_HANDLE_MARKER_IMAGE_RIGHT,      ///< name "selectionHandleMarkerImageRight",     The image to display for the right selection handle marker,               type MAP
+      SELECTION_HIGHLIGHT_COLOR,                ///< name "selectionHighlightColor",             The color of the selection highlight,                                     type VECTOR4
+      DECORATION_BOUNDING_BOX,                  ///< name "decorationBoundingBox",               The decorations (handles etc) will positioned within this area on-screen, type RECTANGLE
+      INPUT_METHOD_SETTINGS,                    ///< name "inputMethodSettings",                 The settings to relating to the System's Input Method, Key and Value      type MAP
+      INPUT_COLOR,                              ///< name "inputColor",                          The color of the new input text,                                          type VECTOR4
+    };
+  };
+
+  /**
+   * @brief Specifies how the text is truncated when it does not fit
+   *
+   * The default value is \e EXCEED_POLICY_CLIP.
+   */
+  enum ExceedPolicy
+  {
+    EXCEED_POLICY_ORIGINAL,        ///< The text will be display at original size, and may exceed the TextField boundary.
+    EXCEED_POLICY_CLIP             ///< The end of text will be clipped to fit within the TextField.
+  };
+
+  // Type Defs
+
+  /// @brief Max Characters Exceed signal type;
+  typedef Signal<void ( TextField ) > TextChangedSignalType;
+  typedef Signal<void ( TextField ) > MaxLengthReachedSignalType;
 
   /**
    * Create the TextField control.
@@ -104,12 +165,29 @@ public:
    */
   static TextField DownCast( BaseHandle handle );
 
+  // Signals
+
   /**
-   * @brief Set the rendering back-end used by the TextField.
+   * @brief This signal is emitted when the text changes.
    *
-   * @param[in] renderer The text renderer to use.
+   * A callback of the following type may be connected:
+   * @code
+   *   void YourCallbackName( TextField textField );
+   * @endcode
+   * @return The signal to connect to.
    */
-  void SetRenderer( Text::RendererPtr renderer );
+  TextChangedSignalType& TextChangedSignal();
+
+  /**
+   * @brief This signal is emitted when inserted text exceeds the maximum character limit.
+   *
+   * A callback of the following type may be connected:
+   * @code
+   *   void YourCallbackName( TextField textField );
+   * @endcode
+   * @return The signal to connect to.
+   */
+  MaxLengthReachedSignalType& MaxLengthReachedSignal();
 
 public: // Not intended for application developers
 
@@ -128,6 +206,9 @@ public: // Not intended for application developers
   explicit DALI_INTERNAL TextField( Dali::Internal::CustomActor* internal );
 };
 
+/**
+ * @}
+ */
 } // namespace Toolkit
 
 } // namespace Dali