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 ~~~{.cpp}
  17 // C++
  18
  19 TextField field = TextField::New();
  20 field.SetProperty( TextField::Property::PLACEHOLDER_TEXT, "Unnamed Name" );
  21 field.SetProperty( TextField::Property::PLACEHOLDER_TEXT_FOCUSED, "Enter Name." );
  22
  23 Stage::GetCurrent().Add( field );
  24 ~~~
  25
  26 ~~~{.js}
  27 // JavaScript
  28
  29 var field = new dali.TextField();
  30 field.placeholderText = "Unnamed Name";
  31 field.placeholderTextFocused = "Enter Name.";
  32
  33 dali.stage.add( field );
  34 ~~~
  35
  36 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.
  37 After text has been entered, it can be retrieved from the TEXT property.
  38
  39 ~~~{.cpp}
  40 // C++
  41
  42 Property::Value fieldText = field.GetProperty( TextField::Property::TEXT );
  43 std::cout << "Received text: " << fieldText.Get< std::string >() << std::endl;
  44 ~~~
  45
  46 ~~~{.js}
  47 // JavaScript
  48
  49 console.log( field.text );
  50 ~~~
  51
  52 ### Font Selection
  53
  54 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.
  55
  56 ### Mark-up Style
  57
  58 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.
  59
  60 ### Input Style
  61
  62 The input style can be changed through the control properties. Current supported input style properties are:
  63
  64 #### INPUT_COLOR
  65
  66 Sets the input color. All subsequent characters added will be rendered with the input color.
  67
  68 Note the input color may change if the cursor is updated by tapping in a new position.
  69
  70 ### Text Alignment
  71
  72 TextField displays a single-line of text, which will scroll if there is not enough room for the text displayed.
  73 If there is enough room, then the text can be aligned horizontally to the beginning, end, or center of the available area:
  74
  75 ~~~{.cpp}
  76 // C++
  77
  78 field.SetProperty( TextField::Property::HORIZONTAL_ALIGNMENT, "BEGIN" ); // "CENTER" or "END"
  79 ~~~
  80
  81 ~~~{.js}
  82 // JavaScript
  83
  84 field.HorizontalAlignment = "BEGIN"; // "CENTER" or "END"
  85 ~~~
  86
  87 ### Copy and Paste  (Selection)
  88
  89 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.
  90
  91 [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.
  92
  93 Empty text means the user has not inputted any text, a TextField containing special characters or purely whitespace is not empty.
  94
  95 Below shows how the popup will look depending on the state of the TextField
  96
  97 |  |  |
  98 |--|--|
  99 | Condition: Long press/double tap when empty text but clipboard has content  |  Condition: Long press/double tap when TextField contains text |
 100 |[PASTE][CLIPBOARD] buttons shown| [CUT][COPY], [SELECT ALL] unless all text selected and [PASTE][CLIPBOARD] if content to paste. |
 101 |    ![ ](../assets/img/text-controls/EmptyTextClipboardHasContent.png) ![ ](./EmptyTextClipboardHasContent.png) |   ![ ](../assets/img/text-controls/SelectingText.png) ![ ](./SelectingText.png) |
 102 | Condition: Long press/double tap popup when TextField contains just whitespace | Condition: Empty text & clipboard empty |
 103 | 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|
 104 |  ![ ](../assets/img/text-controls/SelectAllWhitespace.png) ![ ](./SelectAllWhitespace.png) | ![ ](../assets/img/text-controls/EmptyTextAndNoContentToPaste.png) ![ ](./EmptyTextAndNoContentToPaste.png)|
 105 | Condition: Longpress/(double tap) on whitespace which is following text | Condition: Tapping text or panning grab handle |
 106 | [PASTE][CLIPBOARD] shown if something to paste. [SELECT ALL] as more text to select | If content in clipboard [PASTE][CLIPBOARD] popup will be shown. |
 107 | ![ ](../assets/img/text-controls/SelectWhitespaceAfterText.png) ![ ](./SelectWhitespaceAfterText.png) | ![ ](../assets/img/text-controls/TapAfterCopyingText.png) ![ ](./TapAfterCopyingText.png) |
 108
 109 ### TextField Decorations
 110
 111 #### Color
 112
 113 To change the color of the text, the recommended way is to use the TEXT_COLOR property.
 114 An alternative color can be used for placeholder text by setting PLACEHOLDER_TEXT_COLOR.
 115 Note that unlike the Actor::COLOR property, these properties will not affect child Actors added to the TextField.
 116
 117 ~~~{.cpp}
 118 // C++
 119 field.SetProperty( TextField::Property::TEXT_COLOR, Color::CYAN );
 120 field.SetProperty( TextField::Property::PLACEHOLDER_TEXT_COLOR, Color::BLACK );
 121 ~~~
 122
 123 ~~~{.js}
 124 // JavaScript
 125
 126 field.textColor = dali.COLOR_CYAN;
 127 field.placeholderTextColor = dali.COLOR_BLACK;
 128 ~~~
 129
 130 ### Text Field Properties
 131
 132  Name (JavaScript)                 |  Name (C++)                          |  Type        | Writable     | Animatable
 133 -----------------------------------|--------------------------------------|--------------|--------------|-----------
 134  renderingBackend                  | RENDERING_BACKEND                    |  INTEGER     | O            | X
 135  text                              | TEXT                                 |  STRING      | O            | X
 136  placeholderText                   | PLACEHOLDER_TEXT                     |  STRING      | O            | X
 137  placeholderTextFocused            | PLACEHOLDER_TEXT_FOCUSED             |  STRING      | O            | X
 138  fontFamily                        | FONT_FAMILY                          |  STRING      | O            | X
 139  fontStyle                         | FONT_STYLE                           |  STRING      | O            | X
 140  pointSize                         | POINT_SIZE                           |  FLOAT       | O            | X
 141  maxLength                         | MAX_LENGTH                           |  INTEGER     | O            | X
 142  exceedPolicy                      | EXCEED_POLICY                        |  INTEGER     | O            | X
 143  horizontalAlignment               | HORIZONTAL_ALIGNMENT                 |  STRING      | O            | X
 144  verticalAlignment                 | VERTICAL_ALIGNMENT                   |  STRING      | O            | X
 145  textColor                         | TEXT_COLOR                           |  VECTOR4     | O            | X
 146  placeholderTextColor              | PLACEHOLDER_TEXT_COLOR               |  VECTOR4     | O            | X
 147  shadowOffset                      | SHADOW_OFFSET                        |  VECTOR2     | O            | X
 148  shadowColor                       | SHADOW_COLOR                         |  VECTOR4     | O            | X
 149  primaryCursorColor                | PRIMARY_CURSOR_COLOR                 |  VECTOR4     | O            | X
 150  secondaryCursorColor              | SECONDARY_CURSOR_COLOR               |  VECTOR4     | O            | X
 151  enableCursorBlink                 | ENABLE_CURSOR_BLINK                  |  BOOLEAN     | O            | X
 152  cursorBlinkInterval               | CURSOR_BLINK_INTERVAL                |  FLOAT       | O            | X
 153  cursorBlinkDuration               | CURSOR_BLINK_DURATION                |  FLOAT       | O            | X
 154  cursorWidth                       | CURSOR_WIDTH                         |  INTEGER     | O            | X
 155  grabHandleImage                   | GRAB_HANDLE_IMAGE                    |  STRING      | O            | X
 156  grabHandlePressedImage            | GRAB_HANDLE_PRESSED_IMAGE            |  STRING      | O            | X
 157  scrollThreshold                   | SCROLL_THRESHOLD                     |  FLOAT       | O            | X
 158  scrollSpeed                       | SCROLL_SPEED                         |  FLOAT       | O            | X
 159  selectionHandleImageLeft          | SELECTION_HANDLE_IMAGE_LEFT          |  STRING      | O            | X
 160  selectionHandleImageRight         | SELECTION_HANDLE_IMAGE_RIGHT         |  STRING      | O            | X
 161  selectionHandlePressedImageLeft   | SELECTION_HANDLE_PRESSED_IMAGE_LEFT  |  STRING      | O            | X
 162  selectionHandlePressedImageRight  | SELECTION_HANDLE_PRESSED_IMAGE_RIGHT |  STRING      | O            | X
 163  selectionHandleMarkerImageLeft    | SELECTION_HANDLE_MARKER_IMAGE_LEFT   |  MAP         | O            | X
 164  selectionHandleMarkerImageRight   | SELECTION_HANDLE_MARKER_IMAGE_RIGHT  |  MAP         | O            | X
 165  selectionHighlightColor           | SELECTION_HIGHLIGHT_COLOR            |  VECTOR4     | O            | X
 166  decorationBoundingBox             | DECORATION_BOUNDING_BOX              |  RECTANGLE   | O            | X
 167  inputMethodSettings               | INPUT_METHOD_SETTINGS                |  MAP         | O            | X
 168  inputColor                        | INPUT_COLOR                          |  VECTOR4     | O            | X
 169  enableMarkup                      | ENABLE_MARKUP                        |  BOOLEAN     | O            | X
 170
 171 @class TextField
 172
 173 */