dali-toolkit/public-api/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
  25 namespace Dali
  26 {
  27
  28 class Image;
  29 class Vector2;
  30 class Vector4;
  31
  32 namespace Toolkit
  33 {
  34
  35 namespace Internal
  36 {
  37 class Control;
  38 }
  39
  40 namespace Text
  41 {
  42
  43 class Decorator;
  44 typedef IntrusivePtr<Decorator> DecoratorPtr;
  45
  46 // Used to set the cursor positions etc.
  47 enum Cursor
  48 {
  49   PRIMARY_CURSOR,   ///< The primary cursor for bidirectional text (or the regular cursor for single-direction text)
  50   SECONDARY_CURSOR, ///< The secondary cursor for bidirectional text
  51   CURSOR_COUNT
  52 };
  53
  54 // Determines which of the cursors are active (if any).
  55 enum ActiveCursor
  56 {
  57   ACTIVE_CURSOR_NONE,    ///< Neither primary nor secondary cursor are active
  58   ACTIVE_CURSOR_PRIMARY, ///< Primary cursor is active (only)
  59   ACTIVE_CURSOR_BOTH     ///< Both primary and secondary cursor are active
  60 };
  61
  62 // The state information for grab handle events
  63 enum GrabHandleState
  64 {
  65   GRAB_HANDLE_TAPPED,
  66   GRAB_HANDLE_PRESSED,
  67   GRAB_HANDLE_RELEASED
  68 };
  69
  70 // The set the selection-handle positions etc.
  71 enum SelectionHandle
  72 {
  73   PRIMARY_SELECTION_HANDLE,
  74   SECONDARY_SELECTION_HANDLE,
  75   SELECTION_HANDLE_COUNT
  76 };
  77
  78 enum SelectionHandleState
  79 {
  80   SELECTION_HANDLE_PRESSED,
  81   SELECTION_HANDLE_RELEASED
  82 };
  83
  84 /**
  85  * @brief A Text Decorator is used to display cursors, handles, selection highlights and pop-ups.
  86  *
  87  * The decorator is responsible for clipping decorations which are positioned outside of the parent area.
  88  * In some cases the decorations will be moved or flipped around, to maintain visibility on-screen.
  89  *
  90  * Decorator components forward input events to a controller class through an observer interface.
  91  * The controller is responsible for selecting which components are active.
  92  */
  93 class Decorator : public RefObject
  94 {
  95 public:
  96
  97   class Observer
  98   {
  99   public:
 100
 101     /**
 102      * @brief Constructor.
 103      */
 104     Observer() {};
 105
 106     /**
 107      * @brief Virtual destructor.
 108      */
 109     virtual ~Observer() {};
 110
 111     /**
 112      * @brief An input event from the grab handle.
 113      *
 114      * @param[in] state The grab handle state.
 115      * @param[in] x The x position relative to the top-left of the parent control.
 116      * @param[in] y The y position relative to the top-left of the parent control.
 117      */
 118     virtual void GrabHandleEvent( GrabHandleState state, float x, float y ) = 0;
 119   };
 120
 121   /**
 122    * @brief Create a new instance of a Decorator.
 123    *
 124    * @param[in] parent Decorations will be added to this parent control.
 125    * @param[in] observer A class which receives input events from Decorator components.
 126    * @return A pointer to a new Decorator.
 127    */
 128   static DecoratorPtr New( Dali::Toolkit::Internal::Control& parent, Observer& observer );
 129
 130   /**
 131    * @brief The decorator waits until a relayout before creating actors etc.
 132    *
 133    * @param[in] size The size of the parent control after size-negotiation.
 134    */
 135   void Relayout( const Dali::Vector2& size );
 136
 137   /**
 138    * @brief Sets which of the cursors are active.
 139    *
 140    * @note Cursor will only be visible if within the parent area.
 141    * @param[in] activeCursor Which of the cursors should be active (if any).
 142    */
 143   void SetActiveCursor( ActiveCursor activeCursor );
 144
 145   /**
 146    * @brief Query which of the cursors are active.
 147    *
 148    * @return  Which of the cursors are active (if any).
 149    */
 150   unsigned int GetActiveCursor() const;
 151
 152   /**
 153    * @brief Sets the position of a cursor.
 154    *
 155    * @param[in] cursor The cursor to set.
 156    * @param[in] x The x position relative to the top-left of the parent control.
 157    * @param[in] y The y position relative to the top-left of the parent control.
 158    * @param[in] height The logical height of the cursor.
 159    */
 160   void SetPosition( Cursor cursor, float x, float y, float height );
 161
 162   /**
 163    * @brief Retrieves the position of a cursor.
 164    *
 165    * @param[in] cursor The cursor to get.
 166    * @param[out] x The x position relative to the top-left of the parent control.
 167    * @param[out] y The y position relative to the top-left of the parent control.
 168    * @param[out] height The logical height of the cursor.
 169    */
 170   void GetPosition( Cursor cursor, float& x, float& y, float& height ) const;
 171
 172   /**
 173    * @brief Sets the image for a cursor.
 174    *
 175    * @param[in] image The image to use.
 176    */
 177   void SetCursorImage( Dali::Image image );
 178
 179   /**
 180    * @brief Retrieves the image for a cursor.
 181    *
 182    * @return The cursor image.
 183    */
 184   Dali::Image GetCursorImage() const;
 185
 186   /**
 187    * @brief Sets the color for a cursor.
 188    *
 189    * @param[in] cursor Whether this color is for the primary or secondary cursor.
 190    * @param[in] color The color to use.
 191    */
 192   void SetColor( Cursor cursor, const Dali::Vector4& color );
 193
 194   /**
 195    * @brief Retrieves the color for a cursor.
 196    *
 197    * @param[in] cursor Whether this color is for the primary or secondary cursor.
 198    * @return The cursor color.
 199    */
 200   const Dali::Vector4& GetColor( Cursor cursor ) const;
 201
 202   /**
 203    * @brief Start blinking the cursor; see also SetCursorBlinkDuration().
 204    */
 205   void StartCursorBlink();
 206
 207   /**
 208    * @brief Stop blinking the cursor.
 209    */
 210   void StopCursorBlink();
 211
 212   /**
 213    * @brief Set the interval between cursor blinks.
 214    *
 215    * @param[in] seconds The interval in seconds.
 216    */
 217   void SetCursorBlinkInterval( float seconds );
 218
 219   /**
 220    * @brief Retrieves the blink-interval for a cursor.
 221    *
 222    * @return The cursor blink-interval.
 223    */
 224   float GetCursorBlinkInterval() const;
 225
 226   /**
 227    * @brief The cursor will stop blinking after this duration.
 228    *
 229    * @param[in] seconds The duration in seconds.
 230    */
 231   void SetCursorBlinkDuration( float seconds );
 232
 233   /**
 234    * @brief Retrieves the blink-duration for a cursor.
 235    *
 236    * @return The cursor blink-duration.
 237    */
 238   float GetCursorBlinkDuration() const;
 239
 240   /**
 241    * @brief Sets whether the grab handle is active.
 242    *
 243    * @note The grab handle follows the cursor position set with SetPosition(Cursor, ...)
 244    * @param[in] active True if the grab handle should be active.
 245    */
 246   void SetGrabHandleActive( bool active );
 247
 248   /**
 249    * @brief Query whether the grab handle is active.
 250    *
 251    * @return True if the grab handle should be active.
 252    */
 253   bool IsGrabHandleActive() const;
 254
 255   /**
 256    * @brief Sets the image for the grab handle.
 257    *
 258    * @param[in] image The image to use.
 259    */
 260   void SetGrabHandleImage( Dali::Image image );
 261
 262   /**
 263    * @brief Retrieves the image for the grab handle.
 264    *
 265    * @return The grab handle image.
 266    */
 267   Dali::Image GetGrabHandleImage() const;
 268
 269   /**
 270    * @brief Sets whether the selection handles and highlight are active.
 271    *
 272    * @param[in] active True if the selection handles and highlight are active.
 273    */
 274   void SetSelectionActive( bool active );
 275
 276   /**
 277    * @brief Query whether the selection handles and highlight are active.
 278    *
 279    * @return True if the selection handles and highlight are active.
 280    */
 281   bool IsSelectionActive() const;
 282
 283   /**
 284    * @brief Sets the position of a selection handle.
 285    *
 286    * @param[in] handle The handle to set.
 287    * @param[in] x The x position relative to the top-left of the parent control.
 288    * @param[in] y The y position relative to the top-left of the parent control.
 289    * @param[in] cursorHeight The logical cursor height at this position.
 290    */
 291   void SetPosition( SelectionHandle handle, float x, float y, float cursorHeight );
 292
 293   /**
 294    * @brief Retrieves the position of a selection handle.
 295    *
 296    * @param[in] handle The handle to get.
 297    * @param[out] x The x position relative to the top-left of the parent control.
 298    * @param[out] y The y position relative to the top-left of the parent control.
 299    * @param[out] cursorHeight The logical cursor height at this position.
 300    */
 301   void GetPosition( SelectionHandle handle, float& x, float& y, float& cursorHeight ) const;
 302
 303   /**
 304    * @brief Sets the image for one of the selection handles.
 305    *
 306    * @param[in] handle The selection handle.
 307    * @param[in] state A different image can be set for the pressed/released states.
 308    * @param[in] image The image to use.
 309    */
 310   void SetImage( SelectionHandle handle, SelectionHandleState state, Dali::Image image );
 311
 312   /**
 313    * @brief Retrieves the image for a selection handle.
 314    *
 315    * @param[in] handle The selection handle.
 316    * @param[in] state A different image can be set for the pressed/released states.
 317    * @return The image.
 318    */
 319   Dali::Image GetImage( SelectionHandle handle, SelectionHandleState state ) const;
 320
 321 protected:
 322
 323   /**
 324    * @brief A reference counted object may only be deleted by calling Unreference().
 325    */
 326   virtual ~Decorator();
 327
 328 private:
 329
 330   /**
 331    * @brief Private constructor.
 332    * @param[in] parent Decorations will be added to this parent control.
 333    * @param[in] observer A class which receives input events from Decorator components.
 334    */
 335   Decorator(Dali::Toolkit::Internal::Control& parent, Observer& observer );
 336
 337   // Undefined
 338   Decorator( const Decorator& handle );
 339
 340   // Undefined
 341   Decorator& operator=( const Decorator& handle );
 342
 343 private:
 344
 345   struct Impl;
 346   Impl* mImpl;
 347 };
 348 } // namespace Text
 349
 350 } // namespace Toolkit
 351
 352 } // namespace Dali
 353
 354 #endif // __DALI_TOOLKIT_TEXT_DECORATOR_H__