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