docs/content/programming-guide/text-input.h

   1 /*! \page text-input Text Input
   2  *
   3  TextInput is a Dali::Actor which allows the input of text from an on-screen virtual keyboard or attached hardware keyboard.
   4
   5
   6 <h2 class="pg">Basic Text Input Set-up</h2>
   7
   8  The below code creates a new TextInput
   9
  10    @code
  11    Dali::Toolkit::TextInput myTextInput;
  12    myTextInput = Dali::Toolkit::TextInput::New();
  13    @endcode
  14
  15  The following code sets the size and adds it to the stage
  16    @code
  17    myTextInput.SetParentOrigin(ParentOrigin::CENTER);
  18    myTextInput.SetSize(stageWidth*0.25f, stageWidth*0.5f);
  19    Stage::GetCurrent().Add(myTextInput);
  20    @endcode
  21
  22  For a TextInput to receive input from the keyboard it must be in edit mode.
  23
  24  To enter edit mode the below call can be made.  If the virtual on-screen keyboard is supported then it will be displayed.
  25  Internally TextInput will set focus to this TextInput and key events will be sent to it.
  26
  27    @code myTextInput.SetEditable(true);@endcode
  28
  29  After this call the TextInput will receive any key press. If you have more than one TextInput the focus will change between them when the edit mode is
  30  initiated on any Text Input.
  31
  32  To automatically start edit mode when the TextInput is "tapped" you can call the following:
  33
  34    @code myTextInput.SetEditOnTouch()@endcode
  35
  36  You will then need to end edit mode by making the call below or swiping away the keyboard (Virtual On-screen Keyboard)
  37    @code myTextInput.SetEditable(false);@endcode
  38
  39  The call will hide the virtual keyboard if previously shown by Text Input.
  40
  41  Then the input string as plain text can be retrieved using
  42    @code Dali::Toolkit::TextInput::GetText()@endcode
  43
  44 <h2 class="pg"> Text Selection </h2>
  45
  46  The SetTextSelectable API when set to true enables text to be highlighted, once highlighted the text style can be changed,
  47  the text can be cut, or copied, overwritten with new text or deleted.
  48
  49  The user does a Long-Press on the text to get the option of text selection.
  50
  51    @code Dali::Toolkit::TextInput::SetTextSelectable( true ) @endcode
  52
  53 <h2 class="pg"> Text Styling </h2>
  54
  55  In conjunction with TextView and the Markup processor, TextInput enables text to be styled.
  56
  57  There are 3 ways to effect the text styling.
  58
  59    SetActiveStyle, new input text is set to the Red glow style
  60    @code
  61    TextStyle style;
  62    style.SetGlow ( true, Dali::Color::RED );
  63    myTextInput.SetActiveStyle( style, MarkupProcessor::GLOW );
  64    @endcode
  65
  66    ApplyStyle, selected/highlighted text now has the Red glow style
  67    @code
  68    TextStyle style;
  69    style.SetGlow ( true, Dali::Color::RED );
  70    myTextInput.ApplyStyle( style, MarkupProcessor::GLOW );
  71    @endcode
  72
  73    ApplyStyleToAll, all text now has the Red glow style
  74    @code
  75    TextStyle style;
  76    style.SetGlow ( true, Dali::Color::RED );
  77    myTextInput.ApplyStyleToAll( style, MarkupProcessor::GLOW );
  78    @endcode
  79
  80  Then the input string with Mark-up defining the style can be retrieved using
  81    @code Dali::Toolkit::TextInput::GetMarkupText()@endcode
  82  This would be usefull if you wish to save the styled text the user has input so it can be re-displayed another time.
  83
  84  Signals are emitted when style changes.
  85
  86  See Dali::Toolkit::TextInput::StyleMask for available styling options.
  87
  88
  89
  90
  91  */
  92