capi/dali-toolkit/public-api/controls/text-input/text-input.h

   1 #ifndef __DALI_TOOLKIT_TEXT_INPUT_H__
   2 #define __DALI_TOOLKIT_TEXT_INPUT_H__
   3
   4 //
   5 // Copyright (c) 2014 Samsung Electronics Co., Ltd.
   6 //
   7 // Licensed under the Flora License, Version 1.0 (the License);
   8 // you may not use this file except in compliance with the License.
   9 // You may obtain a copy of the License at
  10 //
  11 //     http://floralicense.org/license/
  12 //
  13 // Unless required by applicable law or agreed to in writing, software
  14 // distributed under the License is distributed on an AS IS BASIS,
  15 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16 // See the License for the specific language governing permissions and
  17 // limitations under the License.
  18 //
  19
  20 /**
  21  * @addtogroup CAPI_DALI_FRAMEWORK
  22  * @{
  23  */
  24
  25 // INTERNAL INCLUDES
  26 #include <dali-toolkit/public-api/controls/text-view/text-view.h>
  27
  28 namespace Dali DALI_IMPORT_API
  29 {
  30
  31 namespace Toolkit
  32 {
  33
  34 namespace Internal DALI_INTERNAL
  35 {
  36 class TextInput;
  37 }
  38
  39 /**
  40  * TextInput Actor takes input one character at a time and displays it as a string within an input box.
  41  * Characters can be removed from the end of the string until it is empty. A maximum length of displayed string
  42  * can be set.
  43  */
  44 class TextInput : public Control
  45 {
  46
  47 public:
  48
  49   //Signal Names
  50   static const char* const SIGNAL_START_INPUT;
  51   static const char* const SIGNAL_END_INPUT;
  52   static const char* const SIGNAL_STYLE_CHANGED;
  53   static const char* const SIGNAL_MAX_INPUT_CHARACTERS_REACHED;
  54   static const char* const SIGNAL_TOOLBAR_DISPLAYED;
  55   static const char* const SIGNAL_TEXT_EXCEED_BOUNDARIES;
  56
  57 public:
  58
  59   /**
  60    * Create an uninitialized TextInput; this can be initialized with TextView::New()
  61    * Calling member functions with an uninitialized Dali::Object is not allowed.
  62    */
  63   TextInput();
  64
  65   /**
  66    * Copy constructor.
  67    * @param handle to be copied
  68    */
  69   TextInput( const TextInput& handle );
  70
  71   /**
  72    * Assignment operator.
  73    * @param handle to object we want to point to
  74    * @return handle to the TextInput
  75    */
  76   TextInput& operator=( const TextInput& handle );
  77
  78   /**
  79    * Create an initialised TextInput.
  80    * @return A handle to a newly allocated Dali resource.
  81    */
  82   static TextInput New();
  83
  84   /**
  85    * Downcast an Object handle to TextInput. If handle points to a TextInput the
  86    * downcast produces valid handle. If not the returned handle is left uninitialized.
  87    * @param[in] handle Handle to an object
  88    * @return handle to a TextInput or an uninitialized handle
  89    */
  90   static TextInput DownCast( BaseHandle handle );
  91
  92   /**
  93    * Virtual destructor.
  94    * Dali::Object derived classes typically do not contain member data.
  95    */
  96   virtual ~TextInput();
  97
  98   /**
  99    * Get the inputed text currently being displayed.
 100    * @return string, the currently displayed string.
 101    */
 102   std::string GetText() const;
 103
 104   /**
 105    * Get the inputed text currently being displayed together with mark-up tags.
 106    * @return string, the currently displayed string with mark-up.
 107    */
 108   std::string GetMarkupText() const;
 109
 110   /**
 111    * Set the maximum number of characters for the Text Input
 112    * @param [in] maxChars the max number of characters
 113    */
 114   void SetMaxCharacterLength(std::size_t maxChars);
 115
 116   /**
 117    * Limits the number of lines of text Text Input will display
 118    * @param [in] maxLines the max number of lines to display, must be greater than 0.
 119    * Currently the only valid limit is 1. Which turns TextInput into Single line mode. Any number higher than 1 results in no limit.
 120    */
 121   void SetNumberOfLinesLimit(std::size_t maxLines);
 122
 123   /**
 124    * Returns the limit of lines Text Input is allowed to display.
 125    * @return max line number limit
 126    */
 127   std::size_t GetNumberOfLinesLimit() const;
 128
 129   /**
 130    * Returns the number of characters TextInput is displaying.
 131    * @return number of characters
 132    */
 133   std::size_t GetNumberOfCharacters() const;
 134
 135   /**
 136    *  Sets a place holder text to be displayed when the text-input is empty.
 137    *  If not set or set to an empty string then no place holder will be shown.
 138    *  @param [in] placeHolderText text to be used as place holder.
 139    */
 140   void SetPlaceholderText( const std::string& placeHolderText );
 141
 142   /**
 143    * @return the current set place holder text, empty string returned if not set.
 144    */
 145   std::string GetPlaceholderText();
 146
 147   /**
 148    *  set initial text to be displayed in text-input
 149    *  can be used to edit a pre-existing string
 150    *  @param [in] initialText text to be initially displayed
 151    */
 152   void SetInitialText(const std::string& initialText);
 153
 154   /**
 155    *  Manual method to set the focus on the TextInput so it starts or stops edit state
 156    *  @pre The text input actor has been initialised.
 157    *  @param[in] editMode true or false to indicate editMode on or off
 158    */
 159    void SetEditable(bool editMode);
 160
 161    /**
 162     * @see SetEditable(bool editMode).
 163     *
 164     * It sets the cursor in the closest character to the given touch point.
 165     *
 166    *  @param[in] editMode true or false to indicate editMode on or off
 167     * @param[in] touchPoint A position in actor coordinates within the text-input.
 168     */
 169    void SetEditable(bool editMode, const Vector2& touchPoint);
 170
 171    /**
 172     *  Check if TextInput is in edit state
 173     *  @pre The text input actor has been initialised.
 174     *  @return  True or False to indicate editMode on or off
 175     */
 176    bool IsEditable() const;
 177
 178    /**
 179     * Method to enable or disable edit on touch/tap.
 180     * If not enabled (set to false) then SetEditable(true) will be used to start edit mode.
 181     * @pre The text input actor has been initialised.
 182     * @param[in] editOnTouch true or false to indicate if editing should start on touch
 183     *            default is for editing to start on touching textinput
 184     */
 185    void SetEditOnTouch(bool editOnTouch = true);
 186
 187    /**
 188     *  Check if TextInput starts edit mode on touch
 189     *  @pre The text input actor has been initialised.
 190     *  @return  True or False to indicate editOnTouch on or off
 191     */
 192    bool IsEditOnTouch() const;
 193
 194    /**
 195     *  Check if Text Selection is enabled so required text can be highlighted
 196     *  @pre The text input actor has been initialised.
 197     *  @param[in] textSelectable true or false to indicate if text can be selected or not
 198     *             default is for text to be select-able when in edit mode
 199     */
 200    void SetTextSelectable(bool textSelectable = true);
 201
 202    /**
 203     *  Check if Text can be selected
 204     *  @pre The text input actor has been initialised.
 205     *  @return  True or False to indicate if text can be selected or not
 206     */
 207    bool IsTextSelectable() const;
 208
 209    /**
 210     * Check if any text is currently selected, can be used to determine if ApplyStyle or SetActiveStyle should be used.
 211     * @pre The text input actor has been initialised.
 212     * @return True if text selected else False
 213     */
 214    bool IsTextSelected() const;
 215
 216    /**
 217     * Selects text between the given positions
 218     * @pre TextInput should be in edit mode.
 219     * @param start position to start selection
 220     * @param end position to end selection, inclusive of this character.
 221     * Providing 0 and result from GetNumberOfCharacters() will select all text.
 222     */
 223    void SelectText(std::size_t start, std::size_t end);
 224
 225    /**
 226     * If any text is selected then de-select it and hide highlight.
 227     * @pre The text input actor has been initialised.
 228     */
 229    void DeSelectText();
 230
 231    /**
 232     * Set the image to be used as the cursor grab hander
 233     * @pre The text input actor has been initialised.
 234     * @param[in] image The image to be used.
 235     */
 236    void SetGrabHandleImage( Image image );
 237
 238    /**
 239     * Set the image to be used for the regular left to right cursor
 240     * @pre The text input actor has been initialised.
 241     * @param[in] image The image to be used.
 242     * @param[in] border The nine patch border for the image.
 243     */
 244    void SetCursorImage(Dali::Image image, const Vector4& border );
 245
 246    /**
 247     * Retrieve the selection handle size. Both handles have same size.
 248     * @return Vector3 the selection handle size.
 249     */
 250    Vector3 GetSelectionHandleSize();
 251
 252    /**
 253     * Set the image to be used for the Right to Left cursor
 254     * @pre The text input actor has been initialised.
 255     * @param[in] image The image to be used.
 256     * @param[in] border The nine patch border for the image.
 257     */
 258     void SetRTLCursorImage(Dali::Image image, const Vector4& border );
 259
 260    /**
 261     * Toggle to enable the grab handle, used to position cursor when magnifier not being used.
 262     * Default behaviour is to use the magnifier to position the cursor, enabling this prevents the magnifier from being shown.
 263     * @param[in] toggle true to enable, false to disable grab handle
 264     */
 265    void EnableGrabHandle(bool toggle);
 266
 267    /**
 268     * Method to check if grab handle is enabled, if false then the magnifier will be used to position cursor.
 269     * @return bool returns true is grab handle enabled.
 270     */
 271    bool IsGrabHandleEnabled();
 272
 273   /**
 274    * Set the bounding rectangle which handles, popup and similar decorations will not exceed
 275    * The default value is the width and height of the stage from the top left origin.
 276    * If a title bar for example is on the top of the screen then the y should be the title's height and
 277    * the boundary height the stage height minus the title's height.
 278    * Restrictions - The boundary box should be set up with a fixed z position for the text-input and the default camera.
 279    * @param[in] boundingOriginAndSize Rect( x coordinate, y coordinate, width, height )
 280    * ------------------------------------------
 281    * |(x,y)                                   |
 282    * |o---------------------------------------|
 283    * ||                                      ||
 284    * ||            Bounding Box              || boundary height
 285    * ||                                      ||
 286    * |----------------------------------------|
 287    * ------------------------------------------
 288    *               boundary width
 289    */
 290   void SetBoundingRectangle( const Rect<float>& boundingOriginAndSize );
 291
 292   /**
 293    * Retrieve the bounding box origin and dimensions
 294    * default is set once control is added to stage, before this the return vector will be Vector4:ZERO
 295    * @return Rect the bounding rectangle
 296    */
 297   const Rect<float> GetBoundingRectangle() const;
 298
 299    /**
 300     * Sets the style for new text being typed.
 301     * By default all style settings are applied but a bit mask could be used to modify only certain style settings.
 302     * @pre The text input actor has been initialised.
 303     * @param[in] style The style for the new text.
 304     * @param[in] mask The bit mask.
 305     */
 306    void SetActiveStyle( const TextStyle& style, const TextStyle::Mask mask = TextStyle::ALL );
 307
 308    /**
 309     * Applies the given style to the selected text.
 310     * By default all style settings are applied but a bit mask could be used to modify only certain style settings.
 311     * Introduced text after this call uses the new style.
 312     * @param[in] style The given style.
 313     * @param[in] mask The bit mask.
 314     */
 315    void ApplyStyle( const TextStyle& style, const TextStyle::Mask mask = TextStyle::ALL );
 316
 317    /**
 318      * Applies the given style to all text, selected or not selected.
 319      * By default all style settings are applied but a bit mask could be used to modify only certain style settings.
 320      * @param[in] style The given style.
 321      * @param[in] mask The bit mask.
 322      */
 323    void ApplyStyleToAll( const TextStyle& style, const TextStyle::Mask mask = TextStyle::ALL );
 324
 325    /**
 326     * Get the style of the Text character before the cursor
 327     * If no character before then return the InputStyle.
 328     * @return TextStyle, the style of the character before the cursor
 329     */
 330    TextStyle GetStyleAtCursor() const;
 331
 332   /**
 333    * Set the current text alignment (overrides default setting)
 334    *
 335    * The default alignment is dependent on the current text in the text field.
 336    * If the text begins using LTR characters (e.g. European text) then the
 337    * alignment is HorizontalLeft. If the text begins using RTL characters
 338    * (e.g. Hebrew/Arabic text) then the alignment is HorizontalRight.
 339    * If there is no text, then the alignment defaults to:
 340    * (HorizontalLeft | VerticalCenter)
 341    * @param[in] align The new alignment option.
 342    */
 343   void SetTextAlignment( Toolkit::Alignment::Type align );
 344
 345   /**
 346    * Set the current line justification. (overrides default setting)
 347    * The default justification is dependent on the current text in the text field.
 348    * If the text begins using LTR characters (e.g. European text) then the
 349    * justification is HorizontalLeft. If the text begins using RTL characters
 350    * (e.g. Hebrew/Arabic text) then the justification is HorizontalRight.
 351    * If there is no text, then the justification defaults to:
 352    * (HorizontalLeft | VerticalCenter)
 353    * @param[in] justification The new line justification.
 354    */
 355   void SetTextLineJustification( Toolkit::TextView::LineJustification justification );
 356
 357   /**
 358    * Sets a fade boundary.
 359    *
 360    * @see TextView::FadeBoundary.
 361    *
 362    * @param[in] fadeBoundary The given fade boundary.
 363    */
 364   void SetFadeBoundary( const Toolkit::TextView::FadeBoundary& fadeBoundary );
 365
 366   /**
 367    * Retrieves the fade boundary.
 368    *
 369    * @see TextView::FadeBoundary.
 370    *
 371    * @return The fade boundary.
 372    */
 373   const Toolkit::TextView::FadeBoundary& GetFadeBoundary() const;
 374
 375   /**
 376    * Get the current text alignment combined into a single value.
 377    * The values can be tested by using the & operator
 378    * and the desired flag. e.g. if (GetTextAlignment() & HorizontalCentre) ...
 379    */
 380   Toolkit::Alignment::Type GetTextAlignment() const;
 381
 382   /**
 383    * Sets how to split the text in lines policy.
 384    * @param policy The multi-line policy.
 385    */
 386    void SetMultilinePolicy( Toolkit::TextView::MultilinePolicy policy );
 387
 388   /**
 389    * Gets the split in lines policy.
 390    * @return The multi-line policy.
 391    */
 392   Toolkit::TextView::MultilinePolicy GetMultilinePolicy() const;
 393
 394   /**
 395    * Sets how to display the text inside the TextView when it exceeds the text-view's width.
 396    * @param policy The exceed policy.
 397    */
 398   void SetWidthExceedPolicy( Toolkit::TextView::ExceedPolicy policy );
 399
 400   /**
 401    * Gets the width exceed policy.
 402    * @return The exceed policy.
 403    */
 404   TextView::ExceedPolicy GetWidthExceedPolicy() const;
 405
 406   /**
 407    * Sets how to display the text inside the TextView when it exceeds the text-view's height.
 408    * @param policy The exceed policy.
 409    */
 410   void SetHeightExceedPolicy( Toolkit::TextView::ExceedPolicy policy );
 411
 412   /**
 413    * Gets the height exceed policy.
 414    * @return The exceed policy.
 415    */
 416   TextView::ExceedPolicy GetHeightExceedPolicy() const;
 417
 418   /**
 419    * Sets if the inputed text can exceed the text-input boundary.
 420    *
 421    * By default is enabled.
 422    *
 423    * @param[in] enable Whether the inputed text can exceed its boundary.
 424    */
 425   void SetExceedEnabled( bool enable );
 426
 427   /**
 428    * Retrieves whether inputed text can exceed the text-input boundary.
 429    *
 430    * @return \e true if text inputed can exceed the boundary, otherwise \e false.
 431    */
 432   bool GetExceedEnabled() const;
 433
 434   /**
 435    * Allows modification of text-actor's position in the depth sort algorithm.
 436    *
 437    * @see Dali::RenderableActor::SetSortModifier()
 438    * @param [in] depthOffset the offset to be given to the internal text-actors. Positive values pushing it further back.
 439    */
 440   void SetSortModifier( float depthOffset );
 441
 442   /**
 443    * Sets whether text-view renders text using a previously generated snapshot.
 444    *
 445    * @see TextView::SetSnapshotModeEnabled()
 446    *
 447    * @param[in] enable Whether text-view is using or not a snapshot to render text.
 448    */
 449   void SetSnapshotModeEnabled( bool enable );
 450
 451   /**
 452    * Retrieves whether text-view is using a snapshot to render text
 453    *
 454    * @see TextView::IsSnapshotModeEnabled()
 455    *
 456    * @return \e true if text-view is using a snapshot to render text, otherwhise it returns \e false.
 457    */
 458   bool IsSnapshotModeEnabled() const;
 459
 460   /**
 461    * @copydoc TextView::SetScrollEnabled()
 462    */
 463   void SetScrollEnabled( bool enable );
 464
 465   /**
 466    * @copydoc TextView::IsScrollEnabled()
 467    */
 468   bool IsScrollEnabled() const;
 469
 470   /**
 471    * @copydoc TextView::SetScrollPosition()
 472    */
 473   void SetScrollPosition( const Vector2& position );
 474
 475   /**
 476    * @copydoc TextView::GetScrollPosition()
 477    */
 478   Vector2 GetScrollPosition() const;
 479
 480 public: /* Signals */
 481
 482   // Input Signal
 483   typedef SignalV2< void ( TextInput textInput ) > InputSignalV2;
 484
 485   // Input style changed signal
 486   typedef SignalV2< void ( TextInput textInput, const TextStyle& style ) > StyleChangedSignalV2;
 487
 488   // Max input characters reached signal
 489   typedef SignalV2< void ( TextInput textInput ) > MaxInputCharactersReachedSignalV2;
 490
 491   // Input text exceeds boundaries signal
 492   typedef SignalV2< void ( TextInput textInput ) > InputTextExceedBoundariesSignalV2;
 493
 494   /**
 495    * Signal emitted when the Text-Input starts receiving input.
 496    */
 497   InputSignalV2& InputStartedSignal();
 498
 499   /**
 500    * Signal emitted when the Text-Input is finished receiving input.
 501    * TextInput::GetText() can be called to get current text string.
 502    */
 503   InputSignalV2& InputFinishedSignal();
 504
 505   /**
 506    * Signal emitted when the cut and paste toolbar is displayed.
 507    */
 508   InputSignalV2& CutAndPasteToolBarDisplayedSignal();
 509
 510   /**
 511    * Signal emitted when style changes.
 512    */
 513   StyleChangedSignalV2& StyleChangedSignal();
 514
 515   /**
 516    * Signal emitted when max input characters are reached during text input.
 517    */
 518   MaxInputCharactersReachedSignalV2& MaxInputCharactersReachedSignal();
 519
 520   /**
 521    * Signal emitted when input text exceeds the boundaries of the text-input.
 522    */
 523   InputTextExceedBoundariesSignalV2& InputTextExceedBoundariesSignal();
 524
 525 public: // Not intended for application developers
 526
 527   /**
 528    * Creates a handle using the Toolkit::Internal implementation.
 529    * @param[in]  implementation  The Control implementation.
 530    */
 531   TextInput(Internal::TextInput& implementation);
 532
 533   /**
 534    * Allows the creation of this Control from an Internal::CustomActor pointer.
 535    * @param[in]  internal  A pointer to the internal CustomActor.
 536    */
 537   TextInput(Dali::Internal::CustomActor* internal );
 538 };
 539
 540 } // namespace Toolkit
 541
 542 } // namespace Dali
 543
 544 /**
 545  * @}
 546  */
 547 #endif // __DALI_TOOLKIT_TEXT_INPUT_H__