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