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