dali-toolkit/internal/text/decorator/text-decorator.h

   1 #ifndef __DALI_TOOLKIT_TEXT_DECORATOR_H__
   2 #define __DALI_TOOLKIT_TEXT_DECORATOR_H__
   3
   4 /*
   5  * Copyright (c) 2015 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/common/intrusive-ptr.h>
  23 #include <dali/public-api/object/ref-object.h>
  24 #include <dali/public-api/math/rect.h>
  25 #include <dali/public-api/math/vector2.h>
  26
  27 // INTERNAL INCLUDES
  28 #include <dali-toolkit/devel-api/controls/text-controls/text-selection-popup.h>
  29
  30 namespace Dali
  31 {
  32
  33 class Actor;
  34 class Image;
  35 class Vector2;
  36 class Vector4;
  37
  38 namespace Toolkit
  39 {
  40
  41 class TextSelectionPopupCallbackInterface;
  42
  43 namespace Internal
  44 {
  45 class Control;
  46 }
  47
  48 namespace Text
  49 {
  50
  51 class Decorator;
  52 typedef IntrusivePtr<Decorator> DecoratorPtr;
  53
  54 // Used to set the cursor positions etc.
  55 enum Cursor
  56 {
  57   PRIMARY_CURSOR,   ///< The primary cursor for bidirectional text (or the regular cursor for single-direction text)
  58   SECONDARY_CURSOR, ///< The secondary cursor for bidirectional text
  59   CURSOR_COUNT
  60 };
  61
  62 // Determines which of the cursors are active (if any).
  63 enum ActiveCursor
  64 {
  65   ACTIVE_CURSOR_NONE,    ///< Neither primary nor secondary cursor are active
  66   ACTIVE_CURSOR_PRIMARY, ///< Primary cursor is active (only)
  67   ACTIVE_CURSOR_BOTH     ///< Both primary and secondary cursor are active
  68 };
  69
  70 // The state information for handle events.
  71 enum HandleState
  72 {
  73   HANDLE_TAPPED,
  74   HANDLE_PRESSED,
  75   HANDLE_RELEASED,
  76   HANDLE_SCROLLING,
  77   HANDLE_STOP_SCROLLING
  78 };
  79
  80 // Used to set different handle images
  81 enum HandleImageType
  82 {
  83   HANDLE_IMAGE_PRESSED,
  84   HANDLE_IMAGE_RELEASED,
  85   HANDLE_IMAGE_TYPE_COUNT
  86 };
  87
  88 // Types of handles.
  89 enum HandleType
  90 {
  91   GRAB_HANDLE,
  92   LEFT_SELECTION_HANDLE,
  93   RIGHT_SELECTION_HANDLE,
  94   HANDLE_TYPE_COUNT
  95 };
  96
  97 /**
  98  * @brief A Text Decorator is used to display cursors, handles, selection highlights and pop-ups.
  99  *
 100  * The decorator is responsible for clipping decorations which are positioned outside of the parent area.
 101  *
 102  * The Popup decoration will be positioned either above the Grab handle or above the selection handles but if doing so
 103  * would cause the Popup to exceed the Decoration Bounding Box ( see SetBoundingBox API ) the the Popup will be repositioned below the handle(s).
 104  *
 105  * Selection handles will be flipped around to ensure they do not exceed the Decoration Bounding Box. ( Stay visible ).
 106  *
 107  * Decorator components forward input events to a controller class through an interface.
 108  * The controller is responsible for selecting which components are active.
 109  */
 110 class Decorator : public RefObject
 111 {
 112 public:
 113
 114   class ControllerInterface
 115   {
 116   public:
 117
 118     /**
 119      * @brief Constructor.
 120      */
 121     ControllerInterface() {};
 122
 123     /**
 124      * @brief Virtual destructor.
 125      */
 126     virtual ~ControllerInterface() {};
 127
 128     /**
 129      * @brief An input event from one of the handles.
 130      *
 131      * @param[out] targetSize The Size of the UI control the decorator is adding it's decorations to.
 132      */
 133     virtual void GetTargetSize( Vector2& targetSize ) = 0;
 134
 135     /**
 136      * @brief Add a decoration to the parent UI control.
 137      *
 138      * @param[in] decoration The actor displaying a decoration.
 139      */
 140     virtual void AddDecoration( Actor& actor, bool needsClipping ) = 0;
 141
 142     /**
 143      * @brief An input event from one of the handles.
 144      *
 145      * @param[in] handleType The handle's type.
 146      * @param[in] state The handle's state.
 147      * @param[in] x The x position relative to the top-left of the parent control.
 148      * @param[in] y The y position relative to the top-left of the parent control.
 149      */
 150     virtual void DecorationEvent( HandleType handleType, HandleState state, float x, float y ) = 0;
 151   };
 152
 153   /**
 154    * @brief Create a new instance of a Decorator.
 155    *
 156    * @param[in] controller The controller which receives input events from Decorator components.
 157    * @param[in] callbackInterface The text popup callback interface which receives the button click callbacks.
 158    *
 159    * @return A pointer to a new Decorator.
 160    */
 161   static DecoratorPtr New( ControllerInterface& controller,
 162                            TextSelectionPopupCallbackInterface& callbackInterface );
 163
 164   /**
 165    * @brief Set the bounding box which handles, popup and similar decorations will not exceed.
 166    *
 167    * The default value is the width and height of the stage from the top left origin.
 168    * If a title bar for example is on the top of the screen then the y should be the title's height and
 169    * the boundary height the stage height minus the title's height.
 170    * Restrictions - The boundary box should be set up with a fixed z position for the text-input and the default camera.
 171    *
 172    * ------------------------------------------
 173    * |(x,y)                                   |
 174    * |o---------------------------------------|
 175    * ||                                      ||
 176    * ||            Bounding Box              || boundary height
 177    * ||                                      ||
 178    * |----------------------------------------|
 179    * ------------------------------------------
 180    *               boundary width
 181    *
 182    * @param[in] boundingBox Vector( x coordinate, y coordinate, width, height )
 183    */
 184   void SetBoundingBox( const Rect<int>& boundingBox );
 185
 186   /**
 187    * @brief Retrieve the bounding box origin and dimensions.
 188    *
 189    * default is set once control is added to stage, before this the return vector will be Vector4:ZERO
 190    * @return Rect<int> the bounding box origin, width and height
 191    */
 192   const Rect<int>& GetBoundingBox() const;
 193
 194   /**
 195    * @brief The decorator waits until a relayout before creating actors etc.
 196    *
 197    * @param[in] size The size of the parent control after size-negotiation.
 198    */
 199   void Relayout( const Dali::Vector2& size );
 200
 201   /**
 202    * @brief Updates the decorator's actor positions after scrolling.
 203    *
 204    * @param[in] scrollOffset The scroll offset.
 205    */
 206   void UpdatePositions( const Vector2& scrollOffset );
 207
 208   /**
 209    * @brief Sets which of the cursors are active.
 210    *
 211    * @note Cursor will only be visible if within the parent area.
 212    * @param[in] activeCursor Which of the cursors should be active (if any).
 213    */
 214   void SetActiveCursor( ActiveCursor activeCursor );
 215
 216   /**
 217    * @brief Query which of the cursors are active.
 218    *
 219    * @return  Which of the cursors are active (if any).
 220    */
 221   unsigned int GetActiveCursor() const;
 222
 223   /**
 224    * @brief Sets the position of a cursor.
 225    *
 226    * @param[in] cursor The cursor to set.
 227    * @param[in] x The x position relative to the top-left of the parent control.
 228    * @param[in] y The y position relative to the top-left of the parent control.
 229    * @param[in] cursorHeight The logical height of the cursor.
 230    * @param[in] lineHeight The logical height of the line.
 231    */
 232   void SetPosition( Cursor cursor, float x, float y, float cursorHeight, float lineHeight );
 233
 234   /**
 235    * @brief Retrieves the position, height and lineHeight of a cursor.
 236    *
 237    * @param[in] cursor The cursor to get.
 238    * @param[out] x The x position relative to the top-left of the parent control.
 239    * @param[out] y The y position relative to the top-left of the parent control.
 240    * @param[out] cursorHeight The logical height of the cursor.
 241    * @param[out] lineHeight The logical height of the line.
 242    */
 243   void GetPosition( Cursor cursor, float& x, float& y, float& cursorHeight, float& lineHeight ) const;
 244
 245   /**
 246    * @brief Retrieves the position of a cursor.
 247    *
 248    * @param[in] cursor The cursor to get.
 249    *
 250    * @return The position.
 251    */
 252   const Vector2& GetPosition( Cursor cursor ) const;
 253
 254   /**
 255    * @brief Sets the color for a cursor.
 256    *
 257    * @param[in] cursor Whether this color is for the primary or secondary cursor.
 258    * @param[in] color The color to use.
 259    */
 260   void SetColor( Cursor cursor, const Dali::Vector4& color );
 261
 262   /**
 263    * @brief Retrieves the color for a cursor.
 264    *
 265    * @param[in] cursor Whether this color is for the primary or secondary cursor.
 266    * @return The cursor color.
 267    */
 268   const Dali::Vector4& GetColor( Cursor cursor ) const;
 269
 270   /**
 271    * @brief Start blinking the cursor; see also SetCursorBlinkDuration().
 272    */
 273   void StartCursorBlink();
 274
 275   /**
 276    * @brief Stop blinking the cursor.
 277    */
 278   void StopCursorBlink();
 279
 280   /**
 281    * @brief Set the interval between cursor blinks.
 282    *
 283    * @param[in] seconds The interval in seconds.
 284    */
 285   void SetCursorBlinkInterval( float seconds );
 286
 287   /**
 288    * @brief Retrieves the blink-interval for a cursor.
 289    *
 290    * @return The cursor blink-interval.
 291    */
 292   float GetCursorBlinkInterval() const;
 293
 294   /**
 295    * @brief The cursor will stop blinking after this duration.
 296    *
 297    * @param[in] seconds The duration in seconds.
 298    */
 299   void SetCursorBlinkDuration( float seconds );
 300
 301   /**
 302    * @brief Retrieves the blink-duration for a cursor.
 303    *
 304    * @return The cursor blink-duration.
 305    */
 306   float GetCursorBlinkDuration() const;
 307
 308   /**
 309    * @brief Sets whether a handle is active.
 310    *
 311    * @param[in] handleType One of the handles.
 312    * @param[in] active True if the handle should be active.
 313    */
 314   void SetHandleActive( HandleType handleType,
 315                         bool active );
 316
 317   /**
 318    * @brief Query whether a handle is active.
 319    *
 320    * @param[in] handleType One of the handles.
 321    *
 322    * @return True if the handle is active.
 323    */
 324   bool IsHandleActive( HandleType handleType ) const;
 325
 326   /**
 327    * @brief Sets the image for one of the handles.
 328    *
 329    * @param[in] handleType One of the handles.
 330    * @param[in] handleImageType A different image can be set for the pressed/released states.
 331    * @param[in] image The image to use.
 332    */
 333   void SetHandleImage( HandleType handleType, HandleImageType handleImageType, Dali::Image image );
 334
 335   /**
 336    * @brief Retrieves the image for one of the handles.
 337    *
 338    * @param[in] handleType One of the handles.
 339    * @param[in] handleImageType A different image can be set for the pressed/released states.
 340    *
 341    * @return The grab handle image.
 342    */
 343   Dali::Image GetHandleImage( HandleType handleType, HandleImageType handleImageType ) const;
 344
 345   /**
 346    * @brief Sets the position of a selection handle.
 347    *
 348    * @param[in] handleType The handle to set.
 349    * @param[in] x The x position relative to the top-left of the parent control.
 350    * @param[in] y The y position relative to the top-left of the parent control.
 351    * @param[in] lineHeight The logical line height at this position.
 352    */
 353   void SetPosition( HandleType handleType, float x, float y, float lineHeight );
 354
 355   /**
 356    * @brief Retrieves the position of a selection handle.
 357    *
 358    * @param[in] handleType The handle to get.
 359    * @param[out] x The x position relative to the top-left of the parent control.
 360    * @param[out] y The y position relative to the top-left of the parent control.
 361    * @param[out] lineHeight The logical line height at this position.
 362    */
 363   void GetPosition( HandleType handleType, float& x, float& y, float& lineHeight ) const;
 364
 365   /**
 366    * @brief Retrieves the position of a selection handle.
 367    *
 368    * @param[in] handleType The handle to get.
 369    *
 370    * @return The position of the selection handle relative to the top-left of the parent control.
 371    */
 372   const Vector2& GetPosition( HandleType handleType ) const;
 373
 374   /**
 375    * @brief Swaps the selection handle's images.
 376    *
 377    * This method is called by the text controller to swap the handles
 378    * when the start index is bigger than the end one.
 379    */
 380   void SwapSelectionHandlesEnabled( bool enable );
 381
 382   /**
 383    * @brief Adds a quad to the existing selection highlights.
 384    *
 385    * @param[in] x1 The top-left x position.
 386    * @param[in] y1 The top-left y position.
 387    * @param[in] x2 The bottom-right x position.
 388    * @param[in] y3 The bottom-right y position.
 389    */
 390   void AddHighlight( float x1, float y1, float x2, float y2 );
 391
 392   /**
 393    * @brief Removes all of the previously added highlights.
 394    */
 395   void ClearHighlights();
 396
 397   /**
 398    * @brief Sets the selection highlight color.
 399    *
 400    * @param[in] image The image to use.
 401    */
 402   void SetHighlightColor( const Vector4& color );
 403
 404   /**
 405    * @brief Retrieves the selection highlight color.
 406    *
 407    * @return The image.
 408    */
 409   const Vector4& GetHighlightColor() const;
 410
 411   /**
 412    * @brief Set the Selection Popup to show or hide via the active flaf
 413    * @param[in] active true to show, false to hide
 414    */
 415   void SetPopupActive( bool active );
 416
 417   /**
 418    * @brief Query whether the Selection Popup is active.
 419    *
 420    * @return True if the Selection Popup should be active.
 421    */
 422   bool IsPopupActive() const;
 423
 424   /**
 425    * @brief Set a bit mask of the buttons to be shown by Popup
 426    * @param[in] enabledButtonsBitMask from TextSelectionPopup::Buttons enum
 427    */
 428   void SetEnabledPopupButtons( TextSelectionPopup::Buttons& enabledButtonsBitMask );
 429
 430   /**
 431    * @brief Get the current bit mask of buttons to be shown by Popup
 432    * @return bitmask of TextSelectionPopup::Buttons
 433    */
 434   TextSelectionPopup::Buttons& GetEnabledPopupButtons();
 435
 436   /**
 437    * @brief Sets the scroll threshold.
 438    *
 439    * It defines a square area inside the control, close to the edge.
 440    * When the cursor enters this area, the decorator starts to send scroll events.
 441    *
 442    * @param[in] threshold The scroll threshold.
 443    */
 444   void SetScrollThreshold( float threshold );
 445
 446   /**
 447    * @brief Retrieves the scroll threshold.
 448    *
 449    * @retunr The scroll threshold.
 450    */
 451   float GetScrollThreshold() const;
 452
 453   /**
 454    * @brief Sets the scroll speed.
 455    *
 456    * Is the distance the text is going to be scrolled during a scroll interval.
 457    *
 458    * @param[in] speed The scroll speed.
 459    */
 460   void SetScrollSpeed( float speed );
 461
 462   /**
 463    * @brief Retrieves the scroll speed.
 464    *
 465    * @return The scroll speed.
 466    */
 467   float GetScrollSpeed() const;
 468
 469   /**
 470    * @brief Notifies the decorator the whole text has been scrolled.
 471    */
 472   void NotifyEndOfScroll();
 473
 474 protected:
 475
 476   /**
 477    * @brief A reference counted object may only be deleted by calling Unreference().
 478    */
 479   virtual ~Decorator();
 480
 481 private:
 482
 483   /**
 484    * @brief Private constructor.
 485    * @param[in] controller The controller which receives input events from Decorator components.
 486    * @param[in] callbackInterface The text popup callback interface which receives the button click callbacks.
 487    */
 488   Decorator( ControllerInterface& controller,
 489              TextSelectionPopupCallbackInterface& callbackInterface );
 490
 491   // Undefined
 492   Decorator( const Decorator& handle );
 493
 494   // Undefined
 495   Decorator& operator=( const Decorator& handle );
 496
 497 private:
 498
 499   struct Impl;
 500   Impl* mImpl;
 501 };
 502 } // namespace Text
 503
 504 } // namespace Toolkit
 505
 506 } // namespace Dali
 507
 508 #endif // __DALI_TOOLKIT_TEXT_DECORATOR_H__