docs/content/shared-javascript-and-cpp-documentation/text-field.md

   1 <!--
   2 /**-->
   3
   4 # Text Field {#text-field}
   5
   6 ## Overview
   7
   8 The Dali::Toolkit::TextField is a control which provides a single-line editable text field.
   9
  10 ### Basic usage
  11
  12 Before any text has been entered, the TextField can display some placeholder text.
  13 An alternative placeholder can be displayed when the TextField has keyboard focus.
  14 For example a TextField used to enter a username could initially show "Unknown Name", and then show "Enter Name." when the cursor is shown.
  15
  16 Note *CR+LF* new line characters are replaced by a *LF* one.
  17
  18 ~~~{.cpp}
  19 // C++
  20
  21 TextField field = TextField::New();
  22 field.SetProperty( TextField::Property::PLACEHOLDER_TEXT, "Unnamed Name" );
  23 field.SetProperty( TextField::Property::PLACEHOLDER_TEXT_FOCUSED, "Enter Name." );
  24
  25 Stage::GetCurrent().Add( field );
  26 ~~~
  27
  28 ~~~{.js}
  29 // JavaScript
  30
  31 var field = new dali.TextField();
  32 field.placeholderText = "Unnamed Name";
  33 field.placeholderTextFocused = "Enter Name.";
  34
  35 dali.stage.add( field );
  36 ~~~
  37
  38 When the TextField is tapped, it will automatically gain the keyboard focus. Key events will then result in text being inserted, and the placeholder text will be removed.
  39 After text has been entered, it can be retrieved from the TEXT property.
  40
  41 ~~~{.cpp}
  42 // C++
  43
  44 Property::Value fieldText = field.GetProperty( TextField::Property::TEXT );
  45 std::cout << "Received text: " << fieldText.Get< std::string >() << std::endl;
  46 ~~~
  47
  48 ~~~{.js}
  49 // JavaScript
  50
  51 console.log( field.text );
  52 ~~~
  53
  54 ### Font Selection
  55
  56 By default TextField will automatically select a suitable font from the platform. However, a different font could be selected. See the [Font Selection](@ref font-selection) section for more details.
  57
  58 ### Mark-up Style
  59
  60 Mark-up tags can be used to change the style of the text. See the [Mark-up Style](@ref markup-style) section for more details.
  61
  62 ### Input Style
  63
  64 The input style can be changed through the control properties. All subsequent characters added will be rendered with the new input style.
  65
  66 Note the input style may change if the cursor is updated by tapping in a new position.
  67
  68 Current supported input style properties are:
  69
  70 - *INPUT_COLOR* Sets the input color. The property expects a Vector4 with the red, green, blue and alpha values clamped between 0 and 1.
  71 - *INPUT_FONT_FAMILY* Sets the input font's family name. The property expects the name of the font. If the new text is not supported by the given font a suitable one will be set.
  72 - *INPUT_FONT_STYLE* Sets the input font's style. The property expects a json formatted string with the font's style. See the [Font Selection](@ref font-selection) section for more details.
  73 - *INPUT_POINT_SIZE* Sets the input font's size. The property expects a float with the font's size in points. See the [Font Selection](@ref font-selection) section for more details.
  74
  75 ### Text Alignment
  76
  77 TextField displays a single-line of text, which will scroll if there is not enough room for the text displayed.
  78 If there is enough room, then the text can be aligned horizontally to the beginning, end, or center of the available area:
  79
  80 ~~~{.cpp}
  81 // C++
  82
  83 field.SetProperty( TextField::Property::HORIZONTAL_ALIGNMENT, "BEGIN" ); // "CENTER" or "END"
  84 ~~~
  85
  86 ~~~{.js}
  87 // JavaScript
  88
  89 field.HorizontalAlignment = "BEGIN"; // "CENTER" or "END"
  90 ~~~
  91
  92 ### Copy and Paste  (Selection)
  93
  94 Text can be selected by a long press or double tapping it.   Depending on certain conditions a popup could be shown giving options including [CUT][COPY][PASTE], [SELECT ALL] or [CLIPBOARD]. Below these conditions will be explained.
  95
  96 [CUT] or [COPY] send the selected text to the clipboard ready to be pasted directly or via the clipboard UI.   Pressing [PASTE] will paste the top item from the clipboard (what has just been copied, possibly from another application).  If the system supports a clipboard UI this can be displayed by pressing the [CLIPBOARD] button.
  97
  98 Empty text means the user has not inputted any text, a TextField containing special characters or purely whitespace is not empty.
  99
 100 Below shows how the popup will look depending on the state of the TextField
 101
 102 |  |  |
 103 |--|--|
 104 | Condition: Long press/double tap when empty text but clipboard has content  |  Condition: Long press/double tap when TextField contains text |
 105 |[PASTE][CLIPBOARD] buttons shown| [CUT][COPY], [SELECT ALL] unless all text selected and [PASTE][CLIPBOARD] if content to paste. |
 106 |    ![ ](../assets/img/text-controls/EmptyTextClipboardHasContent.png) ![ ](./EmptyTextClipboardHasContent.png) |   ![ ](../assets/img/text-controls/SelectingText.png) ![ ](./SelectingText.png) |
 107 | Condition: Long press/double tap popup when TextField contains just whitespace | Condition: Empty text & clipboard empty |
 108 | Whitespace treated as regular text, [CUT][COPY] shown and [PASTE][CLIPBOARD] if content to paste. As all text is selected there is no need for [SELECT ALL] |  No popup shown after longpress/double tap|
 109 |  ![ ](../assets/img/text-controls/SelectAllWhitespace.png) ![ ](./SelectAllWhitespace.png) | ![ ](../assets/img/text-controls/EmptyTextAndNoContentToPaste.png) ![ ](./EmptyTextAndNoContentToPaste.png)|
 110 | Condition: Longpress/(double tap) on whitespace which is following text | Condition: Tapping text or panning grab handle |
 111 | [PASTE][CLIPBOARD] shown if something to paste. [SELECT ALL] as more text to select | If content in clipboard [PASTE][CLIPBOARD] popup will be shown. |
 112 | ![ ](../assets/img/text-controls/SelectWhitespaceAfterText.png) ![ ](./SelectWhitespaceAfterText.png) | ![ ](../assets/img/text-controls/TapAfterCopyingText.png) ![ ](./TapAfterCopyingText.png) |
 113
 114 ### TextField Decorations
 115
 116 #### Color
 117
 118 To change the color of the text, the recommended way is to use the TEXT_COLOR property.
 119 An alternative color can be used for placeholder text by setting PLACEHOLDER_TEXT_COLOR.
 120 Note that unlike the Actor::COLOR property, these properties will not affect child Actors added to the TextField.
 121
 122 ~~~{.cpp}
 123 // C++
 124 field.SetProperty( TextField::Property::TEXT_COLOR, Color::CYAN );
 125 field.SetProperty( TextField::Property::PLACEHOLDER_TEXT_COLOR, Color::BLACK );
 126 ~~~
 127
 128 ~~~{.js}
 129 // JavaScript
 130
 131 field.textColor = dali.COLOR_CYAN;
 132 field.placeholderTextColor = dali.COLOR_BLACK;
 133 ~~~
 134
 135 ### Text Field Properties
 136
 137  Name (JavaScript)                 |  Name (C++)                          |  Type        | Writable     | Animatable
 138 -----------------------------------|--------------------------------------|--------------|--------------|-----------
 139  renderingBackend                  | RENDERING_BACKEND                    |  INTEGER     | O            | X
 140  text                              | TEXT                                 |  STRING      | O            | X
 141  placeholderText                   | PLACEHOLDER_TEXT                     |  STRING      | O            | X
 142  placeholderTextFocused            | PLACEHOLDER_TEXT_FOCUSED             |  STRING      | O            | X
 143  fontFamily                        | FONT_FAMILY                          |  STRING      | O            | X
 144  fontStyle                         | FONT_STYLE                           |  STRING      | O            | X
 145  pointSize                         | POINT_SIZE                           |  FLOAT       | O            | X
 146  maxLength                         | MAX_LENGTH                           |  INTEGER     | O            | X
 147  exceedPolicy                      | EXCEED_POLICY                        |  INTEGER     | O            | X
 148  horizontalAlignment               | HORIZONTAL_ALIGNMENT                 |  STRING      | O            | X
 149  verticalAlignment                 | VERTICAL_ALIGNMENT                   |  STRING      | O            | X
 150  textColor                         | TEXT_COLOR                           |  VECTOR4     | O            | X
 151  placeholderTextColor              | PLACEHOLDER_TEXT_COLOR               |  VECTOR4     | O            | X
 152  shadowOffset                      | SHADOW_OFFSET                        |  VECTOR2     | O            | X
 153  shadowColor                       | SHADOW_COLOR                         |  VECTOR4     | O            | X
 154  primaryCursorColor                | PRIMARY_CURSOR_COLOR                 |  VECTOR4     | O            | X
 155  secondaryCursorColor              | SECONDARY_CURSOR_COLOR               |  VECTOR4     | O            | X
 156  enableCursorBlink                 | ENABLE_CURSOR_BLINK                  |  BOOLEAN     | O            | X
 157  cursorBlinkInterval               | CURSOR_BLINK_INTERVAL                |  FLOAT       | O            | X
 158  cursorBlinkDuration               | CURSOR_BLINK_DURATION                |  FLOAT       | O            | X
 159  cursorWidth                       | CURSOR_WIDTH                         |  INTEGER     | O            | X
 160  grabHandleImage                   | GRAB_HANDLE_IMAGE                    |  STRING      | O            | X
 161  grabHandlePressedImage            | GRAB_HANDLE_PRESSED_IMAGE            |  STRING      | O            | X
 162  scrollThreshold                   | SCROLL_THRESHOLD                     |  FLOAT       | O            | X
 163  scrollSpeed                       | SCROLL_SPEED                         |  FLOAT       | O            | X
 164  selectionHandleImageLeft          | SELECTION_HANDLE_IMAGE_LEFT          |  STRING      | O            | X
 165  selectionHandleImageRight         | SELECTION_HANDLE_IMAGE_RIGHT         |  STRING      | O            | X
 166  selectionHandlePressedImageLeft   | SELECTION_HANDLE_PRESSED_IMAGE_LEFT  |  STRING      | O            | X
 167  selectionHandlePressedImageRight  | SELECTION_HANDLE_PRESSED_IMAGE_RIGHT |  STRING      | O            | X
 168  selectionHandleMarkerImageLeft    | SELECTION_HANDLE_MARKER_IMAGE_LEFT   |  MAP         | O            | X
 169  selectionHandleMarkerImageRight   | SELECTION_HANDLE_MARKER_IMAGE_RIGHT  |  MAP         | O            | X
 170  selectionHighlightColor           | SELECTION_HIGHLIGHT_COLOR            |  VECTOR4     | O            | X
 171  decorationBoundingBox             | DECORATION_BOUNDING_BOX              |  RECTANGLE   | O            | X
 172  inputMethodSettings               | INPUT_METHOD_SETTINGS                |  MAP         | O            | X
 173  inputColor                        | INPUT_COLOR                          |  VECTOR4     | O            | X
 174  enableMarkup                      | ENABLE_MARKUP                        |  BOOLEAN     | O            | X
 175  inputFontFamily                   | INPUT_FONT_FAMILY                    |  STRING      | O            | X
 176  inputFontStyle                    | INPUT_FONT_STYLE                     |  STRING      | O            | X
 177  inputPointSize                    | INPUT_POINT_SIZE                     |  FLOAT       | O            | X
 178
 179 @class TextField
 180
 181 */