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