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