capi/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) 2014 Samsung Electronics Co., Ltd.
   6 //
   7 // Licensed under the Flora License, Version 1.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://floralicense.org/license/
  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  * @addtogroup CAPI_DALI_TOOLKIT_CONTROLS_MODULE
  22  * @{
  23  */
  24
  25 // INTERNAL INCLUDES
  26 #include <dali-toolkit/public-api/controls/control.h>
  27
  28 namespace Dali DALI_IMPORT_API
  29 {
  30
  31 namespace Toolkit
  32 {
  33
  34 namespace Internal DALI_INTERNAL
  35 {
  36 class StyleChangeProcessor;
  37 class RelayoutControllerImpl;
  38 class KeyInputFocusManager;
  39 }
  40
  41 typedef std::pair< Actor, Vector2 > ActorSizePair; ///< Pair of actor and size
  42 typedef std::vector< ActorSizePair > ActorSizeContainer; ///< Container of actors and their sizes
  43
  44 /**
  45  * @brief This is the internal base class for all controls.
  46  *
  47  * It will provide some common functionality required by all controls.
  48  * Implements ConnectionTrackerInterface so that signals (typically connected to member functions) will
  49  * be disconnected automatically when the control is destroyed.
  50  */
  51 class ControlImpl : public CustomActorImpl, public ConnectionTrackerInterface
  52 {
  53 public:
  54
  55   // Properties
  56   enum
  57   {
  58     CONTROL_PROPERTY_START_INDEX = PROPERTY_REGISTRATION_START_INDEX,
  59     CONTROL_PROPERTY_END_INDEX = CONTROL_PROPERTY_START_INDEX + 1000 ///< Reserving 1000 property indices
  60   };
  61
  62   // Creation
  63
  64   /**
  65    * @brief Create 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    * @return A handle to the ConntrolImpl instance.
  69    */
  70   static Control New();
  71
  72   // Destruction
  73
  74   /**
  75    * @brief Virtual destructor.
  76    */
  77   virtual ~ControlImpl();
  78
  79   // Actions
  80
  81   /**
  82    * @brief This method should be overridden by deriving classes when they wish to be notified when they
  83    * are activated.
  84    */
  85   virtual void OnActivated() { }
  86
  87   /**
  88    * @brief This method should be overridden by deriving classes when they wish to respond the accessibility
  89    * pan gesture.
  90    *
  91    * @param[in] gesture The pan gesture.
  92    * @return true if the pan gesture has been consumed by this control
  93    */
  94   virtual bool OnAccessibilityPan(PanGesture gesture);
  95
  96   /**
  97    * @brief This method should be overridden by deriving classes when they wish to respond
  98    * the accessibility up and down action (i.e. value change of slider control).
  99    *
 100    * @param[in] isIncrease Whether the value should be increased or decreased
 101    * @return true if the value changed action has been consumed by this control
 102    */
 103   virtual bool OnAccessibilityValueChange(bool isIncrease);
 104
 105   /**
 106    * @brief Sets whether this control supports two dimensional
 107    * keyboard navigation (i.e. whether it knows how to handle the
 108    * keyboardn focus movement between its child actors).
 109    *
 110    * The control doesn't support it by default.
 111    * @param[in] isSupported Whether this control supports two dimensional keyboard navigation.
 112    */
 113   void SetKeyboardNavigationSupport(bool isSupported);
 114
 115   /**
 116    * @brief Gets whether this control supports two dimensional keyboard navigation.
 117    *
 118    * @return true if this control supports two dimensional keyboard navigation.
 119    */
 120   bool IsKeyboardNavigationSupported();
 121
 122   /**
 123    * @brief Sets whether this control is a focus group for keyboard navigation.
 124    *
 125    * (i.e. the scope of keyboard focus movement
 126    * can be limitied to its child actors). The control is not a focus group by default.
 127    * @param[in] isFocusGroup Whether this control is set as a focus group for keyboard navigation.
 128    */
 129   void SetAsKeyboardFocusGroup(bool isFocusGroup);
 130
 131   /**
 132    * @brief Gets whether this control is a focus group for keyboard navigation.
 133    *
 134    * @return true if this control is set as a focus group for keyboard navigation.
 135    */
 136   bool IsKeyboardFocusGroup();
 137
 138   /**
 139    * @brief Gets the next keyboard focusable actor in this control towards the given direction.
 140    *
 141    * A control needs to override this function in order to support two dimensional keyboard navigation.
 142    * @param[in] currentFocusedActor The current focused actor.
 143    * @param[in] direction The direction to move the focus towards.
 144    * @param[in] loopEnabled Whether the focus movement should be looped within the control.
 145    * @return the next keyboard focusable actor in this control or an empty handle if no actor can be focused.
 146    */
 147   virtual Actor GetNextKeyboardFocusableActor(Actor currentFocusedActor, Control::KeyboardFocusNavigationDirection direction, bool loopEnabled);
 148
 149   /**
 150    * @brief Informs this control that its chosen focusable actor will be focused.
 151    *
 152    * This allows the application to preform any actions if wishes
 153    * before the focus is actually moved to the chosen actor.
 154    *
 155    * @param[in] commitedFocusableActor The commited focusable actor.
 156    */
 157   virtual void OnKeyboardFocusChangeCommitted(Actor commitedFocusableActor) { }
 158
 159   /**
 160    * @brief Performs actions as requested using the action name.
 161    *
 162    * @param[in] object The object on which to perform the action.
 163    * @param[in] actionName The action to perform.
 164    * @param[in] attributes The attributes with which to perfrom this action.
 165    * @return true if action has been accepted by this control
 166    */
 167   static bool DoAction(BaseObject* object, const std::string& actionName, const std::vector<Property::Value>& attributes);
 168
 169   /**
 170    * @brief If deriving classes wish to fine tune pinch gesture
 171    * detection then they can access the gesture detector through this
 172    * API and modify the detection.
 173    *
 174    * @return The pinch gesture detector.
 175    * @pre Pinch detection should have been enabled via EnableGestureDetection().
 176    * @see EnableGestureDetection
 177    */
 178   PinchGestureDetector GetPinchGestureDetector() const;
 179
 180   /**
 181    * @brief If deriving classes wish to fine tune pan gesture
 182    * detection then they can access the gesture detector through this
 183    * API and modify the detection.
 184    *
 185    * @return The pan gesture detector.
 186    * @pre Pan detection should have been enabled via EnableGestureDetection().
 187    * @see EnableGestureDetection
 188    */
 189   PanGestureDetector GetPanGestureDetector() const;
 190
 191   /**
 192    * @brief If deriving classes wish to fine tune tap gesture
 193    * detection then they can access the gesture detector through this
 194    * API and modify the detection.
 195    *
 196    * @return The tap gesture detector.
 197    * @pre Tap detection should have been enabled via EnableGestureDetection().
 198    * @see EnableGestureDetection
 199    */
 200   TapGestureDetector GetTapGestureDetector() const;
 201
 202   /**
 203    * @brief If deriving classes wish to fine tune long press gesture
 204    * detection then they can access the gesture detector through this
 205    * API and modify the detection.
 206    *
 207    * @return The long press gesture detector.
 208    * @pre Long press detection should have been enabled via EnableGestureDetection().
 209    * @see EnableGestureDetection
 210    */
 211   LongPressGestureDetector GetLongPressGestureDetector() const;
 212
 213 public:
 214
 215   /**
 216    * @copydoc Dali::Toolkit::Control::KeyEventSignal()
 217    */
 218   Toolkit::Control::KeyEventSignalV2& KeyEventSignal();
 219
 220 protected:
 221
 222   // Construction
 223
 224   /**
 225    * @brief Second phase initialization.
 226    */
 227   void Initialize();
 228
 229   // Gesture Detection
 230
 231   /**
 232    * @brief Allows deriving classes to enable any of the gesture detectors that are available.
 233    *
 234    * Gesture detection can be enabled one at a time or in bitwise format as shown:
 235    * @code
 236    * EnableGestureDetection(Gesture::Type(Gesture::Pinch | Gesture::Tap | Gesture::Pan));
 237    * @endcode
 238    * @param[in]  type  The gesture type(s) to enable.
 239    */
 240   void EnableGestureDetection(Gesture::Type type);
 241
 242   /**
 243    * @brief Allows deriving classes to disable any of the gesture detectors.
 244    *
 245    * Like EnableGestureDetection, this can also be called using bitwise or.
 246    * @param[in]  type  The gesture type(s) to disable.
 247    * @see EnableGetureDetection
 248    */
 249   void DisableGestureDetection(Gesture::Type type);
 250
 251 private: // For derived classes to override
 252
 253   /**
 254    * @brief This method is called after the Control has been initialized.
 255    *
 256    * Derived classes should do any second phase initialization by
 257    * overriding this method.
 258    */
 259   virtual void OnInitialize() { }
 260
 261   /**
 262    * @brief This method should be overridden by deriving classes when
 263    * they wish to be notified when the style changes.
 264    *
 265    * @param[in] change  Information denoting what has changed.
 266    */
 267   virtual void OnStyleChange(StyleChange change) { }
 268
 269   /**
 270    * @brief Called whenever a pinch gesture is detected on this control.
 271    *
 272    * This can be overridden by deriving classes when pinch detection
 273    * is enabled.  The default behaviour is to scale the control by the
 274    * pinch scale.
 275    *
 276    * @note If overridden, then the default behaviour will not occur.
 277    * @note Pinch detection should be enabled via EnableGestureDetection().
 278    * @param[in]  pinch  The pinch gesture.
 279    * @see EnableGestureDetection
 280    */
 281   virtual void OnPinch(PinchGesture pinch);
 282
 283   /**
 284    * @brief Called whenever a pan gesture is detected on this control.
 285    *
 286    * This should be overridden by deriving classes when pan detection
 287    * is enabled.
 288    *
 289    * @note There is no default behaviour with panning.
 290    * @note Pan detection should be enabled via EnableGestureDetection().
 291    * @param[in]  pan  The pan gesture.
 292    * @see EnableGestureDetection
 293    */
 294   virtual void OnPan(PanGesture pan) { }
 295
 296   /**
 297    * @brief Called whenever a tap gesture is detected on this control.
 298    *
 299    * This should be overridden by deriving classes when tap detection
 300    * is enabled.
 301    *
 302    * @note There is no default behaviour with a tap.
 303    * @note Tap detection should be enabled via EnableGestureDetection().
 304    * @param[in]  tap  The tap gesture.
 305    * @see EnableGestureDetection
 306    */
 307   virtual void OnTap(TapGesture tap) { }
 308
 309   /**
 310    * @brief Called whenever a long press gesture is detected on this control.
 311    *
 312    * This should be overridden by deriving classes when long press
 313    * detection is enabled.
 314    *
 315    * @note There is no default behaviour associated with a long press.
 316    * @note Long press detection should be enabled via EnableGestureDetection().
 317    * @param[in]  longPress  The long press gesture.
 318    * @see EnableGestureDetection
 319    */
 320   virtual void OnLongPress(LongPressGesture longPress) { }
 321
 322   /**
 323    * @brief Called whenever the control is added to the stage.
 324    *
 325    * Could be overridden by derived classes.
 326    */
 327   virtual void OnControlStageConnection() { }
 328
 329   /**
 330    * @brief Called whenever the control is removed from the stage.
 331    *
 332    * Could be overridden by derived classes.
 333    */
 334   virtual void OnControlStageDisconnection() { }
 335
 336   /**
 337    * @brief Called whenever an Actor is added to the control.
 338    *
 339    * Could be overridden by derived classes.
 340    *
 341    * @param[in] child The added actor.
 342    */
 343   virtual void OnControlChildAdd( Actor& child ) { }
 344
 345   /**
 346    * @brief Called whenever an Actor is removed from the control.
 347    *
 348    * Could be overridden by derived classes.
 349    *
 350    * @param[in] child The removed actor.
 351    */
 352   virtual void OnControlChildRemove( Actor& child ) { }
 353
 354   /**
 355    * @brief Called whenever the Control's size is set.
 356    *
 357    * Could be overridden by derived classes.
 358    *
 359    * @param[in] size The new size.
 360    */
 361   virtual void OnControlSizeSet( const Vector3& size ) { }
 362
 363   /**
 364    * @brief Called after the Dali::Stage::SignalMessageQueueFlushed()
 365    * signal is emitted if this control requested to be relaid-out.
 366    *
 367    * Should be overridden by derived classes if they need to layout
 368    * actors differently after certain operations like add or remove
 369    * actors, resize or after changing especific properties.
 370    *
 371    * @param[in]      size       The allocated size.
 372    * @param[in,out]  container  The control should add actors to this container that it is not able
 373    *                            to allocate a size for.
 374    */
 375   virtual void OnRelaidOut( Vector2 size, ActorSizeContainer& container );
 376
 377 private: // From CustomActorImpl, derived classes can override these.
 378
 379   /**
 380    * @brief Sends a request to relayout this control.
 381    *
 382    * The control will be relaid out after the
 383    * Dali::Stage::SignalMessageQueueFlushed() signal is emitted.
 384    *
 385    * It calls OnControlStageConnection() to notify derived classes.
 386    *
 387    * @see Dali::CustomActorImpl::OnStageConnection()
 388    */
 389   virtual void OnStageConnection();
 390
 391   /**
 392    * @brief Calls OnControlStageDisconnection() to notify derived classed.
 393    *
 394    * @see Dali::CustomActorImpl::OnStageDisconnection()
 395    */
 396   virtual void OnStageDisconnection();
 397
 398   /**
 399    * @brief Sends a request to relayout this control.
 400    *
 401    * The control will be relaid out after the
 402    * Dali::Stage::SignalMessageQueueFlushed() signal is emitted.  It
 403    * calls OnControlChildAdd() to notify derived classes.
 404    *
 405    * @note This method shouldn't be overridden by derived classes.
 406    *
 407    * @param[in] child The added actor.
 408    *
 409    * @see Dali::CustomActorImpl::OnChildAdd(Actor&)
 410    */
 411   virtual void OnChildAdd(Actor& child);
 412
 413   /**
 414    * @brief Sends a request to relayout this control.
 415    *
 416    * The control will be relaid out after the
 417    * Dali::Stage::SignalMessageQueueFlushed() signal is emitted.  It
 418    * calls OnControlChildRemove() to notify derived classes.
 419    *
 420    * @note This method shouldn't be overridden by derived classes.
 421    *
 422    * @param[in] child The removed actor.
 423    *
 424    * @see Dali::CustomActorImpl::OnChildRemove(Actor&)
 425    */
 426   virtual void OnChildRemove(Actor& child);
 427
 428   /**
 429    * @brief It stores the size set by size negotiation and relayout.
 430    *
 431    * It also keeps a backup of the size set through the Actor's API used in the size negotiation.
 432    * It calls the OnControlSizeSet() to notify derived classes.
 433    *
 434    * @param[in] targetSize The new size.
 435    *
 436    * @see Dali::CustomActorImpl::OnSizeSet(const Vector3&)
 437    */
 438   virtual void OnSizeSet(const Vector3& targetSize);
 439
 440   /**
 441    * @copydoc Dali::CustomActorImpl::OnSizeAnimation(Animation&, const Vector3&)
 442    */
 443   virtual void OnSizeAnimation(Animation& animation, const Vector3& targetSize);
 444
 445   /**
 446    * @copydoc Dali::CustomActorImpl::OnTouchEvent(const TouchEvent&)
 447    */
 448   virtual bool OnTouchEvent(const TouchEvent& event);
 449
 450   /**
 451    * @copydoc Dali::CustomActorImpl::OnKeyEvent(const KeyEvent&)
 452    */
 453   virtual bool OnKeyEvent(const KeyEvent& event);
 454
 455   /**
 456    * @copydoc Dali::CustomActorImpl::OnMouseWheelEvent(const MouseWheelEvent&)
 457    */
 458   virtual bool OnMouseWheelEvent(const MouseWheelEvent& event);
 459
 460   /**
 461    * @copydoc Dali::CustomActorImpl::OnKeyInputFocusGained()
 462    */
 463   virtual void OnKeyInputFocusGained();
 464
 465   /**
 466    * @copydoc Dali::CustomActorImpl::OnKeyInputFocusLost()
 467    */
 468   virtual void OnKeyInputFocusLost();
 469
 470   /**
 471    * @copydoc Dali::CustomActorImpl::GetChildByAlias(const std::string& actorAlias)
 472    */
 473   virtual Actor GetChildByAlias(const std::string& actorAlias);
 474
 475 private:
 476
 477   /**
 478    * @brief Perform the activated action.
 479    *
 480    * @param[in] attributes The attributes to perfrom this action.
 481    */
 482   void DoActivatedAction(const PropertyValueContainer& attributes);
 483
 484 protected: // Construction
 485
 486   /**
 487    * @brief Create a ControlImpl.
 488    *
 489    * @param[in] requiresTouchEvents True if the OnTouchEvent() callback is required.
 490    */
 491   ControlImpl(bool requiresTouchEvents);
 492
 493 public:
 494
 495   // Size negotiation
 496
 497   /**
 498    * @copydoc Control::SetSizePolicy()
 499    */
 500   void SetSizePolicy( Control::SizePolicy widthPolicy, Control::SizePolicy heightPolicy );
 501
 502   /**
 503    * @copydoc Control::GetSizePolicy()
 504    */
 505   void GetSizePolicy( Control::SizePolicy& widthPolicy, Control::SizePolicy& heightPolicy ) const;
 506
 507   /**
 508    * @copydoc Control::SetMinimumSize()
 509    */
 510   void SetMinimumSize( const Vector3& size );
 511
 512   /**
 513    * @copydoc Control::GetMinimumSize()
 514    */
 515   const Vector3& GetMinimumSize() const;
 516
 517   /**
 518    * @copydoc Control::SetMaximumSize()
 519    */
 520   void SetMaximumSize( const Vector3& size );
 521
 522   /**
 523    * @copydoc Control::GetMaximumSize()
 524    */
 525   const Vector3& GetMaximumSize() const;
 526
 527   /**
 528    * @copydoc Control::GetNaturalSize()
 529    */
 530   virtual Vector3 GetNaturalSize();
 531
 532   /**
 533    * @copydoc Control::GetHeightForWidth()
 534    */
 535   virtual float GetHeightForWidth( float width );
 536
 537   /**
 538    * @copydoc Control::GetWidthForHeight()
 539    */
 540   virtual float GetWidthForHeight( float height );
 541
 542   /**
 543    * @brief Retrieves the current Control's size.
 544    *
 545    * @return The control's size.
 546    */
 547   const Vector3& GetControlSize() const;
 548
 549   /**
 550    * @brief Retrieves the Control's size set by the Application / Control.
 551    *
 552    * @return The control's size.
 553    */
 554   const Vector3& GetSizeSet() const;
 555
 556   //KeyInput
 557
 558   /**
 559    * @copydoc Control::SetKeyInputFocus()
 560    */
 561   void SetKeyInputFocus();
 562
 563   /**
 564    * @copydoc Control::HasKeyInputFocus()
 565    */
 566   bool HasKeyInputFocus();
 567
 568   /**
 569    * @copydoc Control::ClearKeyInputFocus()
 570    */
 571   void ClearKeyInputFocus();
 572
 573   /**
 574    * @copydoc ConnectionTrackerInterface::SignalConnected
 575    */
 576   virtual void SignalConnected( SlotObserver* slotObserver, CallbackBase* callback );
 577
 578   /**
 579    * @copydoc ConnectionTrackerInterface::SignalDisconnected
 580    */
 581   virtual void SignalDisconnected( SlotObserver* slotObserver, CallbackBase* callback );
 582
 583   /**
 584    * @copydoc ConnectionTrackerInterface::GetConnectionCount
 585    */
 586   virtual std::size_t GetConnectionCount() const;
 587
 588 protected:
 589
 590   /**
 591    * @brief Sends a request to be relaid-out.
 592    *
 593    * This method is called from OnStageConnection(), OnChildAdd(),
 594    * OnChildRemove(), SetSizePolicy(), SetMinimumSize() and
 595    * SetMaximumSize().
 596    *
 597    * This method could also be called from derived classes every time
 598    * a control's poperty change and it needs to be relaid-out.  After
 599    * the Dali::Stage::SignalMessageQueueFlushed() is emitted a
 600    * relayout process starts and all controls which called this method
 601    * will be relaid-out.
 602    *
 603    * @note RelayoutRequest() only sends a request per Control before
 604    * the Dali::Stage::SignalMessageQueueFlushed() signal is
 605    * emitted. That means a control will be relaid-out only once, even
 606    * if more than one request is sent between two consecutive signals.
 607    */
 608   void RelayoutRequest();
 609
 610   /**
 611    * @brief Helper method for controls to Relayout their children if
 612    * they do not know whether that child is a control or not.
 613    *
 614    * @param[in]      actor      The actor to relayout.
 615    * @param[in]      size       The size to allocate to the actor.
 616    * @param[in,out]  container  The container that holds actors that have not been allocated a size yet.
 617    */
 618   static void Relayout( Actor actor, Vector2 size, ActorSizeContainer& container );
 619
 620 private: // Used by the RelayoutController
 621
 622   /**
 623    * @brief Called by the RelayoutController to negotiate the size of a control.
 624    *
 625    * The size allocated by the the algorithm is passed in which the
 626    * control must adhere to.  A container is passed in as well which
 627    * the control should populate with actors it has not / or does not
 628    * need to handle in its size negotiation.
 629    *
 630    * @param[in]      size       The allocated size.
 631    * @param[in,out]  container  The container that holds actors that are fed back into the
 632    *                            RelayoutController algorithm.
 633    */
 634   void NegotiateSize( Vector2 size, ActorSizeContainer& container );
 635
 636 private:
 637
 638   /**
 639    * @brief Called by NegotiateSize when the size to allocate to the control has been calculated.
 640    *
 641    * It calls the OnRelaidOut() method which can be overridden by derived classes.
 642    *
 643    * @param[in]      size       The allocated size.
 644    * @param[in,out]  container  The control should add actors to this container that it is not able
 645    *                            to allocate a size for.
 646    */
 647   void Relayout( Vector2 size, ActorSizeContainer& container );
 648
 649   /**
 650    * @brief Used by the KeyInputFocusManager to emit key event signals.
 651    *
 652    * @param[in] event The key event.
 653    * @return True if the event was consumed.
 654    */
 655   bool EmitKeyEventSignal(const KeyEvent& event);
 656
 657
 658
 659 private:
 660
 661   // Undefined
 662   ControlImpl(const ControlImpl&);
 663   ControlImpl& operator=(const ControlImpl&);
 664
 665   class Impl;
 666   Impl *mImpl;
 667
 668   friend class Internal::StyleChangeProcessor;
 669   friend class Internal::RelayoutControllerImpl;   ///< Relayout controller needs to call Relayout() which is private.
 670   friend class Internal::KeyInputFocusManager;     ///< KeyInputFocusManager needs to call which is private.
 671 };
 672
 673 } // namespace Toolkit
 674
 675 } // namespace Dali
 676
 677 /**
 678  * @}
 679  */
 680 #endif // __DALI_TOOLKIT_CONTROL_IMPL_H__