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