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