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(GestureType::Value(GestureType::PINCH | GestureType::TAP | GestureType::PAN));
 121    * @endcode
 122    * @SINCE_1_0.0
 123    * @param[in] type The gesture type(s) to enable
 124    */
 125   void EnableGestureDetection( GestureType::Value 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( GestureType::Value 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::OnRelayout()
 343    */
 344   virtual void OnRelayout( const Vector2& size, RelayoutContainer& container ) override;
 345
 346   /**
 347    * @copydoc CustomActorImpl::OnSetResizePolicy()
 348    */
 349   virtual void OnSetResizePolicy( ResizePolicy::Type policy, Dimension::Type dimension ) override;
 350
 351   /**
 352    * @copydoc CustomActorImpl::GetNaturalSize()
 353    */
 354   virtual Vector3 GetNaturalSize() override;
 355
 356   /**
 357    * @copydoc CustomActorImpl::CalculateChildSize()
 358    */
 359   virtual float CalculateChildSize( const Dali::Actor& child, Dimension::Type dimension ) override;
 360
 361   /**
 362    * @copydoc CustomActorImpl::GetHeightForWidth()
 363    */
 364   virtual float GetHeightForWidth( float width ) override;
 365
 366   /**
 367    * @copydoc CustomActorImpl::GetWidthForHeight()
 368    */
 369   virtual float GetWidthForHeight( float height ) override;
 370
 371   /**
 372    * @copydoc CustomActorImpl::RelayoutDependentOnChildren()
 373    */
 374   virtual bool RelayoutDependentOnChildren( Dimension::Type dimension = Dimension::ALL_DIMENSIONS ) override;
 375
 376   /**
 377    * @copydoc CustomActorImpl::OnCalculateRelayoutSize()
 378    */
 379   virtual void OnCalculateRelayoutSize( Dimension::Type dimension ) override;
 380
 381   /**
 382    * @copydoc CustomActorImpl::OnLayoutNegotiated()
 383    */
 384   virtual void OnLayoutNegotiated( float size, Dimension::Type dimension ) override;
 385
 386 protected: // Helpers for deriving classes
 387
 388   // Construction
 389
 390   /**
 391    * @brief Flags for the constructor.
 392    * @SINCE_1_0.0
 393    */
 394   enum ControlBehaviour
 395   {
 396     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
 397     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
 398     REQUIRES_KEYBOARD_NAVIGATION_SUPPORT = 1 << ( CustomActorImpl::ACTOR_FLAG_COUNT + 1 ),     ///< True if needs to support keyboard navigation @SINCE_1_0.0
 399
 400     DISABLE_STYLE_CHANGE_SIGNALS         = 1 << ( CustomActorImpl::ACTOR_FLAG_COUNT + 2 ),     ///< True if control should not monitor style change signals @SINCE_1_2_10
 401
 402     LAST_CONTROL_BEHAVIOUR_FLAG
 403   };
 404
 405   static const int CONTROL_BEHAVIOUR_FLAG_COUNT = Log< LAST_CONTROL_BEHAVIOUR_FLAG - 1 >::value + 1;      ///< Total count of flags
 406
 407   /**
 408    * @brief Control constructor.
 409    *
 410    * @SINCE_1_0.0
 411    * @param[in] behaviourFlags Behavioural flags from ControlBehaviour enum
 412    */
 413   Control( ControlBehaviour behaviourFlags );
 414
 415   /**
 416    * @brief Second phase initialization.
 417    * @SINCE_1_0.0
 418    */
 419   void Initialize();
 420
 421 public: // API for derived classes to override
 422
 423   // Lifecycle
 424
 425   /**
 426    * @brief This method is called after the Control has been initialized.
 427    *
 428    * Derived classes should do any second phase initialization by overriding this method.
 429    * @SINCE_1_0.0
 430    */
 431   virtual void OnInitialize();
 432
 433   // Styling
 434
 435   /**
 436    * @brief This method should be overridden by deriving classes requiring notifications when the style changes.
 437    *
 438    * @SINCE_1_0.0
 439    * @param[in] styleManager The StyleManager object
 440    * @param[in] change Information denoting what has changed
 441    */
 442   virtual void OnStyleChange( Toolkit::StyleManager styleManager, StyleChange::Type change );
 443
 444   // Accessibility
 445
 446   /**
 447    * @brief This method is called when the control is accessibility activated.
 448    *
 449    * Derived classes should override this to perform custom accessibility activation.
 450    * @SINCE_1_0.0
 451    * @return true if this control can perform accessibility activation
 452    */
 453   virtual bool OnAccessibilityActivated();
 454
 455   /**
 456    * @brief This method should be overridden by deriving classes when they wish to respond the accessibility
 457    * pan gesture.
 458    *
 459    * @SINCE_1_0.0
 460    * @param[in] gesture The pan gesture
 461    * @return true if the pan gesture has been consumed by this control
 462    */
 463   virtual bool OnAccessibilityPan( PanGesture gesture );
 464
 465   /**
 466    * @brief This method should be overridden by deriving classes when they wish to respond
 467    * the accessibility up and down action (i.e. value change of slider control).
 468    *
 469    * @SINCE_1_0.0
 470    * @param[in] isIncrease Whether the value should be increased or decreased
 471    * @return true if the value changed action has been consumed by this control
 472    */
 473   virtual bool OnAccessibilityValueChange( bool isIncrease );
 474
 475   /**
 476    * @brief This method should be overridden by deriving classes when they wish to respond
 477    * the accessibility zoom action.
 478    *
 479    * @SINCE_1_0.0
 480    * @return true if the zoom action has been consumed by this control
 481    */
 482   virtual bool OnAccessibilityZoom();
 483
 484   // Keyboard focus
 485
 486   /**
 487    * @brief Called when the control gains key input focus.
 488    *
 489    * Should be overridden by derived classes if they need to customize what happens when focus is gained.
 490    * @SINCE_1_0.0
 491    */
 492   virtual void OnKeyInputFocusGained();
 493
 494   /**
 495    * @brief Called when the control loses key input focus.
 496    *
 497    * Should be overridden by derived classes if they need to customize what happens when focus is lost.
 498    * @SINCE_1_0.0
 499    */
 500   virtual void OnKeyInputFocusLost();
 501
 502   /**
 503    * @brief Gets the next keyboard focusable actor in this control towards the given direction.
 504    *
 505    * A control needs to override this function in order to support two dimensional keyboard navigation.
 506    * @SINCE_1_0.0
 507    * @param[in] currentFocusedActor The current focused actor
 508    * @param[in] direction The direction to move the focus towards
 509    * @param[in] loopEnabled Whether the focus movement should be looped within the control
 510    * @return The next keyboard focusable actor in this control or an empty handle if no actor can be focused
 511    */
 512   virtual Actor GetNextKeyboardFocusableActor( Actor currentFocusedActor, Toolkit::Control::KeyboardFocus::Direction direction, bool loopEnabled );
 513
 514   /**
 515    * @brief Informs this control that its chosen focusable actor will be focused.
 516    *
 517    * This allows the application to perform any actions if wishes
 518    * before the focus is actually moved to the chosen actor.
 519    *
 520    * @SINCE_1_0.0
 521    * @param[in] commitedFocusableActor The commited focusable actor
 522    */
 523   virtual void OnKeyboardFocusChangeCommitted( Actor commitedFocusableActor );
 524
 525   /**
 526    * @brief This method is called when the control has enter pressed on it.
 527    *
 528    * Derived classes should override this to perform custom actions.
 529    * @SINCE_1_0.0
 530    * @return true if this control supported this action
 531    */
 532   virtual bool OnKeyboardEnter();
 533
 534   /**
 535    * @brief Called after a key-event is received by the actor that has had its focus set.
 536    *
 537    * @SINCE_1_0.0
 538    * @param[in] event The Key Event
 539    * @return True if the event should be consumed
 540    */
 541   virtual bool OnKeyEvent( const KeyEvent& event );
 542
 543   // Gestures
 544
 545   /**
 546    * @brief Called whenever a pinch gesture is detected on this control.
 547    *
 548    * This can be overridden by deriving classes when pinch detection
 549    * is enabled.  The default behaviour is to scale the control by the
 550    * pinch scale.
 551    *
 552    * @SINCE_1_0.0
 553    * @param[in] pinch The pinch gesture
 554    * @note If overridden, then the default behavior will not occur.
 555    * @note Pinch detection should be enabled via EnableGestureDetection().
 556    * @see EnableGestureDetection
 557    */
 558   virtual void OnPinch( const PinchGesture& pinch );
 559
 560   /**
 561    * @brief Called whenever a pan gesture is detected on this control.
 562    *
 563    * This should be overridden by deriving classes when pan detection
 564    * is enabled.
 565    *
 566    * @SINCE_1_0.0
 567    * @param[in] pan The pan gesture
 568    * @note There is no default behavior with panning.
 569    * @note Pan detection should be enabled via EnableGestureDetection().
 570    * @see EnableGestureDetection
 571    */
 572   virtual void OnPan( const PanGesture& pan );
 573
 574   /**
 575    * @brief Called whenever a tap gesture is detected on this control.
 576    *
 577    * This should be overridden by deriving classes when tap detection
 578    * is enabled.
 579    *
 580    * @SINCE_1_0.0
 581    * @param[in] tap The tap gesture
 582    * @note There is no default behavior with a tap.
 583    * @note Tap detection should be enabled via EnableGestureDetection().
 584    * @see EnableGestureDetection
 585    */
 586   virtual void OnTap( const TapGesture& tap );
 587
 588   /**
 589    * @brief Called whenever a long press gesture is detected on this control.
 590    *
 591    * This should be overridden by deriving classes when long press
 592    * detection is enabled.
 593    *
 594    * @SINCE_1_0.0
 595    * @param[in] longPress The long press gesture
 596    * @note There is no default behaviour associated with a long press.
 597    * @note Long press detection should be enabled via EnableGestureDetection().
 598    * @see EnableGestureDetection
 599    */
 600   virtual void OnLongPress( const LongPressGesture& longPress );
 601
 602   // From ConnectionTrackerInterface
 603
 604   /**
 605    * @copydoc ConnectionTrackerInterface::SignalConnected
 606    */
 607   virtual void SignalConnected( SlotObserver* slotObserver, CallbackBase* callback ) override;
 608
 609   /**
 610    * @copydoc ConnectionTrackerInterface::SignalDisconnected
 611    */
 612   virtual void SignalDisconnected( SlotObserver* slotObserver, CallbackBase* callback ) override;
 613
 614   /**
 615    * @brief Retrieves the extension for this control.
 616    *
 617    * @SINCE_1_0.0
 618    * @return The extension if available, NULL otherwise
 619    */
 620   virtual Extension* GetControlExtension()
 621   {
 622     return NULL;
 623   }
 624
 625 private:
 626
 627   /// @cond internal
 628
 629   // Not copyable or movable
 630   DALI_INTERNAL Control( const Control& ) = delete; ///< Deleted copy constructor.
 631   DALI_INTERNAL Control( Control&& ) = delete; ///< Deleted move constructor.
 632   DALI_INTERNAL Control& operator=( const Control& ) = delete; ///< Deleted copy assignment operator.
 633   DALI_INTERNAL Control& operator=( Control&& ) = delete; ///< Deleted move assignment operator.
 634
 635 public:
 636   class DALI_INTERNAL Impl; // Class declaration is public so we can internally add devel API's to the Controls Impl
 637
 638 private:
 639   Impl* mImpl;
 640   /// @endcond
 641
 642 };
 643
 644 /**
 645  * @brief Gets implementation from the handle.
 646  *
 647  * @SINCE_1_0.0
 648  * @param handle
 649  * @return Implementation
 650  * @pre handle is initialized and points to a control
 651  */
 652 DALI_TOOLKIT_API Internal::Control& GetImplementation( Dali::Toolkit::Control& handle );
 653
 654 /**
 655  * @brief Gets implementation from the handle.
 656  *
 657  * @SINCE_1_0.0
 658  * @param handle
 659  * @return Implementation
 660  * @pre Handle is initialized and points to a control.
 661  */
 662 DALI_TOOLKIT_API const Internal::Control& GetImplementation( const Dali::Toolkit::Control& handle );
 663
 664 } // namespace Internal
 665
 666 /**
 667  * @}
 668  */
 669 } // namespace Toolkit
 670
 671 } // namespace Dali
 672
 673 #endif // DALI_TOOLKIT_CONTROL_IMPL_H