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