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