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