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

   1 #ifndef __DALI_TOOLKIT_CONTROL_H__
   2 #define __DALI_TOOLKIT_CONTROL_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/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  * @addtogroup dali_toolkit_controls
  45  * @{
  46  */
  47
  48 /**
  49  * @brief Control is the base class for all controls.
  50  *
  51  * The implementation of the control must be supplied; see Internal::Control for more details.
  52  * @SINCE_1_0.0
  53  * @see Internal::Control
  54  *
  55  * Signals
  56  * | %Signal Name           | Method                                              |
  57  * |------------------------|-----------------------------------------------------|
  58  * | keyEvent               | @ref KeyEventSignal()                               |
  59  * | keyInputFocusGained    | @ref KeyInputFocusGainedSignal()                    |
  60  * | keyInputFocusLost      | @ref KeyInputFocusLostSignal()                      |
  61  * | tapped                 | @ref GetTapGestureDetector().DetectedSignal()       |
  62  * | panned                 | @ref GetPanGestureDetector().DetectedSignal()       |
  63  * | pinched                | @ref GetPinchGestureDetector().DetectedSignal()     |
  64  * | longPressed            | @ref GetLongPressGestureDetector().DetectedSignal() |
  65  *
  66  * Actions
  67  * | %Action Name           | %Control method called                             |
  68  * |------------------------|----------------------------------------------------|
  69  * | accessibilityActivated | %OnAccessibilityActivated()                        |
  70  */
  71 class DALI_IMPORT_API Control : public CustomActor
  72 {
  73 public:
  74
  75   /**
  76    * @brief The start and end property ranges for control.
  77    * @SINCE_1_0.0
  78    */
  79   enum PropertyRange
  80   {
  81     PROPERTY_START_INDEX = PROPERTY_REGISTRATION_START_INDEX,        ///< Start index is used by the property registration macro. @SINCE_1_0.0
  82     CONTROL_PROPERTY_START_INDEX = PROPERTY_START_INDEX,             ///< Start index of Control properties. @SINCE_1_0.0
  83     CONTROL_PROPERTY_END_INDEX = CONTROL_PROPERTY_START_INDEX + 1000 ///< Reserving 1000 property indices. @SINCE_1_0.0
  84   };
  85
  86   /**
  87    * @brief An enumeration of properties belonging to the Control class.
  88    * @SINCE_1_0.0
  89    */
  90   struct Property
  91   {
  92     /**
  93      * @brief An enumeration of properties belonging to the Control class.
  94      * @SINCE_1_0.0
  95      */
  96     enum
  97     {
  98       /**
  99        * @brief name "styleName", type std::string
 100        * @SINCE_1_0.0
 101        * @see SetStyleName
 102        */
 103       STYLE_NAME = PROPERTY_START_INDEX,
 104       /**
 105        * @DEPRECATED_1_1.3
 106        * @brief name "background-color", mutually exclusive with BACKGROUND_IMAGE & BACKGROUND,  type Vector4
 107        * @SINCE_1_0.0
 108        * @see SetStyleName
 109        */
 110       BACKGROUND_COLOR,
 111       /**
 112        * @DEPRECATED_1_1.3
 113        * @brief name "background-image", mutually exclusive with BACKGROUND_COLOR & BACKGROUND,  type Map
 114        * @SINCE_1_0.0
 115        */
 116       BACKGROUND_IMAGE,
 117       /**
 118        * @brief name "keyInputFocus", type bool
 119        * @SINCE_1_0.0
 120        * @see SetKeyInputFocus
 121        */
 122       KEY_INPUT_FOCUS,
 123       /**
 124        * @brief name "background", mutually exclusive with BACKGROUND_COLOR & BACKGROUND_IMAGE, type Map or std::string for URL
 125        * @SINCE_1_1.3
 126        */
 127       BACKGROUND,
 128     };
 129   };
 130
 131   /**
 132    * @brief Describes the direction to move the keyboard focus towards.
 133    * @SINCE_1_0.0
 134    */
 135   struct KeyboardFocus
 136   {
 137     /**
 138      * @brief Keyboard focus direction
 139      * @SINCE_1_0.0
 140      */
 141     enum Direction
 142     {
 143       LEFT,   ///< Move keyboard focus towards the left direction @SINCE_1_0.0
 144       RIGHT,  ///< Move keyboard focus towards the right direction @SINCE_1_0.0
 145       UP,     ///< Move keyboard focus towards the up direction @SINCE_1_0.0
 146       DOWN    ///< Move keyboard focus towards the down direction @SINCE_1_0.0
 147     };
 148   };
 149
 150   // Typedefs
 151
 152   /// @brief Key Event signal type;
 153   typedef Signal<bool ( Control, const KeyEvent& ) > KeyEventSignalType;
 154
 155   /// @brief Key InputFocusType signal type;
 156   typedef Signal<void ( Control ) > KeyInputFocusSignalType;
 157
 158 public: // Creation & Destruction
 159
 160   /**
 161    * @brief Create a new instance of a Control.
 162    *
 163    * @SINCE_1_0.0
 164    * @return A handle to a new Control.
 165    */
 166   static Control New();
 167
 168   /**
 169    * @brief Create an uninitialized Control handle.
 170    *
 171    * Only derived versions can be instantiated.  Calling member
 172    * functions with an uninitialized Dali::Object is not allowed.
 173    * @SINCE_1_0.0
 174    */
 175   Control();
 176
 177   /**
 178    * @brief Copy constructor.
 179    *
 180    * Creates another handle that points to the same real object.
 181    * @SINCE_1_0.0
 182    * @param[in] uiControl Handle to copy
 183    */
 184   Control(const Control& uiControl);
 185
 186   /**
 187    * @brief Dali::Control is intended as a base class.
 188    *
 189    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 190    * @SINCE_1_0.0
 191    */
 192   ~Control();
 193
 194 public: // operators
 195
 196   /**
 197    * @brief Assignment operator.
 198    *
 199    * Changes this handle to point to another real object.
 200    * @SINCE_1_0.0
 201    * @param[in] handle Object to assign this to
 202    * @return reference to this
 203    */
 204   Control& operator=( const Control& handle );
 205
 206 public:
 207
 208   /**
 209    * @brief Downcast a handle to Control handle.
 210    *
 211    * If handle points to a Control the downcast produces valid
 212    * handle. If not the returned handle is left uninitialized.
 213    *
 214    * @SINCE_1_0.0
 215    * @param[in] handle Handle to an object
 216    * @return A handle to a Control or an uninitialized handle
 217    */
 218   static Control DownCast( BaseHandle handle );
 219
 220   // Key Input
 221
 222   /**
 223    * @brief This sets the control to receive key events.
 224    *
 225    * The key event can originate from a virtual or physical keyboard.
 226    * @SINCE_1_0.0
 227    * @pre The Control has been initialized.
 228    * @pre The Control should be on the stage before setting keyboard focus.
 229    */
 230   void SetKeyInputFocus();
 231
 232   /**
 233    * @brief Quries whether the control has key input focus.
 234    *
 235    * @SINCE_1_0.0
 236    * @return true if this control has keyboard input focus
 237    * @pre The Control has been initialized.
 238    * @pre The Control should be on the stage before setting keyboard focus.
 239    * @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.
 240    * As the key input focus mechanism works like a stack, the top most control receives all the key events, and passes on the
 241    * unhandled events to the controls below in the stack. A control in the stack will regain key input focus when there are no more
 242    * controls above it in the focus stack.
 243    * To query for the conrol which is on top of the focus stack use Dali::Toolkit::KeyInputFocusManager::GetCurrentKeyboardFocusActor().
 244    */
 245   bool HasKeyInputFocus();
 246
 247   /**
 248    * @brief Once an actor is Set to receive key input focus this function is called to stop it receiving key events.
 249    *
 250    * A check is performed to ensure it was previously set, if this check fails then nothing is done.
 251    * @SINCE_1_0.0
 252    * @pre The Actor has been initialized.
 253    */
 254   void ClearKeyInputFocus();
 255
 256   // Gesture Detection
 257
 258   /**
 259    * @brief Retrieves the pinch gesture detector of the control.
 260    *
 261    * @SINCE_1_0.0
 262    * @return The pinch gesture detector.
 263    * @note Will return an empty handle if the control does not handle the gesture itself.
 264    */
 265   PinchGestureDetector GetPinchGestureDetector() const;
 266
 267   /**
 268    * @brief Retrieves the pan gesture detector of the control.
 269    *
 270    * @SINCE_1_0.0
 271    * @return The pan gesture detector.
 272    * @note Will return an empty handle if the control does not handle the gesture itself.
 273    */
 274   PanGestureDetector GetPanGestureDetector() const;
 275
 276   /**
 277    * @brief Retrieves the tap gesture detector of the control.
 278    *
 279    * @SINCE_1_0.0
 280    * @return The tap gesture detector.
 281    * @note Will return an empty handle if the control does not handle the gesture itself.
 282    */
 283   TapGestureDetector GetTapGestureDetector() const;
 284
 285   /**
 286    * @brief Retrieves the long press gesture detector of the control.
 287    *
 288    * @SINCE_1_0.0
 289    * @return The long press gesture detector.
 290    * @note Will return an empty handle if the control does not handle the gesture itself.
 291    */
 292   LongPressGestureDetector GetLongPressGestureDetector() const;
 293
 294   // Styling
 295
 296   /**
 297    * @brief Sets the name of the style to be applied to the control.
 298    *
 299    * @SINCE_1_0.0
 300    * @param[in] styleName A string matching a style described in a stylesheet.
 301    */
 302   void SetStyleName( const std::string& styleName );
 303
 304   /**
 305    * @brief Retrieves the name of the style to be applied to the control (if any).
 306    * @SINCE_1_0.0
 307    * @return A string matching a style or an empty string.
 308    */
 309   const std::string& GetStyleName() const;
 310
 311   // Background
 312
 313   /**
 314    * @brief Sets the background color of the control.
 315    *
 316    * @SINCE_1_0.0
 317    * @param[in] color The required background color of the control
 318    *
 319    * @note if SetBackgroundImage is called later, this background color is removed.
 320    *
 321    * @note The background color fully blends with the actor color.
 322    */
 323   void SetBackgroundColor( const Vector4& color );
 324
 325   /**
 326    * @DEPRECATED_1_1.3
 327    *
 328    * @brief Retrieves the background color of the control.
 329    *
 330    * @SINCE_1_0.0
 331    * @return The background color of the control.
 332    */
 333   Vector4 GetBackgroundColor() const;
 334
 335   /**
 336    * @DEPRECATED_1_2_8, use Property::BACKGROUND instead
 337    *
 338    * @brief Sets an image as the background of the control.
 339    *
 340    * @SINCE_1_0.0
 341    * @param[in] image The image to set as the background.
 342    */
 343   void SetBackgroundImage( Image image );
 344
 345   /**
 346    * @brief Clears the background.
 347    * @SINCE_1_0.0
 348    */
 349   void ClearBackground();
 350
 351   // Signals
 352
 353   /**
 354    * @brief This signal is emitted when key event is received.
 355    *
 356    * A callback of the following type may be connected:
 357    * @code
 358    *   bool YourCallbackName(Control control, const KeyEvent& event);
 359    * @endcode
 360    * The return value of True, indicates that the event should be consumed.
 361    * Otherwise the signal will be emitted on the next parent of the actor.
 362    * @SINCE_1_0.0
 363    * @return The signal to connect to.
 364    * @pre The Control has been initialized.
 365    */
 366   KeyEventSignalType& KeyEventSignal();
 367
 368   /**
 369    * @brief This signal is emitted when the control gets Key Input Focus.
 370    *
 371    * A callback of the following type may be connected:
 372    * @code
 373    *   bool YourCallbackName( Control control );
 374    * @endcode
 375    * The return value of True, indicates that the event should be consumed.
 376    * Otherwise the signal will be emitted on the next parent of the actor.
 377    * @SINCE_1_0.0
 378    * @return The signal to connect to.
 379    * @pre The Control has been initialized.
 380    */
 381   KeyInputFocusSignalType& KeyInputFocusGainedSignal();
 382
 383   /**
 384    * @brief This signal is emitted when the control loses Key Input Focus
 385    * which could be due to it being gained by another Control or Actor or just cleared from
 386    * this control as no longer required.
 387    *
 388    * A callback of the following type may be connected:
 389    * @code
 390    *   bool YourCallbackName( Control control );
 391    * @endcode
 392    * The return value of True, indicates that the event should be consumed.
 393    * Otherwise the signal will be emitted on the next parent of the actor.
 394    * @SINCE_1_0.0
 395    * @return The signal to connect to.
 396    * @pre The Control has been initialized.
 397    */
 398   KeyInputFocusSignalType& KeyInputFocusLostSignal();
 399
 400 public: // Intended for control developers
 401
 402   /**
 403    * @brief Create an initialised Control.
 404    *
 405    * @SINCE_1_0.0
 406    * @param[in] implementation The implementation for this control.
 407    * @return A handle to a newly allocated Dali resource.
 408    *
 409    * @note Should NOT be called to create a handle from the implementation. As stated, this allocates a NEW Dali resource.
 410    */
 411   explicit Control(Internal::Control& implementation);
 412
 413   /**
 414    * @brief This constructor is used by CustomActor within Dali core to create additional Control handles
 415    * using an Internal CustomActor pointer.
 416    *
 417    * @SINCE_1_0.0
 418    * @param [in] internal A pointer to a newly allocated Dali resource
 419    */
 420   explicit Control(Dali::Internal::CustomActor* internal);
 421
 422 public: // Templates for Deriving Classes
 423
 424   /**
 425    * @brief Template to allow deriving controls to DownCast handles to deriving handle classes.
 426    *
 427    * @tparam     T       The handle class
 428    * @tparam     I       The implementation class
 429    * @SINCE_1_0.0
 430    * @param[in]  handle  Handle to an object
 431    * @return Handle to a class T or an uninitialized handle.
 432    * @see DownCast(BaseHandle)
 433    */
 434   template<typename T, typename I>
 435   DALI_INTERNAL static T DownCast( BaseHandle handle )
 436   {
 437     T result;
 438
 439     CustomActor custom = Dali::CustomActor::DownCast( handle );
 440     if ( custom )
 441     {
 442       CustomActorImpl& customImpl = custom.GetImplementation();
 443
 444       I* impl = dynamic_cast<I*>(&customImpl);
 445
 446       if (impl)
 447       {
 448         result = T(customImpl.GetOwner());
 449       }
 450     }
 451
 452     return result;
 453   }
 454
 455   /**
 456    * @brief Template to allow deriving controls to verify whether the Internal::CustomActor* is actually an
 457    * implementation of their class.
 458    *
 459    * @tparam     I         The implementation class
 460    * @SINCE_1_0.0
 461    * @param[in]  internal  Pointer to the Internal::CustomActor
 462    */
 463   template<typename I>
 464   DALI_INTERNAL void VerifyCustomActorPointer(Dali::Internal::CustomActor* internal)
 465   {
 466     // Can have a NULL pointer so we only need to check if the internal implementation is our class
 467     // when there is a value.
 468     if (internal)
 469     {
 470       DALI_ASSERT_DEBUG(dynamic_cast<I*>(&CustomActor(internal).GetImplementation()));
 471     }
 472   }
 473
 474 };
 475
 476 /**
 477  * @}
 478  */
 479 } // namespace Toolkit
 480
 481 } // namespace Dali
 482
 483 #endif // __DALI_TOOLKIT_CONTROL_H__