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