dali-toolkit/public-api/controls/control.h

   1 #ifndef __DALI_TOOLKIT_CONTROL_H__
   2 #define __DALI_TOOLKIT_CONTROL_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/custom-actor.h>
  23 #include <dali/public-api/common/dali-common.h>
  24 #include <dali/public-api/events/long-press-gesture-detector.h>
  25 #include <dali/public-api/events/pan-gesture-detector.h>
  26 #include <dali/public-api/events/pinch-gesture-detector.h>
  27 #include <dali/public-api/events/tap-gesture-detector.h>
  28 #include <dali/public-api/events/tap-gesture-detector.h>
  29 #include <dali/public-api/images/image.h>
  30
  31 namespace Dali
  32 {
  33
  34 namespace Toolkit
  35 {
  36
  37 //Forward declarations.
  38
  39 namespace Internal
  40 {
  41 class Control;
  42 }
  43
  44 /**
  45  * @brief Control is the base class for all controls.
  46  *
  47  * The implementation of the control must be supplied; see Internal::Control for more details.
  48  * @see Internal::Control
  49  *
  50  * Signals
  51  * | %Signal Name      | Method                                              |
  52  * |-------------------|-----------------------------------------------------|
  53  * | key-event         | @ref KeyEventSignal()                               |
  54  * | tapped            | @ref GetTapGestureDetector().DetectedSignal()       |
  55  * | panned            | @ref GetPanGestureDetector().DetectedSignal()       |
  56  * | pinched           | @ref GetPinchGestureDetector().DetectedSignal()     |
  57  * | long-pressed      | @ref GetLongPressGestureDetector().DetectedSignal() |
  58  *
  59  * Actions
  60  * | %Action Name      | %Control method called                              |
  61  * |-------------------|-----------------------------------------------------|
  62  * | control-activated | %OnActivated()                                      |
  63  */
  64 class DALI_IMPORT_API Control : public CustomActor
  65 {
  66 public:
  67
  68   /// @name Properties
  69   /** @{ */
  70   static const Property::Index PROPERTY_BACKGROUND_COLOR;    ///< name "background-color",        @see SetBackgroundColor,        type VECTOR4
  71   static const Property::Index PROPERTY_BACKGROUND;          ///< name "background",              @see SetBackground,             type MAP
  72   static const Property::Index PROPERTY_WIDTH_POLICY;        ///< name "width-policy",            @see SetSizePolicy,             type STRING
  73   static const Property::Index PROPERTY_HEIGHT_POLICY;       ///< name "height-policy",           @see SetSizePolicy,             type STRING
  74   static const Property::Index PROPERTY_MINIMUM_SIZE;        ///< name "minimum-size",            @see SetMinimumSize,            type VECTOR3
  75   static const Property::Index PROPERTY_MAXIMUM_SIZE;        ///< name "maximum-size",            @see SetMaximumSize,            type VECTOR3
  76   static const Property::Index PROPERTY_KEY_INPUT_FOCUS;     ///< name "key-input-focus",         @see SetKeyInputFocus,          type BOOLEAN
  77   /** @} */
  78
  79   /**
  80    * @brief Describes how a control could be resized.
  81    */
  82   enum SizePolicy
  83   {
  84     Fixed,    ///< Size can't grow or shrink.
  85     Minimum,  ///< Size can grow but shrink up to a minimum level.
  86     Maximum,  ///< Size can shrink but grow up to a maximum value.
  87     Range,    ///< Size can grow or shrink between a minimum and a maximum values.
  88     Flexible, ///< Size can grow or shrink with no limits.
  89   };
  90
  91   /**
  92    * @brief Describes what a control should do when a contained actor/control exceeds the boundary of the control.
  93    */
  94   enum ExceedPolicy
  95   {
  96     Crop,   ///< Control's contents will be cropped.
  97     Shrink, ///< Control's contents will be shrunk.
  98     Scroll  ///< Control's contents will be added to a scroll.
  99   };
 100
 101   /**
 102    * @brief Describes the direction to move the keyboard focus towards.
 103    */
 104   enum KeyboardFocusNavigationDirection
 105   {
 106     Left,   ///< Move keyboard focus towards the left direction
 107     Right,  ///< Move keyboard focus towards the right direction
 108     Up,     ///< Move keyboard focus towards the up direction
 109     Down    ///< Move keyboard focus towards the down direction
 110   };
 111
 112   // Typedefs
 113
 114   /// @brief Key Event signal type;
 115   typedef Signal<bool ( Control, const KeyEvent& ) > KeyEventSignalType;
 116
 117 public: // Creation & Destruction
 118
 119   /**
 120    * @brief Create a new instance of a Control.
 121    *
 122    * @return A handle to a new Control.
 123    */
 124   static Control New();
 125
 126   /**
 127    * @brief Create an uninitialized Control handle.
 128    *
 129    * Only derived versions can be instantiated.  Calling member
 130    * functions with an uninitialized Dali::Object is not allowed.
 131    */
 132   Control();
 133
 134   /**
 135    * @brief Copy constructor.
 136    *
 137    * Creates another handle that points to the same real object
 138    * @param[in] uiControl Handle to copy
 139    */
 140   Control(const Control& uiControl);
 141
 142   /**
 143    * @brief Dali::Control is intended as a base class
 144    *
 145    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 146    */
 147   ~Control();
 148
 149 public: // operators
 150
 151   /**
 152    * @brief Assignment operator.
 153    *
 154    * Changes this handle to point to another real object
 155    * @param[in] handle Object to assign this to
 156    * @return reference to this
 157    */
 158   Control& operator=( const Control& handle );
 159
 160 public:
 161
 162   /**
 163    * @brief Downcast an Object handle to Control.
 164    *
 165    * If handle points to a Control the downcast produces valid
 166    * handle. If not the returned handle is left uninitialized.
 167    *
 168    * @param[in] handle Handle to an object
 169    * @return handle to a Control or an uninitialized handle
 170    */
 171   static Control DownCast( BaseHandle handle );
 172
 173   /**
 174    * @brief Retrieve the Control implementation.
 175    *
 176    * @return The implementation.
 177    */
 178   Internal::Control& GetImplementation();
 179
 180   /**
 181    * @brief Retrieve the Control implementation.
 182    *
 183    * @return The implementation.
 184    */
 185   const Internal::Control& GetImplementation() const;
 186
 187   // Size Negotiation
 188
 189   /**
 190    * @brief Sets the size policies for the width and height dimensions.
 191    *
 192    * @param[in] widthPolicy Size policy for the width dimension.
 193    * @param[in] heightPolicy Size policy for the height dimension.
 194    */
 195   void SetSizePolicy( SizePolicy widthPolicy, SizePolicy heightPolicy );
 196
 197   /**
 198    * @brief Retrieves the size policies for the width and height dimensions.
 199    *
 200    * @param[out] widthPolicy Width's size policy.
 201    * @param[out] heightPolicy Height's size policy.
 202    */
 203   void GetSizePolicy( SizePolicy& widthPolicy, SizePolicy& heightPolicy ) const;
 204
 205   /**
 206    * @brief Sets the minimum size for the control.
 207    *
 208    * @param[in] size The minimum size.
 209    */
 210   void SetMinimumSize( const Vector3& size );
 211
 212   /**
 213    * @brief Retrieves the minimum size.
 214    *
 215    * @return The minimum size.
 216    */
 217   const Vector3& GetMinimumSize() const;
 218
 219   /**
 220    * @brief Sets the maximum size.
 221    *
 222    * @param[in] size The maximum size.
 223    */
 224   void SetMaximumSize( const Vector3& size );
 225
 226   /**
 227    * @brief Retrieves the maximum size.
 228    *
 229    * @return The maximum size.
 230    */
 231   const Vector3& GetMaximumSize() const;
 232
 233   /**
 234    * @brief Works out the natural size.
 235    *
 236    * Natural size is the control's size with any restriction.
 237    *
 238    * @return The natural size.
 239    */
 240   Vector3 GetNaturalSize();
 241
 242   /**
 243    * @brief Works out the control's height for a given width.
 244    *
 245    * @param[in] width The control's width.
 246    *
 247    * @return The control's height for the given width.
 248    */
 249   float GetHeightForWidth( float width );
 250
 251   /**
 252    * @brief Works out the control's width for a given height.
 253    *
 254    * @param[in] height The control's height.
 255    *
 256    * @return The control's width for the given height.
 257    */
 258   float GetWidthForHeight( float height );
 259
 260   // Key Input
 261
 262   /**
 263    * @brief This sets the control to receive key events.
 264    *
 265    * The key event can originate from a virtual or physical keyboard.
 266    * @pre The Control has been initialized.
 267    * @pre The Control should be on the stage before setting keyboard focus.
 268    * @return True if the control has foucs, False otherwise.
 269    */
 270   void SetKeyInputFocus();
 271
 272   /**
 273    * @brief Quries whether the control has key input focus.
 274    *
 275    * Note: The control can be set to have the focus and still not receive all the key events if another control has over ridden it.
 276    * As the key input focus mechanism works like a stack, the top most control receives all the key events, and passes on the
 277    * unhandled events to the controls below in the stack. A control in the stack will regain key input focus when there are no more
 278    * controls above it in the focus stack.
 279    * To query for the conrol which is on top of the focus stack use Dali::Toolkit::KeyInputFocusManager::GetCurrentKeyboardFocusActor()
 280    * @pre The Control has been initialized.
 281    * @pre The Control should be on the stage before setting keyboard focus.
 282    * @return true if this control has keyboard input focus
 283    */
 284   bool HasKeyInputFocus();
 285
 286   /**
 287    * @brief Once an actor is Set to receive key input focus this function is called to stop it receiving key events.
 288    *
 289    * A check is performed to ensure it was previously set, if this check fails then nothing is done.
 290    * @pre The Actor has been initialized.
 291    */
 292   void ClearKeyInputFocus();
 293
 294   // Gesture Detection
 295
 296   /**
 297    * @brief Retrieves the pinch gesture detector of the control.
 298    *
 299    * @return The pinch gesture detector.
 300    * @note Will return an empty handle if the control does not handle the gesture itself.
 301    */
 302   PinchGestureDetector GetPinchGestureDetector() const;
 303
 304   /**
 305    * @brief Retrieves the pan gesture detector of the control.
 306    *
 307    * @return The pan gesture detector.
 308    * @note Will return an empty handle if the control does not handle the gesture itself.
 309    */
 310   PanGestureDetector GetPanGestureDetector() const;
 311
 312   /**
 313    * @brief Retrieves the tap gesture detector of the control.
 314    *
 315    * @return The tap gesture detector.
 316    * @note Will return an empty handle if the control does not handle the gesture itself.
 317    */
 318   TapGestureDetector GetTapGestureDetector() const;
 319
 320   /**
 321    * @brief Retrieves the long press gesture detector of the control.
 322    *
 323    * @return The long press gesture detector.
 324    * @note Will return an empty handle if the control does not handle the gesture itself.
 325    */
 326   LongPressGestureDetector GetLongPressGestureDetector() const;
 327
 328   // Background
 329
 330   /**
 331    * @brief Sets the background color of the control.
 332    *
 333    * @param[in] color The required background color of the control
 334    *
 335    * @note The background color fully blends with the actor color.
 336    */
 337   void SetBackgroundColor( const Vector4& color );
 338
 339   /**
 340    * @brief Retrieves the background color of the control.
 341    *
 342    * @return The background color of the control.
 343    */
 344   Vector4 GetBackgroundColor() const;
 345
 346   /**
 347    * @brief Sets an image as the background of the control.
 348    *
 349    * The color of this image is blended with the background color @see SetBackgroundColor
 350    *
 351    * @param[in] image The image to set as the background.
 352    */
 353   void SetBackground( Image image );
 354
 355   /**
 356    * @brief Clears the background.
 357    */
 358   void ClearBackground();
 359
 360   /**
 361    * @brief Retrieves the actor used as the background for this control.
 362    *
 363    * @return The actor that used as the background for this control.
 364    */
 365   Actor GetBackgroundActor() const;
 366
 367   // Signals
 368
 369   /**
 370    * @brief This signal is emitted when key event is received.
 371    *
 372    * A callback of the following type may be connected:
 373    * @code
 374    *   bool YourCallbackName(Control control, const KeyEvent& event);
 375    * @endcode
 376    * The return value of True, indicates that the touch event should be consumed.
 377    * Otherwise the signal will be emitted on the next sensitive parent of the actor.
 378    * @pre The Control has been initialized.
 379    * @return The signal to connect to.
 380    */
 381   KeyEventSignalType& KeyEventSignal();
 382
 383 public: // Intended for control developers
 384
 385   /**
 386    * @brief Create an initialised Control.
 387    *
 388    * @param[in] implementation The implementation for this control.
 389    * @return A handle to a newly allocated Dali resource.
 390    *
 391    * @note Should NOT be called to create a handle from the implementation. As stated, this allocates a NEW Dali resource.
 392    */
 393   explicit Control(Internal::Control& implementation);
 394
 395   /**
 396    * @brief This constructor is used by CustomActor within Dali core to create additional Control handles
 397    * using an Internal CustomActor pointer.
 398    *
 399    * @param [in] internal A pointer to a newly allocated Dali resource
 400    */
 401   explicit Control(Dali::Internal::CustomActor* internal);
 402
 403 public: // Templates for Deriving Classes
 404
 405   /**
 406    * @brief Template to allow deriving controls to DownCast handles to deriving handle classes.
 407    *
 408    * @tparam     T       The handle class
 409    * @tparam     I       The implementation class
 410    * @param[in]  handle  Handle to an object
 411    * @return Handle to a class T or an uninitialized handle.
 412    * @see DownCast(BaseHandle)
 413    */
 414   template<typename T, typename I>
 415   DALI_INTERNAL static T DownCast( BaseHandle handle )
 416   {
 417     T result;
 418
 419     CustomActor custom = Dali::CustomActor::DownCast( handle );
 420     if ( custom )
 421     {
 422       CustomActorImpl& customImpl = custom.GetImplementation();
 423
 424       I* impl = dynamic_cast<I*>(&customImpl);
 425
 426       if (impl)
 427       {
 428         result = T(customImpl.GetOwner());
 429       }
 430     }
 431
 432     return result;
 433   }
 434
 435   /**
 436    * @brief Template to allow deriving controls to verify whether the Internal::CustomActor* is actually an
 437    * implementation of their class.
 438    *
 439    * @tparam     I         The implementation class
 440    * @param[in]  internal  Pointer to the Internal::CustomActor
 441    */
 442   template<typename I>
 443   DALI_INTERNAL void VerifyCustomActorPointer(Dali::Internal::CustomActor* internal)
 444   {
 445     // Can have a NULL pointer so we only need to check if the internal implementation is our class
 446     // when there is a value.
 447     if (internal)
 448     {
 449       DALI_ASSERT_DEBUG(dynamic_cast<I*>(&CustomActor(internal).GetImplementation()));
 450     }
 451   }
 452
 453 };
 454
 455 } // namespace Toolkit
 456
 457 } // namespace Dali
 458
 459 #endif // __DALI_TOOLKIT_CONTROL_H__