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