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

   1 <!--
   2 /**-->
   3
   4 # Text Editor {#text-editor}
   5
   6 ## Overview
   7
   8 The Dali::Toolkit::TextEditor is a control which provides a multi-line editable text.
   9
  10 ### Basic usage
  11
  12 Add the text-editor to the stage.
  13
  14 ~~~{.cpp}
  15 // C++
  16
  17 TextEditor editor = TextEditor::New();
  18
  19 Stage::GetCurrent().Add( editor );
  20 ~~~
  21
  22 ~~~{.js}
  23 // JavaScript
  24
  25 var editor = new dali.TextEditor();
  26
  27 dali.stage.add( editor );
  28 ~~~
  29
  30 When the TextEditor is tapped, it will automatically gain the keyboard focus. Key events will then result in text being inserted.
  31 After text has been entered, it can be retrieved from the TEXT property.
  32
  33 ~~~{.cpp}
  34 // C++
  35
  36 Property::Value editorText = editor.GetProperty( TextEditor::Property::TEXT );
  37 std::cout << "Received text: " << editorText.Get< std::string >() << std::endl;
  38 ~~~
  39
  40 ~~~{.js}
  41 // JavaScript
  42
  43 console.log( editor.text );
  44 ~~~
  45
  46 ### Font Selection
  47
  48 By default TextEditor 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.
  49
  50 ### Mark-up Style
  51
  52 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.
  53
  54 ### Input Style
  55
  56 The input style can be changed through the control properties.See the [Input Style](@ref input-style) section for more details.
  57
  58 ### Text Alignment
  59
  60 TextEditor displays a multi-line of text, which will scroll if there is not enough room for the text displayed.
  61 If there is enough room, then the text can be aligned horizontally to the beginning, end, or center of the available area:
  62
  63 ~~~{.cpp}
  64 // C++
  65
  66 editor.SetProperty( TextEditor::Property::HORIZONTAL_ALIGNMENT, "BEGIN" ); // "CENTER" or "END"
  67 ~~~
  68
  69 ~~~{.js}
  70 // JavaScript
  71
  72 editor.HorizontalAlignment = "BEGIN"; // "CENTER" or "END"
  73 ~~~
  74
  75 ### Copy and Paste  (Selection)
  76
  77 Text can be selected by a long press or double tapping it. See the [Copy and Paste](@ref copy-n-paste) section for more details.
  78
  79 ### TextEditor Decorations
  80
  81 #### Color
  82
  83 To change the color of the text, the recommended way is to use the TEXT_COLOR property.
  84
  85 ~~~{.cpp}
  86 // C++
  87 editor.SetProperty( TextEditor::Property::TEXT_COLOR, Color::CYAN );
  88 ~~~
  89
  90 ~~~{.js}
  91 // JavaScript
  92
  93 editor.textColor = dali.COLOR_CYAN;
  94 ~~~
  95
  96 ### TextEditor Properties
  97
  98  Name (JavaScript)                 |  Name (C++)                          |  Type        | Writable     | Animatable
  99 -----------------------------------|--------------------------------------|--------------|--------------|-----------
 100  renderingBackend                  | RENDERING_BACKEND                    |  INTEGER     | O            | X
 101  text                              | TEXT                                 |  STRING      | O            | X
 102  textColor                         | TEXT_COLOR                           |  VECTOR4     | O            | X
 103  fontFamily                        | FONT_FAMILY                          |  STRING      | O            | X
 104  fontStyle                         | FONT_STYLE                           |  STRING      | O            | X
 105  pointSize                         | POINT_SIZE                           |  FLOAT       | O            | X
 106  horizontalAlignment               | HORIZONTAL_ALIGNMENT                 |  STRING      | O            | X
 107  verticalAlignment                 | VERTICAL_ALIGNMENT                   |  STRING      | O            | X
 108  scrollThreshold                   | SCROLL_THRESHOLD                     |  FLOAT       | O            | X
 109  scrollSpeed                       | SCROLL_SPEED                         |  FLOAT       | O            | X
 110  primaryCursorColor                | PRIMARY_CURSOR_COLOR                 |  VECTOR4     | O            | X
 111  secondaryCursorColor              | SECONDARY_CURSOR_COLOR               |  VECTOR4     | O            | X
 112  enableCursorBlink                 | ENABLE_CURSOR_BLINK                  |  BOOLEAN     | O            | X
 113  cursorBlinkInterval               | CURSOR_BLINK_INTERVAL                |  FLOAT       | O            | X
 114  cursorBlinkDuration               | CURSOR_BLINK_DURATION                |  FLOAT       | O            | X
 115  cursorWidth                       | CURSOR_WIDTH                         |  INTEGER     | O            | X
 116  grabHandleImage                   | GRAB_HANDLE_IMAGE                    |  STRING      | O            | X
 117  grabHandlePressedImage            | GRAB_HANDLE_PRESSED_IMAGE            |  STRING      | O            | X
 118  selectionHandleImageLeft          | SELECTION_HANDLE_IMAGE_LEFT          |  STRING      | O            | X
 119  selectionHandleImageRight         | SELECTION_HANDLE_IMAGE_RIGHT         |  STRING      | O            | X
 120  selectionHandlePressedImageLeft   | SELECTION_HANDLE_PRESSED_IMAGE_LEFT  |  STRING      | O            | X
 121  selectionHandlePressedImageRight  | SELECTION_HANDLE_PRESSED_IMAGE_RIGHT |  STRING      | O            | X
 122  selectionHandleMarkerImageLeft    | SELECTION_HANDLE_MARKER_IMAGE_LEFT   |  MAP         | O            | X
 123  selectionHandleMarkerImageRight   | SELECTION_HANDLE_MARKER_IMAGE_RIGHT  |  MAP         | O            | X
 124  selectionHighlightColor           | SELECTION_HIGHLIGHT_COLOR            |  VECTOR4     | O            | X
 125  decorationBoundingBox             | DECORATION_BOUNDING_BOX              |  RECTANGLE   | O            | X
 126  enableMarkup                      | ENABLE_MARKUP                        |  BOOLEAN     | O            | X
 127  inputColor                        | INPUT_COLOR                          |  VECTOR4     | O            | X
 128  inputFontFamily                   | INPUT_FONT_FAMILY                    |  STRING      | O            | X
 129  inputFontStyle                    | INPUT_FONT_STYLE                     |  STRING      | O            | X
 130  inputPointSize                    | INPUT_POINT_SIZE                     |  FLOAT       | O            | X
 131
 132 @class TextEditor
 133
 134 */