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   // Background
 214
 215   /**
 216    * @copydoc Dali::Toolkit::Control::SetBackgroundColor
 217    */
 218   void SetBackgroundColor( const Vector4& color );
 219
 220   /**
 221    * @copydoc Dali::Toolkit::Control::GetBackgroundColor
 222    */
 223   Vector4 GetBackgroundColor() const;
 224
 225   /**
 226    * @copydoc Dali::Toolkit::Control::SetBackground
 227    */
 228   void SetBackground( Image image );
 229
 230   /**
 231    * @copydoc Dali::Toolkit::Control::ClearBackground
 232    */
 233   void ClearBackground();
 234
 235   /**
 236    * @copydoc Dali::Toolkit::Control::GetBackgroundActor
 237    */
 238   Actor GetBackgroundActor() const;
 239
 240 public:
 241
 242   /**
 243    * @copydoc Dali::Toolkit::Control::KeyEventSignal()
 244    */
 245   Toolkit::Control::KeyEventSignalV2& KeyEventSignal();
 246
 247 protected:
 248
 249   // Construction
 250
 251   /**
 252    * @brief Second phase initialization.
 253    */
 254   void Initialize();
 255
 256   // Gesture Detection
 257
 258   /**
 259    * @brief Allows deriving classes to enable any of the gesture detectors that are available.
 260    *
 261    * Gesture detection can be enabled one at a time or in bitwise format as shown:
 262    * @code
 263    * EnableGestureDetection(Gesture::Type(Gesture::Pinch | Gesture::Tap | Gesture::Pan));
 264    * @endcode
 265    * @param[in]  type  The gesture type(s) to enable.
 266    */
 267   void EnableGestureDetection(Gesture::Type type);
 268
 269   /**
 270    * @brief Allows deriving classes to disable any of the gesture detectors.
 271    *
 272    * Like EnableGestureDetection, this can also be called using bitwise or.
 273    * @param[in]  type  The gesture type(s) to disable.
 274    * @see EnableGetureDetection
 275    */
 276   void DisableGestureDetection(Gesture::Type type);
 277
 278 private: // For derived classes to override
 279
 280   /**
 281    * @brief This method is called after the Control has been initialized.
 282    *
 283    * Derived classes should do any second phase initialization by
 284    * overriding this method.
 285    */
 286   virtual void OnInitialize() { }
 287
 288   /**
 289    * @brief This method should be overridden by deriving classes when
 290    * they wish to be notified when the style changes.
 291    *
 292    * @param[in] change  Information denoting what has changed.
 293    */
 294   virtual void OnStyleChange(StyleChange change) { }
 295
 296   /**
 297    * @brief Called whenever a pinch gesture is detected on this control.
 298    *
 299    * This can be overridden by deriving classes when pinch detection
 300    * is enabled.  The default behaviour is to scale the control by the
 301    * pinch scale.
 302    *
 303    * @note If overridden, then the default behaviour will not occur.
 304    * @note Pinch detection should be enabled via EnableGestureDetection().
 305    * @param[in]  pinch  The pinch gesture.
 306    * @see EnableGestureDetection
 307    */
 308   virtual void OnPinch(PinchGesture pinch);
 309
 310   /**
 311    * @brief Called whenever a pan gesture is detected on this control.
 312    *
 313    * This should be overridden by deriving classes when pan detection
 314    * is enabled.
 315    *
 316    * @note There is no default behaviour with panning.
 317    * @note Pan detection should be enabled via EnableGestureDetection().
 318    * @param[in]  pan  The pan gesture.
 319    * @see EnableGestureDetection
 320    */
 321   virtual void OnPan(PanGesture pan) { }
 322
 323   /**
 324    * @brief Called whenever a tap gesture is detected on this control.
 325    *
 326    * This should be overridden by deriving classes when tap detection
 327    * is enabled.
 328    *
 329    * @note There is no default behaviour with a tap.
 330    * @note Tap detection should be enabled via EnableGestureDetection().
 331    * @param[in]  tap  The tap gesture.
 332    * @see EnableGestureDetection
 333    */
 334   virtual void OnTap(TapGesture tap) { }
 335
 336   /**
 337    * @brief Called whenever a long press gesture is detected on this control.
 338    *
 339    * This should be overridden by deriving classes when long press
 340    * detection is enabled.
 341    *
 342    * @note There is no default behaviour associated with a long press.
 343    * @note Long press detection should be enabled via EnableGestureDetection().
 344    * @param[in]  longPress  The long press gesture.
 345    * @see EnableGestureDetection
 346    */
 347   virtual void OnLongPress(LongPressGesture longPress) { }
 348
 349   /**
 350    * @brief Called whenever the control is added to the stage.
 351    *
 352    * Could be overridden by derived classes.
 353    */
 354   virtual void OnControlStageConnection() { }
 355
 356   /**
 357    * @brief Called whenever the control is removed from the stage.
 358    *
 359    * Could be overridden by derived classes.
 360    */
 361   virtual void OnControlStageDisconnection() { }
 362
 363   /**
 364    * @brief Called whenever an Actor is added to the control.
 365    *
 366    * Could be overridden by derived classes.
 367    *
 368    * @param[in] child The added actor.
 369    */
 370   virtual void OnControlChildAdd( Actor& child ) { }
 371
 372   /**
 373    * @brief Called whenever an Actor is removed from the control.
 374    *
 375    * Could be overridden by derived classes.
 376    *
 377    * @param[in] child The removed actor.
 378    */
 379   virtual void OnControlChildRemove( Actor& child ) { }
 380
 381   /**
 382    * @brief Called whenever the Control's size is set.
 383    *
 384    * Could be overridden by derived classes.
 385    *
 386    * @param[in] size The new size.
 387    */
 388   virtual void OnControlSizeSet( const Vector3& size ) { }
 389
 390   /**
 391    * @brief Called after the Dali::Stage::SignalMessageQueueFlushed()
 392    * signal is emitted if this control requested to be relaid-out.
 393    *
 394    * Should be overridden by derived classes if they need to layout
 395    * actors differently after certain operations like add or remove
 396    * actors, resize or after changing especific properties.
 397    *
 398    * @param[in]      size       The allocated size.
 399    * @param[in,out]  container  The control should add actors to this container that it is not able
 400    *                            to allocate a size for.
 401    */
 402   virtual void OnRelaidOut( Vector2 size, ActorSizeContainer& container );
 403
 404 private: // From CustomActorImpl, derived classes can override these.
 405
 406   /**
 407    * @brief Sends a request to relayout this control.
 408    *
 409    * The control will be relaid out after the
 410    * Dali::Stage::SignalMessageQueueFlushed() signal is emitted.
 411    *
 412    * It calls OnControlStageConnection() to notify derived classes.
 413    *
 414    * @see Dali::CustomActorImpl::OnStageConnection()
 415    */
 416   virtual void OnStageConnection();
 417
 418   /**
 419    * @brief Calls OnControlStageDisconnection() to notify derived classed.
 420    *
 421    * @see Dali::CustomActorImpl::OnStageDisconnection()
 422    */
 423   virtual void OnStageDisconnection();
 424
 425   /**
 426    * @brief Sends a request to relayout this control.
 427    *
 428    * The control will be relaid out after the
 429    * Dali::Stage::SignalMessageQueueFlushed() signal is emitted.  It
 430    * calls OnControlChildAdd() to notify derived classes.
 431    *
 432    * @note This method shouldn't be overridden by derived classes.
 433    *
 434    * @param[in] child The added actor.
 435    *
 436    * @see Dali::CustomActorImpl::OnChildAdd(Actor&)
 437    */
 438   virtual void OnChildAdd(Actor& child);
 439
 440   /**
 441    * @brief Sends a request to relayout this control.
 442    *
 443    * The control will be relaid out after the
 444    * Dali::Stage::SignalMessageQueueFlushed() signal is emitted.  It
 445    * calls OnControlChildRemove() to notify derived classes.
 446    *
 447    * @note This method shouldn't be overridden by derived classes.
 448    *
 449    * @param[in] child The removed actor.
 450    *
 451    * @see Dali::CustomActorImpl::OnChildRemove(Actor&)
 452    */
 453   virtual void OnChildRemove(Actor& child);
 454
 455   /**
 456    * @brief It stores the size set by size negotiation and relayout.
 457    *
 458    * It also keeps a backup of the size set through the Actor's API used in the size negotiation.
 459    * It calls the OnControlSizeSet() to notify derived classes.
 460    *
 461    * @param[in] targetSize The new size.
 462    *
 463    * @see Dali::CustomActorImpl::OnSizeSet(const Vector3&)
 464    */
 465   virtual void OnSizeSet(const Vector3& targetSize);
 466
 467   /**
 468    * @copydoc Dali::CustomActorImpl::OnSizeAnimation(Animation&, const Vector3&)
 469    */
 470   virtual void OnSizeAnimation(Animation& animation, const Vector3& targetSize);
 471
 472   /**
 473    * @copydoc Dali::CustomActorImpl::OnTouchEvent(const TouchEvent&)
 474    */
 475   virtual bool OnTouchEvent(const TouchEvent& event);
 476
 477   /**
 478    * @copydoc Dali::CustomActorImpl::OnKeyEvent(const KeyEvent&)
 479    */
 480   virtual bool OnKeyEvent(const KeyEvent& event);
 481
 482   /**
 483    * @copydoc Dali::CustomActorImpl::OnMouseWheelEvent(const MouseWheelEvent&)
 484    */
 485   virtual bool OnMouseWheelEvent(const MouseWheelEvent& event);
 486
 487   /**
 488    * @copydoc Dali::CustomActorImpl::OnKeyInputFocusGained()
 489    */
 490   virtual void OnKeyInputFocusGained();
 491
 492   /**
 493    * @copydoc Dali::CustomActorImpl::OnKeyInputFocusLost()
 494    */
 495   virtual void OnKeyInputFocusLost();
 496
 497   /**
 498    * @copydoc Dali::CustomActorImpl::GetChildByAlias(const std::string& actorAlias)
 499    */
 500   virtual Actor GetChildByAlias(const std::string& actorAlias);
 501
 502 private:
 503
 504   /**
 505    * @brief Perform the activated action.
 506    *
 507    * @param[in] attributes The attributes to perfrom this action.
 508    */
 509   void DoActivatedAction(const PropertyValueContainer& attributes);
 510
 511 protected: // Construction
 512
 513   /**
 514    * @brief Create a ControlImpl.
 515    *
 516    * @param[in] requiresTouchEvents True if the OnTouchEvent() callback is required.
 517    */
 518   ControlImpl(bool requiresTouchEvents);
 519
 520 public:
 521
 522   // Size negotiation
 523
 524   /**
 525    * @copydoc Control::SetSizePolicy()
 526    */
 527   void SetSizePolicy( Control::SizePolicy widthPolicy, Control::SizePolicy heightPolicy );
 528
 529   /**
 530    * @copydoc Control::GetSizePolicy()
 531    */
 532   void GetSizePolicy( Control::SizePolicy& widthPolicy, Control::SizePolicy& heightPolicy ) const;
 533
 534   /**
 535    * @copydoc Control::SetMinimumSize()
 536    */
 537   void SetMinimumSize( const Vector3& size );
 538
 539   /**
 540    * @copydoc Control::GetMinimumSize()
 541    */
 542   const Vector3& GetMinimumSize() const;
 543
 544   /**
 545    * @copydoc Control::SetMaximumSize()
 546    */
 547   void SetMaximumSize( const Vector3& size );
 548
 549   /**
 550    * @copydoc Control::GetMaximumSize()
 551    */
 552   const Vector3& GetMaximumSize() const;
 553
 554   /**
 555    * @copydoc Control::GetNaturalSize()
 556    */
 557   virtual Vector3 GetNaturalSize();
 558
 559   /**
 560    * @copydoc Control::GetHeightForWidth()
 561    */
 562   virtual float GetHeightForWidth( float width );
 563
 564   /**
 565    * @copydoc Control::GetWidthForHeight()
 566    */
 567   virtual float GetWidthForHeight( float height );
 568
 569   /**
 570    * @brief Retrieves the current Control's size.
 571    *
 572    * @return The control's size.
 573    */
 574   const Vector3& GetControlSize() const;
 575
 576   /**
 577    * @brief Retrieves the Control's size set by the Application / Control.
 578    *
 579    * @return The control's size.
 580    */
 581   const Vector3& GetSizeSet() const;
 582
 583   //KeyInput
 584
 585   /**
 586    * @copydoc Control::SetKeyInputFocus()
 587    */
 588   void SetKeyInputFocus();
 589
 590   /**
 591    * @copydoc Control::HasKeyInputFocus()
 592    */
 593   bool HasKeyInputFocus();
 594
 595   /**
 596    * @copydoc Control::ClearKeyInputFocus()
 597    */
 598   void ClearKeyInputFocus();
 599
 600   /**
 601    * @copydoc ConnectionTrackerInterface::SignalConnected
 602    */
 603   virtual void SignalConnected( SlotObserver* slotObserver, CallbackBase* callback );
 604
 605   /**
 606    * @copydoc ConnectionTrackerInterface::SignalDisconnected
 607    */
 608   virtual void SignalDisconnected( SlotObserver* slotObserver, CallbackBase* callback );
 609
 610   /**
 611    * @copydoc ConnectionTrackerInterface::GetConnectionCount
 612    */
 613   virtual std::size_t GetConnectionCount() const;
 614
 615 protected:
 616
 617   /**
 618    * @brief Sends a request to be relaid-out.
 619    *
 620    * This method is called from OnStageConnection(), OnChildAdd(),
 621    * OnChildRemove(), SetSizePolicy(), SetMinimumSize() and
 622    * SetMaximumSize().
 623    *
 624    * This method could also be called from derived classes every time
 625    * a control's poperty change and it needs to be relaid-out.  After
 626    * the Dali::Stage::SignalMessageQueueFlushed() is emitted a
 627    * relayout process starts and all controls which called this method
 628    * will be relaid-out.
 629    *
 630    * @note RelayoutRequest() only sends a request per Control before
 631    * the Dali::Stage::SignalMessageQueueFlushed() signal is
 632    * emitted. That means a control will be relaid-out only once, even
 633    * if more than one request is sent between two consecutive signals.
 634    */
 635   void RelayoutRequest();
 636
 637   /**
 638    * @brief Helper method for controls to Relayout their children if
 639    * they do not know whether that child is a control or not.
 640    *
 641    * @param[in]      actor      The actor to relayout.
 642    * @param[in]      size       The size to allocate to the actor.
 643    * @param[in,out]  container  The container that holds actors that have not been allocated a size yet.
 644    */
 645   static void Relayout( Actor actor, Vector2 size, ActorSizeContainer& container );
 646
 647 private: // Used by the RelayoutController
 648
 649   /**
 650    * @brief Called by the RelayoutController to negotiate the size of a control.
 651    *
 652    * The size allocated by the the algorithm is passed in which the
 653    * control must adhere to.  A container is passed in as well which
 654    * the control should populate with actors it has not / or does not
 655    * need to handle in its size negotiation.
 656    *
 657    * @param[in]      size       The allocated size.
 658    * @param[in,out]  container  The container that holds actors that are fed back into the
 659    *                            RelayoutController algorithm.
 660    */
 661   void NegotiateSize( Vector2 size, ActorSizeContainer& container );
 662
 663 private:
 664
 665   /**
 666    * @brief Called by NegotiateSize when the size to allocate to the control has been calculated.
 667    *
 668    * It calls the OnRelaidOut() method which can be overridden by derived classes.
 669    *
 670    * @param[in]      size       The allocated size.
 671    * @param[in,out]  container  The control should add actors to this container that it is not able
 672    *                            to allocate a size for.
 673    */
 674   void Relayout( Vector2 size, ActorSizeContainer& container );
 675
 676   /**
 677    * @brief Used by the KeyInputFocusManager to emit key event signals.
 678    *
 679    * @param[in] event The key event.
 680    * @return True if the event was consumed.
 681    */
 682   bool EmitKeyEventSignal(const KeyEvent& event);
 683
 684
 685
 686 private:
 687
 688   // Undefined
 689   ControlImpl(const ControlImpl&);
 690   ControlImpl& operator=(const ControlImpl&);
 691
 692   class Impl;
 693   Impl *mImpl;
 694
 695   friend class Internal::StyleChangeProcessor;
 696   friend class Internal::RelayoutControllerImpl;   ///< Relayout controller needs to call Relayout() which is private.
 697   friend class Internal::KeyInputFocusManager;     ///< KeyInputFocusManager needs to call which is private.
 698 };
 699
 700 } // namespace Toolkit
 701
 702 } // namespace Dali
 703
 704 /**
 705  * @}
 706  */
 707 #endif // __DALI_TOOLKIT_CONTROL_IMPL_H__