capi/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 Flora License, Version 1.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://floralicense.org/license/
  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  * @addtogroup CAPI_DALI_TOOLKIT_CONTROLS_MODULE
  22  * @{
  23  */
  24
  25 // INTERNAL INCLUDES
  26 #include <dali/dali.h>
  27
  28 namespace Dali DALI_IMPORT_API
  29 {
  30
  31 namespace Toolkit
  32 {
  33
  34 //Forward declarations.
  35
  36 namespace Internal
  37 {
  38 class Control;
  39 }
  40
  41 /**
  42  * @brief Control is the base class for all controls.
  43  *
  44  * The implementation of the control must be supplied; see Internal::Control for more details.
  45  * @see Internal::Control
  46  */
  47 class Control : public CustomActor, public ConnectionTrackerInterface
  48 {
  49 public:
  50
  51   /// @name Properties
  52   /** @{ */
  53   static const Property::Index PROPERTY_BACKGROUND_COLOR;    ///< name "background-color",        @see SetBackgroundColor,        type VECTOR4
  54   static const Property::Index PROPERTY_BACKGROUND;          ///< name "background",              @see SetBackground,             type MAP
  55   static const Property::Index PROPERTY_WIDTH_POLICY;        ///< name "width-policy",            @see SetSizePolicy,             type STRING
  56   static const Property::Index PROPERTY_HEIGHT_POLICY;       ///< name "height-policy",           @see SetSizePolicy,             type STRING
  57   static const Property::Index PROPERTY_MINIMUM_SIZE;        ///< name "minimum-size",            @see SetMinimumSize,            type VECTOR3
  58   static const Property::Index PROPERTY_MAXIMUM_SIZE;        ///< name "maximum-size",            @see SetMaximumSize,            type VECTOR3
  59   static const Property::Index PROPERTY_KEY_INPUT_FOCUS;     ///< name "key-input-focus",         @see SetKeyInputFocus,          type BOOLEAN
  60   /** @} */
  61
  62   /// @name Signals
  63   /** @{ */
  64   static const char* const SIGNAL_KEY_EVENT;                 ///< name "key-event"
  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 Virtual destructor.
 137    *
 138    * Dali::Object derived classes do not contain member data.
 139    */
 140   virtual ~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   void SetBackgroundColor( const Vector4& color );
 329
 330   /**
 331    * @brief Retrieves the background color of the control.
 332    *
 333    * @return The background color of the control.
 334    */
 335   Vector4 GetBackgroundColor() const;
 336
 337   /**
 338    * @brief Sets an image as the background of the control.
 339    *
 340    * The color of this image is blended with the background color @see SetBackgroundColor
 341    *
 342    * @param[in] image The image to set as the background.
 343    */
 344   void SetBackground( Image image );
 345
 346   /**
 347    * @brief Clears the background.
 348    */
 349   void ClearBackground();
 350
 351   /**
 352    * @brief Retrieves the actor used as the background for this control.
 353    *
 354    * @return The actor that used as the background for this control.
 355    */
 356   Actor GetBackgroundActor() const;
 357
 358   // Signals
 359
 360   /**
 361    * @brief This signal is emitted when key event is received.
 362    *
 363    * A callback of the following type may be connected:
 364    * @code
 365    *   bool YourCallbackName(Control control, const KeyEvent& event);
 366    * @endcode
 367    * The return value of True, indicates that the touch event should be consumed.
 368    * Otherwise the signal will be emitted on the next sensitive parent of the actor.
 369    * @pre The Control has been initialized.
 370    * @return The signal to connect to.
 371    */
 372   KeyEventSignalV2& KeyEventSignal();
 373
 374 protected:
 375
 376   /**
 377    * @copydoc ConnectionTrackerInterface::SignalConnected
 378    */
 379   virtual void SignalConnected( SlotObserver* slotObserver, CallbackBase* callback );
 380
 381   /**
 382    * @copydoc ConnectionTrackerInterface::SignalDisconnected
 383    */
 384   virtual void SignalDisconnected( SlotObserver* slotObserver, CallbackBase* callback );
 385
 386   /**
 387    * @copydoc ConnectionTrackerInterface::GetConnectionCount
 388    */
 389   virtual std::size_t GetConnectionCount() const;
 390
 391 public: // Not intended for application developers
 392
 393   /**
 394    * @brief Create an initialised Control.
 395    *
 396    * @param[in] implementation The implementation for this control.
 397    * @return A handle to a newly allocated Dali resource.
 398    */
 399   Control(Internal::Control& implementation);
 400
 401   /**
 402    * @brief This constructor is used by CustomActor within Dali core to create additional Control handles
 403    * using an Internal CustomActor pointer.
 404    *
 405    * @param [in] internal A pointer to a newly allocated Dali resource
 406    */
 407   Control(Dali::Internal::CustomActor* internal);
 408
 409 public: // Templates for Deriving Classes
 410
 411   /**
 412    * @brief Template to allow deriving controls to DownCast handles to deriving handle classes.
 413    *
 414    * @tparam     T       The handle class
 415    * @tparam     I       The implementation class
 416    * @param[in]  handle  Handle to an object
 417    * @return Handle to a class T or an uninitialized handle.
 418    * @see DownCast(BaseHandle)
 419    */
 420   template<typename T, typename I>
 421   static T DownCast( BaseHandle handle )
 422   {
 423     T result;
 424
 425     CustomActor custom = Dali::CustomActor::DownCast( handle );
 426     if ( custom )
 427     {
 428       CustomActorImpl& customImpl = custom.GetImplementation();
 429
 430       I* impl = dynamic_cast<I*>(&customImpl);
 431
 432       if (impl)
 433       {
 434         result = T(customImpl.GetOwner());
 435       }
 436     }
 437
 438     return result;
 439   }
 440
 441   /**
 442    * @brief Template to allow deriving controls to verify whether the Internal::CustomActor* is actually an
 443    * implementation of their class.
 444    *
 445    * @tparam     I         The implementation class
 446    * @param[in]  internal  Pointer to the Internal::CustomActor
 447    */
 448   template<typename I>
 449   void VerifyCustomActorPointer(Dali::Internal::CustomActor* internal)
 450   {
 451     // Can have a NULL pointer so we only need to check if the internal implementation is our class
 452     // when there is a value.
 453     if (internal)
 454     {
 455       DALI_ASSERT_DEBUG(dynamic_cast<I*>(&CustomActor(internal).GetImplementation()));
 456     }
 457   }
 458
 459 };
 460
 461 } // namespace Toolkit
 462
 463 } // namespace Dali
 464
 465 /**
 466  * @}
 467  */
 468 #endif // __DALI_TOOLKIT_CONTROL_H__