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