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