dali-toolkit/public-api/controls/control-impl.h

   1 #ifndef __DALI_TOOLKIT_CONTROL_IMPL_H__
   2 #define __DALI_TOOLKIT_CONTROL_IMPL_H__
   3
   4 /*
   5  * Copyright (c) 2015 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 // EXTERNAL INCLUDES
  22 #include <dali/public-api/adaptor-framework/style-change.h>
  23 #include <dali/public-api/events/long-press-gesture.h>
  24 #include <dali/public-api/events/pan-gesture.h>
  25 #include <dali/public-api/events/pinch-gesture.h>
  26 #include <dali/public-api/events/tap-gesture.h>
  27 #include <dali/public-api/object/property-index-ranges.h>
  28 #include <dali/public-api/object/type-info.h>
  29
  30 // INTERNAL INCLUDES
  31 #include <dali-toolkit/public-api/controls/control.h>
  32
  33 namespace Dali
  34 {
  35
  36 namespace Toolkit
  37 {
  38
  39 class StyleManager;
  40
  41 namespace Internal DALI_INTERNAL
  42 {
  43 class KeyInputFocusManager;
  44 }
  45
  46 namespace Internal
  47 {
  48
  49 /**
  50  * @brief This is the internal base class for all controls.
  51  *
  52  * It will provide some common functionality required by all controls.
  53  * Implements ConnectionTrackerInterface so that signals (typically connected to member functions) will
  54  * be disconnected automatically when the control is destroyed.
  55  */
  56 class DALI_IMPORT_API Control : public CustomActorImpl, public ConnectionTrackerInterface
  57 {
  58 public:
  59
  60   // Creation & Destruction
  61
  62   /**
  63    * @brief Create a new ControlImpl instance that does not require touch by default.
  64    *
  65    * If touch is required then the user can connect to this class' touch signal.
  66    * @return A handle to the ControlImpl instance.
  67    */
  68   static Toolkit::Control New();
  69
  70   /**
  71    * @brief Virtual destructor.
  72    */
  73   virtual ~Control();
  74
  75   // Size negotiation
  76
  77   /**
  78    * @copydoc Dali::CustomActorImpl::GetHeightForWidth()
  79    */
  80   virtual float GetHeightForWidth( float width );
  81
  82   /**
  83    * @copydoc Dali::CustomActorImpl::GetWidthForHeight()
  84    */
  85   virtual float GetWidthForHeight( float height );
  86
  87   /**
  88    * @copydoc Toolkit::CustomActorImpl::GetNaturalSize()
  89    */
  90   virtual Vector3 GetNaturalSize();
  91
  92   // Key Input
  93
  94   /**
  95    * @copydoc Toolkit::Control::SetKeyInputFocus()
  96    */
  97   void SetKeyInputFocus();
  98
  99   /**
 100    * @copydoc Toolkit::Control::HasKeyInputFocus()
 101    */
 102   bool HasKeyInputFocus();
 103
 104   /**
 105    * @copydoc Toolkit::Control::ClearKeyInputFocus()
 106    */
 107   void ClearKeyInputFocus();
 108
 109   // Gesture Detection
 110
 111   /**
 112    * @brief If deriving classes wish to fine tune pinch gesture
 113    * detection then they can access the gesture detector through this
 114    * API and modify the detection.
 115    *
 116    * @return The pinch gesture detector.
 117    * @pre Pinch detection should have been enabled via EnableGestureDetection().
 118    * @see EnableGestureDetection
 119    */
 120   PinchGestureDetector GetPinchGestureDetector() const;
 121
 122   /**
 123    * @brief If deriving classes wish to fine tune pan gesture
 124    * detection then they can access the gesture detector through this
 125    * API and modify the detection.
 126    *
 127    * @return The pan gesture detector.
 128    * @pre Pan detection should have been enabled via EnableGestureDetection().
 129    * @see EnableGestureDetection
 130    */
 131   PanGestureDetector GetPanGestureDetector() const;
 132
 133   /**
 134    * @brief If deriving classes wish to fine tune tap gesture
 135    * detection then they can access the gesture detector through this
 136    * API and modify the detection.
 137    *
 138    * @return The tap gesture detector.
 139    * @pre Tap detection should have been enabled via EnableGestureDetection().
 140    * @see EnableGestureDetection
 141    */
 142   TapGestureDetector GetTapGestureDetector() const;
 143
 144   /**
 145    * @brief If deriving classes wish to fine tune long press gesture
 146    * detection then they can access the gesture detector through this
 147    * API and modify the detection.
 148    *
 149    * @return The long press gesture detector.
 150    * @pre Long press detection should have been enabled via EnableGestureDetection().
 151    * @see EnableGestureDetection
 152    */
 153   LongPressGestureDetector GetLongPressGestureDetector() const;
 154
 155   // Background
 156
 157   /**
 158    * @copydoc Dali::Toolkit::Control::SetStyleName
 159    */
 160   void SetStyleName( const std::string& styleName );
 161
 162   /**
 163    * @copydoc Dali::Toolkit::Control::GetStyleName
 164    */
 165   const std::string& GetStyleName() const;
 166
 167   /**
 168    * @copydoc Dali::Toolkit::Control::SetBackgroundColor
 169    */
 170   void SetBackgroundColor( const Vector4& color );
 171
 172   /**
 173    * @copydoc Dali::Toolkit::Control::GetBackgroundColor
 174    */
 175   Vector4 GetBackgroundColor() const;
 176
 177   /**
 178    * @copydoc Dali::Toolkit::Control::SetBackgroundImage
 179    */
 180   void SetBackgroundImage( Image image );
 181
 182   /**
 183    * @copydoc Dali::Toolkit::Control::ClearBackground
 184    */
 185   void ClearBackground();
 186
 187   /**
 188    * @copydoc Dali::Toolkit::Control::GetBackgroundActor
 189    */
 190   Actor GetBackgroundActor() const;
 191
 192   // Keyboard Navigation
 193
 194   /**
 195    * @brief Sets whether this control supports two dimensional
 196    * keyboard navigation (i.e. whether it knows how to handle the
 197    * keyboard focus movement between its child actors).
 198    *
 199    * The control doesn't support it by default.
 200    * @param[in] isSupported Whether this control supports two dimensional keyboard navigation.
 201    */
 202   void SetKeyboardNavigationSupport(bool isSupported);
 203
 204   /**
 205    * @brief Gets whether this control supports two dimensional keyboard navigation.
 206    *
 207    * @return true if this control supports two dimensional keyboard navigation.
 208    */
 209   bool IsKeyboardNavigationSupported();
 210
 211   // Called by Focus Managers
 212
 213   /**
 214    * @brief Called by the focus manager and keyboard focus manager to Activate the Control
 215    */
 216   DALI_INTERNAL void Activate();
 217
 218   /**
 219    * @brief This method should be overridden by deriving classes when they wish to respond the accessibility
 220    * pan gesture.
 221    *
 222    * @param[in] gesture The pan gesture.
 223    * @return true if the pan gesture has been consumed by this control
 224    */
 225   virtual bool OnAccessibilityPan(PanGesture gesture);
 226
 227   /**
 228    * @brief This method should be overridden by deriving classes when they wish to respond the accessibility
 229    * touch event.
 230    *
 231    * @param[in] touchEvent The touch event.
 232    * @return true if the touch event has been consumed by this control
 233    */
 234   virtual bool OnAccessibilityTouch(const TouchEvent& touchEvent);
 235
 236   /**
 237    * @brief This method should be overridden by deriving classes when they wish to respond
 238    * the accessibility up and down action (i.e. value change of slider control).
 239    *
 240    * @param[in] isIncrease Whether the value should be increased or decreased
 241    * @return true if the value changed action has been consumed by this control
 242    */
 243   virtual bool OnAccessibilityValueChange(bool isIncrease);
 244
 245   // Keyboard Focus
 246
 247   /**
 248    * @brief Sets whether this control is a focus group for keyboard navigation.
 249    *
 250    * (i.e. the scope of keyboard focus movement
 251    * can be limitied to its child actors). The control is not a focus group by default.
 252    * @param[in] isFocusGroup Whether this control is set as a focus group for keyboard navigation.
 253    */
 254   void SetAsKeyboardFocusGroup(bool isFocusGroup);
 255
 256   /**
 257    * @brief Gets whether this control is a focus group for keyboard navigation.
 258    *
 259    * @return true if this control is set as a focus group for keyboard navigation.
 260    */
 261   bool IsKeyboardFocusGroup();
 262
 263   /**
 264    * @brief Gets the next keyboard focusable actor in this control towards the given direction.
 265    *
 266    * A control needs to override this function in order to support two dimensional keyboard navigation.
 267    * @param[in] currentFocusedActor The current focused actor.
 268    * @param[in] direction The direction to move the focus towards.
 269    * @param[in] loopEnabled Whether the focus movement should be looped within the control.
 270    * @return the next keyboard focusable actor in this control or an empty handle if no actor can be focused.
 271    */
 272   virtual Actor GetNextKeyboardFocusableActor(Actor currentFocusedActor, Toolkit::Control::KeyboardFocusNavigationDirection direction, bool loopEnabled);
 273
 274   /**
 275    * @brief Informs this control that its chosen focusable actor will be focused.
 276    *
 277    * This allows the application to preform any actions if wishes
 278    * before the focus is actually moved to the chosen actor.
 279    *
 280    * @param[in] commitedFocusableActor The commited focusable actor.
 281    */
 282   virtual void OnKeyboardFocusChangeCommitted(Actor commitedFocusableActor);
 283
 284   /**
 285    * @brief Emits KeyInputFocusGained signal if true else emits KeyInputFocusLost signal
 286    *
 287    * Should be called last by the control after it acts on the Input Focus change.
 288    *
 289    * @param[in] focusGained True if gained, False if lost
 290    */
 291   void EmitKeyInputFocusSignal( bool focusGained );
 292
 293   // Actions & Signals
 294
 295   /**
 296    * @brief Performs actions as requested using the action name.
 297    *
 298    * @param[in] object The object on which to perform the action.
 299    * @param[in] actionName The action to perform.
 300    * @param[in] attributes The attributes with which to perfrom this action.
 301    * @return true if action has been accepted by this control
 302    */
 303   static bool DoAction(BaseObject* object, const std::string& actionName, const PropertyValueContainer& attributes);
 304
 305   /**
 306    * Connects a callback function with the object's signals.
 307    * @param[in] object The object providing the signal.
 308    * @param[in] tracker Used to disconnect the signal.
 309    * @param[in] signalName The signal to connect to.
 310    * @param[in] functor A newly allocated FunctorDelegate.
 311    * @return True if the signal was connected.
 312    * @post If a signal was connected, ownership of functor was passed to CallbackBase. Otherwise the caller is responsible for deleting the unused functor.
 313    */
 314   static bool DoConnectSignal( BaseObject* object, ConnectionTrackerInterface* tracker, const std::string& signalName, FunctorDelegate* functor );
 315
 316   /**
 317    * @copydoc Dali::Toolkit::Control::KeyEventSignal()
 318    */
 319   Toolkit::Control::KeyEventSignalType& KeyEventSignal();
 320
 321   /**
 322    * @copydoc Dali::Toolkit::Control::KeyInputFocusGainedSignal()
 323    */
 324   Toolkit::Control::KeyInputFocusSignalType& KeyInputFocusGainedSignal();
 325
 326   /**
 327    * @copydoc Dali::Toolkit::Control::KeyInputFocusLostSignal()
 328    */
 329   Toolkit::Control::KeyInputFocusSignalType& KeyInputFocusLostSignal();
 330
 331   /**
 332    * @brief Called by the KeyInputFocusManager to emit key event signals.
 333    *
 334    * @param[in] event The key event.
 335    * @return True if the event was consumed.
 336    */
 337   DALI_INTERNAL bool EmitKeyEventSignal(const KeyEvent& event);
 338
 339 protected:
 340
 341   // Construction
 342
 343   // Flags for the constructor
 344   enum ControlBehaviour
 345   {
 346     REQUIRES_STYLE_CHANGE_SIGNALS        = 1 << ( CustomActorImpl::ACTOR_FLAG_COUNT + 0 ),     ///< True if needs to monitor style change signals such as theme/font change
 347     REQUIRES_KEYBOARD_NAVIGATION_SUPPORT = 1 << ( CustomActorImpl::ACTOR_FLAG_COUNT + 1 ),     ///< True if needs to support keyboard navigation
 348
 349     LAST_CONTROL_BEHAVIOUR_FLAG
 350   };
 351
 352   static const int CONTROL_BEHAVIOUR_FLAG_COUNT = Log< LAST_CONTROL_BEHAVIOUR_FLAG - 1 >::value + 1;      ///< Total count of flags
 353
 354   /**
 355    * @brief Create a Control.
 356    *
 357    * @param[in] behaviourFlags Behavioural flags from ControlBehaviour enum
 358    */
 359   Control(ControlBehaviour behaviourFlags);
 360
 361   /**
 362    * @brief Second phase initialization.
 363    */
 364   void Initialize();
 365
 366   // Gesture Detection
 367
 368   /**
 369    * @brief Allows deriving classes to enable any of the gesture detectors that are available.
 370    *
 371    * Gesture detection can be enabled one at a time or in bitwise format as shown:
 372    * @code
 373    * EnableGestureDetection(Gesture::Type(Gesture::Pinch | Gesture::Tap | Gesture::Pan));
 374    * @endcode
 375    * @param[in]  type  The gesture type(s) to enable.
 376    */
 377   void EnableGestureDetection(Gesture::Type type);
 378
 379   /**
 380    * @brief Allows deriving classes to disable any of the gesture detectors.
 381    *
 382    * Like EnableGestureDetection, this can also be called using bitwise or.
 383    * @param[in]  type  The gesture type(s) to disable.
 384    * @see EnableGetureDetection
 385    */
 386   void DisableGestureDetection(Gesture::Type type);
 387
 388   /**
 389    * @copydoc Dali::CustomActorImpl::RelayoutDependentOnChildren()
 390    */
 391   virtual bool RelayoutDependentOnChildren( Dimension::Type dimension = Dimension::ALL_DIMENSIONS );
 392
 393 private:
 394
 395   // For derived classes to override
 396
 397   /**
 398    * @brief This method is called after the Control has been initialized.
 399    *
 400    * Derived classes should do any second phase initialization by overriding this method.
 401    */
 402   virtual void OnInitialize();
 403
 404   /**
 405    * @brief This method is called when the control is activated.
 406    *
 407    * Derived classes should override this if they wish to be notified when they are activated.
 408    */
 409   virtual void OnActivated();
 410
 411   /**
 412    * @brief This method should be overridden by deriving classes requiring notifications when the style changes.
 413    *
 414    * @param[in] styleManager  The StyleManager object.
 415    * @param[in] change  Information denoting what has changed.
 416    */
 417   virtual void OnStyleChange( Toolkit::StyleManager styleManager, StyleChange change );
 418
 419   /**
 420    * @brief Called whenever a pinch gesture is detected on this control.
 421    *
 422    * This can be overridden by deriving classes when pinch detection
 423    * is enabled.  The default behaviour is to scale the control by the
 424    * pinch scale.
 425    *
 426    * @note If overridden, then the default behaviour will not occur.
 427    * @note Pinch detection should be enabled via EnableGestureDetection().
 428    * @param[in]  pinch  The pinch gesture.
 429    * @see EnableGestureDetection
 430    */
 431   virtual void OnPinch(const PinchGesture& pinch);
 432
 433   /**
 434    * @brief Called whenever a pan gesture is detected on this control.
 435    *
 436    * This should be overridden by deriving classes when pan detection
 437    * is enabled.
 438    *
 439    * @note There is no default behaviour with panning.
 440    * @note Pan detection should be enabled via EnableGestureDetection().
 441    * @param[in]  pan  The pan gesture.
 442    * @see EnableGestureDetection
 443    */
 444   virtual void OnPan( const PanGesture& pan );
 445
 446   /**
 447    * @brief Called whenever a tap gesture is detected on this control.
 448    *
 449    * This should be overridden by deriving classes when tap detection
 450    * is enabled.
 451    *
 452    * @note There is no default behaviour with a tap.
 453    * @note Tap detection should be enabled via EnableGestureDetection().
 454    * @param[in]  tap  The tap gesture.
 455    * @see EnableGestureDetection
 456    */
 457   virtual void OnTap( const TapGesture& tap );
 458
 459   /**
 460    * @brief Called whenever a long press gesture is detected on this control.
 461    *
 462    * This should be overridden by deriving classes when long press
 463    * detection is enabled.
 464    *
 465    * @note There is no default behaviour associated with a long press.
 466    * @note Long press detection should be enabled via EnableGestureDetection().
 467    * @param[in]  longPress  The long press gesture.
 468    * @see EnableGestureDetection
 469    */
 470   virtual void OnLongPress( const LongPressGesture& longPress );
 471
 472   /**
 473    * @brief Called whenever the control is added to the stage.
 474    *
 475    * Could be overridden by derived classes.
 476    */
 477   virtual void OnControlStageConnection();
 478
 479   /**
 480    * @brief Called whenever the control is removed from the stage.
 481    *
 482    * Could be overridden by derived classes.
 483    */
 484   virtual void OnControlStageDisconnection();
 485
 486   /**
 487    * @brief Called whenever an Actor is added to the control.
 488    *
 489    * Could be overridden by derived classes.
 490    *
 491    * @param[in] child The added actor.
 492    */
 493   virtual void OnControlChildAdd( Actor& child );
 494
 495   /**
 496    * @brief Called whenever an Actor is removed from the control.
 497    *
 498    * Could be overridden by derived classes.
 499    *
 500    * @param[in] child The removed actor.
 501    */
 502   virtual void OnControlChildRemove( Actor& child );
 503
 504   /**
 505    * @brief Called whenever the Control's size is set.
 506    *
 507    * Could be overridden by derived classes.
 508    *
 509    * @param[in] size The new size.
 510    */
 511   virtual void OnControlSizeSet( const Vector3& size );
 512
 513   /**
 514    * @brief Called when the control gains key input focus.
 515    *
 516    * Should be overridden by derived classes if they need to customize what happens when focus is gained.
 517    */
 518   virtual void OnKeyInputFocusGained();
 519
 520   /**
 521    * @brief Called when the control loses key input focus.
 522    *
 523    * Should be overridden by derived classes if they need to customize what happens when focus is lost.
 524    */
 525   virtual void OnKeyInputFocusLost();
 526
 527   // From CustomActorImpl, derived classes can override these.
 528
 529   /**
 530    * @copydoc Dali::CustomActorImpl::OnSizeAnimation(Animation&, const Vector3&)
 531    */
 532   virtual void OnSizeAnimation(Animation& animation, const Vector3& targetSize);
 533
 534   /**
 535    * @copydoc Dali::CustomActorImpl::OnTouchEvent(const TouchEvent&)
 536    */
 537   virtual bool OnTouchEvent(const TouchEvent& event);
 538
 539   /**
 540    * @copydoc Dali::CustomActorImpl::OnHoverEvent(const HoverEvent&)
 541    */
 542   virtual bool OnHoverEvent(const HoverEvent& event);
 543
 544   /**
 545    * @copydoc Dali::CustomActorImpl::OnKeyEvent(const KeyEvent&)
 546    */
 547   virtual bool OnKeyEvent(const KeyEvent& event);
 548
 549   /**
 550    * @copydoc Dali::CustomActorImpl::OnMouseWheelEvent(const MouseWheelEvent&)
 551    */
 552   virtual bool OnMouseWheelEvent(const MouseWheelEvent& event);
 553
 554   /**
 555    * @copydoc Dali::CustomActorImpl::OnCalculateRelayoutSize()
 556    */
 557   virtual void OnCalculateRelayoutSize( Dimension::Type dimension );
 558
 559   /**
 560    * @copydoc Dali::CustomActorImpl::OnLayoutNegotiated()
 561    */
 562   virtual void OnLayoutNegotiated( float size, Dimension::Type dimension );
 563
 564   /**
 565    * @copydoc Dali::CustomActorImpl::OnRelayout()
 566    */
 567   virtual void OnRelayout( const Vector2& size, RelayoutContainer& container );
 568
 569   /**
 570    * @copydoc Dali::CustomActorImpl::OnSetResizePolicy()
 571    */
 572   virtual void OnSetResizePolicy( ResizePolicy::Type policy, Dimension::Type dimension );
 573
 574   /**
 575    * @copydoc Dali::CustomActorImpl::CalculateChildSize()
 576    */
 577   virtual float CalculateChildSize( const Dali::Actor& child, Dimension::Type dimension );
 578
 579   // From CustomActorImpl, derived classes should NOT override these.
 580
 581   /**
 582    * @brief Sends a request to relayout this control.
 583    *
 584    * The control will be relaid out after the
 585    * Dali::Stage::SignalMessageQueueFlushed() signal is emitted.
 586    *
 587    * It calls OnControlStageConnection() to notify derived classes.
 588    *
 589    * @see Dali::CustomActorImpl::OnStageConnection()
 590    */
 591   virtual void OnStageConnection();
 592
 593   /**
 594    * @copydoc Dali::CustomActorImpl::OnStageDisconnection()
 595    */
 596   virtual void OnStageDisconnection();
 597
 598   /**
 599    * @copydoc Dali::CustomActorImpl::OnChildAdd(Actor&)
 600    */
 601   virtual void OnChildAdd(Actor& child);
 602
 603   /**
 604    * @copydoc Dali::CustomActorImpl::OnChildRemove(Actor&)
 605    */
 606   virtual void OnChildRemove(Actor& child);
 607
 608   /**
 609    * @copydoc Dali::CustomActorImpl::OnSizeSet(const Vector3&)
 610    */
 611   virtual void OnSizeSet(const Vector3& targetSize);
 612
 613   // From ConnectionTrackerInterface
 614
 615   /**
 616    * @copydoc ConnectionTrackerInterface::SignalConnected
 617    */
 618   virtual void SignalConnected( SlotObserver* slotObserver, CallbackBase* callback );
 619
 620   /**
 621    * @copydoc ConnectionTrackerInterface::SignalDisconnected
 622    */
 623   virtual void SignalDisconnected( SlotObserver* slotObserver, CallbackBase* callback );
 624
 625 private:
 626
 627   // Undefined
 628   DALI_INTERNAL Control(const Control&);
 629   DALI_INTERNAL Control& operator=(const Control&);
 630
 631   class Impl;
 632   Impl* mImpl;
 633
 634   friend class Internal::KeyInputFocusManager;     ///< KeyInputFocusManager needs to call several methods which are private. // TODO: Remove
 635 };
 636
 637 } // namespace Internal
 638
 639 } // namespace Toolkit
 640
 641 } // namespace Dali
 642
 643 #endif // __DALI_TOOLKIT_CONTROL_IMPL_H__