dali-toolkit/internal/controls/text-input/text-input-decorator-impl.h

   1 #ifndef __DALI_TOOLKIT_INTERNAL_TEXT_INPUT_DECORATOR_H__
   2 #define __DALI_TOOLKIT_INTERNAL_TEXT_INPUT_DECORATOR_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 // EXTERNAL INCLUDES
  22 #include <dali/public-api/actors/image-actor.h>
  23 #include <dali/public-api/adaptor-framework/timer.h>
  24 #include <dali/public-api/animation/animation.h>
  25 #include <dali/public-api/common/intrusive-ptr.h>
  26 #include <dali/public-api/signals/connection-tracker.h>
  27
  28 // INTERNAL INCLUDES
  29 #include <dali-toolkit/internal/controls/text-input/textview-character-positions-impl.h>
  30 #include <dali-toolkit/internal/controls/text-input/text-input-handles-impl.h>
  31 #include <dali-toolkit/internal/controls/text-input/text-input-text-highlight-impl.h>
  32 #include <dali-toolkit/internal/controls/text-input/text-input-popup-new-impl.h>
  33
  34 namespace Dali
  35 {
  36
  37 namespace Toolkit
  38 {
  39
  40 namespace Internal
  41 {
  42
  43 class Decorator;
  44
  45 typedef IntrusivePtr<Decorator> DecoratorPtr;
  46
  47 /**
  48  *  @brief Decorator Class
  49  *
  50  *  Decorations are Selection Handles, cursor, grab handle, magnifier the "cut copy paste" PopUp and Selection highlight.
  51  *  The Decorator triggers creation of these decorations and positions them.
  52  *  Decoration positions can be dependent on other decorations like the PopUp on the Selection handles.
  53  *  The decorator maintains a Bounding Box which the decorations have to be positioned within, decorations can be flipped or hidden to obey this Bounding Box.
  54  *  Scrolling of Text can effect positioning of decorations, the decorator repositions decorations in this case.
  55  */
  56
  57 class Decorator : public ConnectionTracker
  58 {
  59
  60 public:
  61
  62   /**
  63    * @brief Constructor
  64    *
  65    * @param[in] textviewManager TextViewManager to be used
  66    */
  67   Decorator( TextViewCharacterPositioning& textviewManager, TextInputTextStyle& textStyle);
  68
  69   /**
  70    * @brief Default destructor
  71    */
  72   ~Decorator();
  73
  74   /**
  75    * @brief Set the dimensions of the bounding rectangle for decorations to obey.
  76    *
  77    * @param[in] boundingRectangle
  78    */
  79   void SetBoundingBox( const Rect<float>& boundingRectangle );
  80
  81   /**
  82    * @brief Get the bounding dimensions of the bounding box
  83    *
  84    * @return dimensions of the bounding box from world origin. (x, y, w, z )
  85    *
  86    *  -----------------
  87    * |        ^        |
  88    * |        |        |
  89    * |        y        |
  90    * |        |        |
  91    * |        v        |
  92    * |<--x--> o <--z-->|
  93    * |        ^        |
  94    * |        |        |
  95    * |        w        |
  96    * |        |        |
  97    * |        v        |
  98    *  -----------------
  99    */
 100   Vector4 GetBoundingBox() const;
 101
 102   /**
 103    * @brief Callback when a handle is panned/moved, either selection handles or grab handle
 104    *
 105    * @param actor Handle of the selection or grab handle.
 106    * @param gesture Data structure with the parameters of the gesture.
 107    */
 108   void OnHandlePan(Actor actor, const PanGesture& gesture);
 109
 110   // Selection Handles
 111
 112   /**
 113    * @brief Create a left and right selection handle and parent both to the provided actor
 114    * @param[in] parent actor in which the handles should be added to.
 115    */
 116   void CreateSelectionHandles( Actor parent );
 117
 118   /**
 119    * @brief Remove selection handles from their parent
 120    */
 121   void RemoveSelectionHandles();
 122
 123   /**
 124    * @brief Get size of Selection handles
 125    *
 126    * @return size of a selection handle
 127    */
 128   Vector3 GetSelectionHandleSize();
 129
 130   /**
 131    * @brief Get position of Selection handle within text
 132    *
 133    * @return character position of a selection handle one
 134    */
 135   std::size_t GetHandleOnePosition() const;
 136
 137   /**
 138    * @brief Get position of Selection handle within text
 139    *
 140    * @return character position of a selection handle two
 141    */
 142   std::size_t GetHandleTwoPosition() const;
 143
 144   /**
 145    * @brief Position Selection a single handle at given positions within the text string.
 146    *
 147    * @param[in] selectionHandle handle to be positioned
 148    * @param[in] position where to place handle
 149    * @return Vector3 Position of handle as a coordinate.
 150    */
 151   Vector3 PositionSelectionHandle( Actor selectionHandle, std::size_t position );
 152
 153   /**
 154    * @brief Position Selection a single handle at given coordinates
 155    *
 156    * @param[in] selectionHandle handle to be positioned
 157    * @param[in] actualPosition coordinates to position handle
 158    * @param[in] position where to place handle
 159    * @return Vector3 Position of handle as a coordinate.
 160    */
 161   Vector3 PositionSelectionHandle( Actor selectionHandle, Vector3& actualPosition, std::size_t position );
 162
 163   /**
 164    * @brief Make both selection handle visible or invisible
 165    * @param[in] visible true to make visible, false to fine
 166    */
 167   void SetSelectionHandlesVisibility( bool visible );
 168
 169   /**
 170    * @brief Position Selection handles at given positions within the text string.
 171    *
 172    * @param[in] start where to place first handle
 173    * @param[in] end  where to place second handle
 174    */
 175   void PositionSelectionHandles( std::size_t start, std::size_t end );
 176
 177   /**
 178    * @brief Move selection handle by the given displacement.
 179    *
 180    * @param[in] selectionHandle Actor to move
 181    * @param[in] actualSelectionHandlePosition actual current position of the handle in x y z
 182    * @param[in] currentSelectionHandlePosition current position along the string
 183    * @param[in] displacement the x y displacement
 184    */
 185   Vector3 MoveSelectionHandle( Actor selectionHandle,
 186                                Vector3& actualSelectionHandlePosition,
 187                                std::size_t& currentSelectionHandlePosition,
 188                                const Vector2& displacement );
 189
 190   /* Grab Handle */
 191
 192   /**
 193    * @brief Position GrabHandlewith depending on the the character in the text it should be placed at
 194    * @param[in] positonInText the character position within the text the handle should be at
 195    */
 196   void PositionGrabHandle( std::size_t positionInText );
 197
 198   /**
 199    * @brief Move grab handle to the required position within the text
 200    *
 201    * @param[in] displacement Displacement of the grab handle in actor coordinates.
 202    */
 203   void MoveGrabHandle( const Vector2& displacement );
 204
 205   /**
 206    * @brief Show or hide the GrabHandle is visibility is true
 207    *
 208    * @param[in] visible flag to show or not show the grab handle
 209    */
 210   void ShowGrabHandle( bool visible );
 211
 212   /**
 213    * @brief Create the GrabHandle used to position cursor
 214    * @param[in] targetParent the Actor to parent the GrabHandle
 215    */
 216   void CreateGrabHandle( Actor targetParent );
 217
 218   /**
 219    * @brief Set the image to be used as the cursor grab hander
 220    * @pre The text input actor has been initialised.
 221    * @param[in] image The image to be used.
 222    */
 223   void SetGrabHandleImage( Image image );
 224
 225   /**
 226    * @brief Toggle to enable the grab handle, used to position cursor when magnifier not being used.
 227    * Default behaviour is to use the magnifier to position the cursor, enabling this prevents the magnifier from being shown.
 228    * @param[in] toggle true to enable, false to disable grab handle
 229    */
 230   void EnableGrabHandle(bool toggle);
 231
 232   /**
 233    * @brief Method to check if grab handle is enabled, if false then the magnifier will be used to position cursor.
 234    * @return bool returns true is grab handle enabled.
 235    */
 236   bool IsGrabHandleEnabled();
 237
 238   /* Cursor */
 239
 240   /**
 241    * @brief Get the current Cursor position
 242    * @return current cursor position
 243    */
 244   std::size_t GetCurrentCursorPosition() const;
 245
 246   /**
 247    * @brief Set the Cursor position
 248    * @param[in] the position the cursor should be set to
 249    */
 250   void SetCurrentCursorPosition( std::size_t newCursorPosition );
 251
 252   /**
 253    * @brief Set if the cursors are visible or not.
 254    * @param[in] visible flag true for visible
 255    */
 256   void SetCursorVisibility( bool visible );
 257
 258   /**
 259    * @brief Display cursor
 260    * @param[in] nthChar position in text string to display cursor
 261    */
 262   void DrawCursor( const std::size_t nthChar = 0 );
 263
 264   /**
 265    * Sets alternate cursor enable state
 266    * @see SetCursorVisibility
 267    * alternate cursor will only be visible if both SetCursorVisiblity
 268    * and cursor enabled have been set to true.
 269    */
 270   void SetAltCursorEnabled( bool enabled );
 271
 272   /**
 273    * @brief Set the image to be used for the regular left to right cursor
 274    * @pre The text input actor has been initialised.
 275    * @param[in] image The image to be used.
 276    * @param[in] border The nine patch border for the image.
 277    */
 278   void SetCursorImage( Image image, const Vector4& border );
 279
 280   /**
 281    * @brief Set the image to be used for the Right to Left cursor
 282    * @pre The text input actor has been initialised.
 283    * @param[in] image The image to be used.
 284    * @param[in] border The nine patch border for the image.
 285    */
 286   void SetRTLCursorImage( Image image, const Vector4& border );
 287
 288   /**
 289    * @brief Creates a cursor from the supplied image and nine patch border.
 290    * @param[in] cursorImage the image to be used for the cursor.
 291    * @param[in] border the nine patch border corresponding to the supplied image.
 292    * @paran[in] cursorName actor name for cursor
 293    * @return the image actor to be used as the cursor.
 294    */
 295   ImageActor CreateCursor( Image cursorImage, const Vector4& border,  const std::string& cursorName );
 296
 297   /**
 298    * @brief Creates a regular and Right-To-Left cursor and parents them to give target Actor
 299    * @param[in] targetParent target Actor
 300    */
 301   void CreateCursors( Actor targetParent );
 302
 303   /**
 304    * @Brief Returns the cursor size at a given position in the text.
 305    * @return Size the size of the cursor
 306    */
 307   Size GetCursorSizeAt( std::size_t positionWithinTextToGetCursorSize );
 308
 309   /**
 310    * @brief  Start a timer to signal cursor to blink.
 311    */
 312   void StartCursorBlinkTimer();
 313
 314   /**
 315    * @brief  Stop the timer signalling the cursor to blink.
 316    */
 317   void StopCursorBlinkTimer();
 318
 319   /**
 320    * @brief Callback when handle timer ticks.
 321    *
 322    * Cursor should become visible/invisible to simulate blinking.
 323    *
 324    * @return True if the timer should be keep running.
 325    */
 326   bool OnCursorBlinkTimerTick();
 327
 328   /* Selection Highlight */
 329
 330   /**
 331    * @brief Updates mesh data for selection highlight depending on handle positions and displays it.
 332    */
 333   void ShowUpdatedHighlight();
 334
 335   /**
 336    * @brief Creates the Highlight used for selection
 337    *
 338    * @param[in] parent target actor in which the handles should be added to.
 339    */
 340   void CreateHighlight( Actor parent );
 341
 342   /**
 343    * @brief Remove Highlight actor from it's parent
 344    */
 345   void RemoveHighlight();
 346
 347   /**
 348    * @brief Set the visibility of the Highlight
 349    *
 350    * @param[in] visibility True to show and False to hide.
 351    */
 352   void HighlightVisibility( bool visiblility );
 353
 354   /* Boundary Property Notifications when handle exceed bounding box*/
 355
 356   /**
 357    * @brief PropertyNotification Callback when left boundary exceeded so handle can be flipped.
 358    *
 359    * @param[in] source PropertyNotification
 360    */
 361   void OnLeftBoundaryExceeded( PropertyNotification& source );
 362   /**
 363    * @brief PropertyNotification Callback when within left boundary so handle can be flipped back.
 364    *
 365    * @param[in] source PropertyNotification
 366    */
 367   void OnReturnToLeftBoundary( PropertyNotification& source );
 368   /**
 369    * @brief PropertyNotification Callback when right boundary exceeded so handle can be flipped.
 370    *
 371    * @param[in] source PropertyNotification
 372    */
 373   void OnRightBoundaryExceeded( PropertyNotification& source );
 374   /**
 375    * @brief PropertyNotification Callback when within right boundary so handle can be flipped back.
 376    *
 377    * @param[in] source PropertyNotification
 378    */
 379   void OnReturnToRightBoundary( PropertyNotification& source );
 380
 381   /**
 382    * @brief PropertyNotification Callbacks for hiding handle one when it exceeds boundary.
 383    *
 384    * @param[in] source PropertyNotification
 385    */
 386   void OnHandleOneLeavesBoundary( PropertyNotification& source );
 387   /**
 388    * @brief PropertyNotification Callbacks for showing hidden handle one when returns within boundary
 389    *
 390    * @param[in] source PropertyNotification
 391    */
 392   void OnHandleOneWithinBoundary( PropertyNotification& source );
 393   /**
 394    * @brief PropertyNotification Callbacks for hiding handle two it  when exceeds boundary.
 395    *
 396    * @param[in] source PropertyNotification
 397    */
 398   void OnHandleTwoLeavesBoundary( PropertyNotification& source );
 399   /**
 400    * @brief PropertyNotification Callbacks for showing hidden handle two when returns within boundary
 401    *
 402    * @param[in] source PropertyNotification
 403    */
 404   void OnHandleTwoWithinBoundary( PropertyNotification& source );
 405
 406   /**
 407    * @brief Set up property notifications on the position of the handles to facilitate flipping and hiding when at screen boundary.
 408    */
 409   void SetUpHandlePropertyNotifications();
 410
 411   // Cut & Paste Pop-up
 412
 413   /**
 414    * @brief Calculate positioning of PopUp relative to handles
 415    * @return Actual position of PopUp
 416    */
 417   Vector3 PositionOfPopUpRelativeToSelectionHandles( );
 418
 419   /**
 420    * @brief Calculate alternative position of PopUp relative to handles  when can it not be displayed in the default upper position.
 421    * @return Actual position of PopUp
 422    */
 423   Vector3 AlternatePopUpPositionRelativeToSelectionHandles();
 424
 425   /**
 426    * @brief Calculate positioning of PopUp relative to cursor
 427    * @return Actual position of PopUp
 428    */
 429   Vector3 PositionOfPopUpRelativeToCursor();
 430
 431   /**
 432    * @brief Calculate alternative position of PopUp relative to cursor when can not be displayed in normal upper position.
 433    * @return Actual position of PopUp
 434    */
 435   Vector3 AlternatePopUpPositionRelativeToCursor();
 436
 437   /**
 438    * @brief Calculate positioning of PopUp relative to GrabHandle
 439    * @return Actual position of PopUp
 440    */
 441   Vector3 PositionOfPopUpRelativeToGrabHandle();
 442
 443  /**
 444   * @brief Show the PopUp in the provided target
 445   * @param[in] target target actor in which the PopUp should be added to.
 446   */
 447   void ShowPopUp( Actor target );
 448
 449   /**
 450    * @brief Show PopUp in previously set Target.
 451    * @pre Must have previously called ShopPopUp( Actor target ) otherwise PopUp will not be shown.
 452    */
 453   void ShowPopUp();
 454
 455   /**
 456    * @brief Create and Show Cut Copy Paste PopUp
 457    */
 458   void ShowPopupCutCopyPaste();
 459
 460   /**
 461    * @brief Hide PopUp
 462    * @param[in] animate Animate or just hide instantly, default is true
 463    * @param[in] signalFinished Signal when finished, default is true
 464    */
 465   void HidePopUp( bool animate=true, bool signalFinished=true );
 466
 467   /**
 468    * @brief Adds a popup option.
 469    * @brief Creates popup frame if not already created.
 470    * @param[in] name The unique name for this option.
 471    * @param[in] caption The caption (label) for this option
 472    * @param[in] icon the image icon to be displayed for this option
 473    * @param[in] finalOption Flag to indicate that this is the final option.
 474    * (set to true on the last option you add)
 475    */
 476   void AddPopupOption(const std::string& name, const std::string& caption, const Image icon, bool finalOption = false);
 477
 478   /**
 479    * @brief Removes popup, and its options.
 480    */
 481   void ClearPopup();
 482
 483   /**
 484    * @brief PropertyNotification Callbacks for flipping PopUp when exceeds boundary.
 485    * @param[in] source PropertyNotification
 486    */
 487   void PopUpLeavesVerticalBoundary( PropertyNotification& source );
 488
 489   /**
 490    * @brief Setup position notifications when PopUp exceeds boundary
 491    */
 492   void SetUpPopUpPositionNotifications( );
 493
 494   /**
 495    * @brief Callback for when a button is pressed in popup panel
 496    * @param[in] button handle to the button pressed.
 497    * @return bool consummation
 498    */
 499   bool OnPopupButtonPressed( Toolkit::Button button );
 500
 501   // Decoration positioning during scrolling
 502
 503   /**
 504    * @brief Updates the position of the decorations when Text is scrolled.
 505    *
 506    * @param[in] textView Handle of the text-view.
 507    * @param[in] scrollPosition The difference with the previous scroll position.
 508    */
 509   void TextViewScrolled( Toolkit::TextView textView, Vector2 scrollPosition );
 510
 511   /**
 512    * @brief  Creates and starts a timer to scroll the text when handles are close to the edges of the text-input.
 513    *
 514    * It only starts the timer if it's already created.
 515    */
 516   void StartScrollTimer();
 517
 518   /**
 519    * @brief  Stops the timer used to scroll the text.
 520    */
 521   void StopScrollTimer();
 522
 523   /**
 524    * @brief Scroll Text according to handle position
 525    * @param[in out] handlePosition handle position within character string
 526    * @param[in] actual vector position of handle
 527    * @return updated actual vector position of handle
 528    */
 529   Vector3 ScrollRelativeToHandle( std::size_t& handlePosition, Vector3& actualHandlePosition );
 530
 531   /**
 532    * @brief Callback called by the timer used to scroll the text.
 533    *
 534    * It calculates and sets a new scroll position.
 535    */
 536   bool OnScrollTimerTick();
 537
 538   // Text Selection
 539
 540   /**
 541    * @brief Function to get Text selected between the 2 selection handles.
 542    * @return StyledTextArray an array of
 543    */
 544   MarkupProcessor::StyledTextArray GetSelectedText();
 545
 546 private:
 547
 548   /**
 549    * @brief Copy Constructor
 550    * @param[in] decorator
 551    * Undefined/Hidden.
 552    */
 553   Decorator(const Decorator& decorator);
 554
 555   /**
 556    * @Assignment Constructor
 557    * @param[in] rhs
 558    * Undefined/Hidden.
 559    */
 560   Decorator& operator=(const Decorator& rhs);
 561
 562 public:
 563
 564   typedef Signal< bool( Toolkit::Button ) > PressedSignal;
 565   typedef Signal< void () > CursorPositionedSignal;
 566   /**
 567    * @brief Signal emitted when the button is touched.
 568    * This is relayed from the PopUp class.  It enables the owner of the Decorator to act on the PopUp button press.
 569    */
 570   PressedSignal& PopUpButtonPressedSignal();
 571
 572   /**
 573    * @brief Signal emitted when the cursor is repositioned
 574    * @param[in] cursor the new cursor position
 575    */
 576   CursorPositionedSignal& CursorRePositionedSignal();
 577
 578 private:
 579
 580   Vector4 mBoundingRectangleWorldCoordinates;
 581
 582   TextViewCharacterPositioning& mTextViewCharacterPositioning;
 583
 584   TextInputHandles mTextInputHandles;
 585
 586   TextInputTextStyle& mTextStyle;
 587
 588   Vector3 mSelectionHandleOneActualPosition;    // Actual x y position of handle
 589   Vector3 mSelectionHandleTwoActualPosition;    // Actual x y position of handle
 590   std::size_t mSelectionHandleOnePosition;      // Position of handle along the string of text
 591   std::size_t mSelectionHandleTwoPosition;      // Position of handle along the string of text
 592
 593   TextInputPopupNew mPopUpPanel;                // PopUp used for Cut Cpoy and Paste
 594   Actor mPopUpTarget;                           // Target Actor to parent PopUp
 595
 596   Vector3 mActualGrabHandlePosition;            // Actual position of grab handle, this might not be snapped to a character
 597   std::size_t mGrabHandlePosition;              // Position of grab handle along the string of text
 598   Vector3 mCurrentHandlePosition;
 599
 600   std::size_t mCursorPosition;                  // Current cursor position within the text string
 601   ImageActor mCursor;                           // Cursor overlayed on Text to show where new text will be inserted
 602   ImageActor mCursorRTL;                        // Right To Left Cursor overlayed on Text (where new RTL text would be inserted)
 603   Animation mCursorAnimation;                   // Animation for cursor blinking.
 604   Timer mCursorBlinkTimer;                      // Timer to signal cursor to blink
 605
 606   Vector2 mScrollDisplacement;                  // How much to scroll by
 607   Timer mScrollTimer;                           // Timer to scroll text over a period of time not all in one update.
 608
 609   TextHighlight mTextHighlight;                 // Holds data required to construct the highlight
 610
 611   PanGestureDetector mPanGestureDetector;
 612
 613   PressedSignal mPopUpButtonPressedSignal;           // Signal emitted when a button within the popup is pressed.
 614   CursorPositionedSignal mCursorRePositionedSignal;  // Signal emitted when a button when cursor position is changed.
 615
 616   bool mCursorBlinkStatus:1;                    // \e true shows the cursor, \e false hides it.
 617   bool mCursorVisibility:1;                     // Should cursor be visible
 618   bool mCursorRTLEnabled:1;                     // Enable state of Alternate RTL Cursor (need to keep track of this as it's not always enabled)
 619   bool mIsGrabHandleInScrollArea:1;             // Whether the grab handle is inside the boundaries of the text-input.
 620   bool mIsCursorInScrollArea:1;                 // Whether the cursor is inside the boundaries of the text-input.
 621   bool mGrabHandleVisibility:1;                 // Should grab handle be visible
 622   bool mGrabHandleEnabled:1;                    // Flag to enable the grab handle instead of the default magnifier.
 623 };
 624
 625 } // namespace Internal
 626
 627 } // namespace Toolkit
 628
 629 } // namespace Dali
 630
 631 #endif // __DALI_TOOLKIT_INTERNAL_TEXT_INPUT_DECORATOR_H__