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