base/dali-toolkit/internal/focus-manager/focus-manager-impl.h

   1 #ifndef __DALI_TOOLKIT_INTERNAL_FOCUS_MANAGER_H__
   2 #define __DALI_TOOLKIT_INTERNAL_FOCUS_MANAGER_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 // EXTERNAL INCLUDES
  21 #include <string>
  22
  23 // INTERNAL INCLUDES
  24 #include <dali/dali.h>
  25 #include <dali-toolkit/public-api/focus-manager/focus-manager.h>
  26
  27 namespace Dali
  28 {
  29
  30 namespace Toolkit
  31 {
  32
  33 namespace Internal
  34 {
  35
  36 class FocusManager;
  37
  38 /**
  39  * @copydoc Toolkit::FocusManager
  40  */
  41 class FocusManager : public Dali::BaseObject, Dali::AccessibilityActionHandler, Dali::AccessibilityGestureHandler
  42 {
  43 public:
  44
  45   struct ActorAdditionalInfo
  46   {
  47     ActorAdditionalInfo()
  48     : mFocusOrder(0)
  49     {
  50     }
  51
  52     unsigned int mFocusOrder; ///< The focus order of the actor. It is undefined by default.
  53
  54     std::string mAccessibilityAttributes[Toolkit::FocusManager::ACCESSIBILITY_ATTRIBUTE_NUM]; ///< The array of attribute texts
  55   };
  56
  57   typedef std::pair<unsigned int, unsigned int>        FocusIDPair;
  58   typedef std::map<unsigned int, unsigned int>         FocusIDContainer;
  59   typedef FocusIDContainer::iterator                   FocusIDIter;
  60   typedef FocusIDContainer::const_iterator             FocusIDConstIter;
  61
  62   typedef std::pair<unsigned int, ActorAdditionalInfo> IDAdditionalInfoPair;
  63   typedef std::map<unsigned int, ActorAdditionalInfo>  IDAdditionalInfoContainer;
  64   typedef IDAdditionalInfoContainer::iterator          IDAdditionalInfoIter;
  65   typedef IDAdditionalInfoContainer::const_iterator    IDAdditionalInfoConstIter;
  66
  67   /**
  68    * Construct a new FocusManager.
  69    */
  70   FocusManager();
  71
  72   /**
  73    * @copydoc Toolkit::FocusManager::SetAccessibilityAttribute
  74    */
  75   void SetAccessibilityAttribute(Actor actor, Toolkit::FocusManager::AccessibilityAttribute type, const std::string& text);
  76
  77   /**
  78    * @copydoc Toolkit::FocusManager::GetAccessibilityAttribute
  79    */
  80   std::string GetAccessibilityAttribute(Actor actor, Toolkit::FocusManager::AccessibilityAttribute type) const;
  81
  82   /**
  83    * @copydoc Toolkit::FocusManager::SetFocusOrder
  84    */
  85   void SetFocusOrder(Actor actor, const unsigned int order);
  86
  87   /**
  88    * @copydoc Toolkit::FocusManager::GetFocusOrder
  89    */
  90   unsigned int GetFocusOrder(Actor actor) const;
  91
  92   /**
  93    * @copydoc Toolkit::FocusManager::GenerateNewFocusOrder
  94    */
  95   unsigned int GenerateNewFocusOrder() const;
  96
  97   /**
  98    * @copydoc Toolkit::FocusManager::GetActorByFocusOrder
  99    */
 100   Actor GetActorByFocusOrder(const unsigned int order);
 101
 102   /**
 103    * @copydoc Toolkit::FocusManager::SetCurrentFocusActor
 104    */
 105   bool SetCurrentFocusActor(Actor actor);
 106
 107   /**
 108    * @copydoc Toolkit::FocusManager::GetCurrentFocusActor
 109    */
 110   Actor GetCurrentFocusActor();
 111
 112   /**
 113    * @copydoc Toolkit::FocusManager::GetCurrentFocusGroup
 114    */
 115   Actor GetCurrentFocusGroup();
 116
 117   /**
 118    * @copydoc Toolkit::FocusManager::GetCurrentFocusOrder
 119    */
 120   unsigned int GetCurrentFocusOrder();
 121
 122   /**
 123    * @copydoc Toolkit::FocusManager::MoveFocusForward
 124    */
 125   bool MoveFocusForward();
 126
 127   /**
 128    * @copydoc Toolkit::FocusManager::MoveFocusBackward
 129    */
 130   bool MoveFocusBackward();
 131
 132   /**
 133    * @copydoc Toolkit::FocusManager::ClearFocus
 134    */
 135   void ClearFocus();
 136
 137   /**
 138    * @copydoc Toolkit::FocusManager::Reset
 139    */
 140   void Reset();
 141
 142   /**
 143    * @copydoc Toolkit::FocusManager::SetFocusGroup
 144    */
 145   void SetFocusGroup(Actor actor, bool isFocusGroup);
 146
 147   /**
 148    * @copydoc Toolkit::FocusManager::IsFocusGroup
 149    */
 150   bool IsFocusGroup(Actor actor) const;
 151
 152   /**
 153    * @copydoc Toolkit::FocusManager::SetGroupMode
 154    */
 155   void SetGroupMode(bool enabled);
 156
 157   /**
 158    * @copydoc Toolkit::FocusManager::GetGroupMode
 159    */
 160   bool GetGroupMode() const;
 161
 162   /**
 163    * @copydoc Toolkit::FocusManager::SetWrapMode
 164    */
 165   void SetWrapMode(bool wrapped);
 166
 167   /**
 168    * @copydoc Toolkit::FocusManager::GetWrapMode
 169    */
 170   bool GetWrapMode() const;
 171
 172   /**
 173    * @copydoc Toolkit::FocusManager::SetEndCapFeedbackEnabled
 174    */
 175   void SetEndCapFeedbackEnabled(bool enabled);
 176
 177   /**
 178    * @copydoc Toolkit::FocusManager::GetEndCapFeedbackEnabled
 179    */
 180   bool GetEndCapFeedbackEnabled() const;
 181
 182   /**
 183    * @copydoc Toolkit::FocusManager::SetFocusIndicatorActor
 184    */
 185   void SetFocusIndicatorActor(Actor indicator);
 186
 187   /**
 188    * @copydoc Toolkit::FocusManager::GetFocusIndicatorActor
 189    */
 190   Actor GetFocusIndicatorActor();
 191
 192   /**
 193    * @copydoc Toolkit::FocusManager::GetFocusGroup
 194    */
 195   Actor GetFocusGroup(Actor actor);
 196
 197 public:
 198
 199   /**
 200    * @copydoc Toolkit::FocusManager::FocusChangedSignal()
 201    */
 202   Toolkit::FocusManager::FocusChangedSignalV2& FocusChangedSignal();
 203
 204   /**
 205    * @copydoc Toolkit::FocusManager::FocusOvershotSignal()
 206    */
 207   Toolkit::FocusManager::FocusOvershotSignalV2& FocusOvershotSignal();
 208
 209   /**
 210    * @copydoc Toolkit::FocusManager::FocusedActorActivatedSignal()
 211    */
 212   Toolkit::FocusManager::FocusedActorActivatedSignalV2& FocusedActorActivatedSignal();
 213
 214   /**
 215    * Connects a callback function with the object's signals.
 216    * @param[in] object The object providing the signal.
 217    * @param[in] tracker Used to disconnect the signal.
 218    * @param[in] signalName The signal to connect to.
 219    * @param[in] functor A newly allocated FunctorDelegate.
 220    * @return True if the signal was connected.
 221    * @post If a signal was connected, ownership of functor was passed to CallbackBase. Otherwise the caller is responsible for deleting the unused functor.
 222    */
 223   static bool DoConnectSignal( BaseObject* object, ConnectionTrackerInterface* tracker, const std::string& signalName, FunctorDelegate* functor );
 224
 225 protected:
 226
 227   /**
 228    * Destructor
 229    */
 230   virtual ~FocusManager();
 231
 232 private:
 233
 234   /**
 235    * Get the additional information (e.g. focus order and description) of the given actor.
 236    * @param actorID The ID of the actor to be queried
 237    * @return The additional information of the actor
 238    */
 239   ActorAdditionalInfo GetActorAdditionalInfo(const unsigned int actorID) const;
 240
 241   /**
 242    * Synchronize the actor's additional information to reflect its latest focus order
 243    * @param actorID The ID of the actor
 244    * @param order The focus order of the actor
 245    * @return The additional information of the actor
 246    */
 247   void SynchronizeActorAdditionalInfo(const unsigned int actorID, const unsigned int order);
 248
 249   /**
 250    * Move the focus to the specified actor and send notification for the focus change.
 251    * @param actorID The ID of the actor to be queried
 252    * @return Whether the focus is successful or not
 253    */
 254   bool DoSetCurrentFocusActor(const unsigned int actorID);
 255
 256   /**
 257    * Move the focus to the next actor in the focus chain towards the specified direction.
 258    * @param focusIDIter The iterator pointing to the current focused actor
 259    * @param forward Whether the focus movement is forward or not. The focus movement will be backward if this is false.
 260    * @param wrapped Whether the focus shoule be moved wrapped around or not
 261    * @return Whether the focus is successful or not
 262    */
 263   bool DoMoveFocus(FocusIDIter focusIDIter, bool forward, bool wrapped);
 264
 265   /**
 266    * Activate the actor. If the actor is control, call OnActivated virtual function.
 267    * This function will emit FocusedActorActivatedSignal.
 268    * @param actor The actor to activate
 269    */
 270   void DoActivate(Actor actor);
 271
 272   /**
 273    * Create the default indicator actor to highlight the focused actor.
 274    */
 275   void CreateDefaultFocusIndicatorActor();
 276
 277   /**
 278    * Set whether the actor is focusable or not. A focusable property will be registered for
 279    * the actor if not yet.
 280    * @param actor The actor to be focused
 281    * @param focusable Whether the actor is focusable or not
 282    */
 283   void SetFocusable(Actor actor, bool focusable);
 284
 285   /**
 286    * Handle the accessibility pan gesture.
 287    * @param[in]  panEvent  The pan event to be handled.
 288    * @return whether the gesture is handled successfully or not.
 289    */
 290   virtual bool HandlePanGesture(const Integration::PanGestureEvent& panEvent);
 291
 292   /**
 293    * Change the accessibility status when Accessibility feature(screen-reader) turned on or off.
 294    * @return whether the status is changed or not.
 295    */
 296   virtual bool ChangeAccessibilityStatus();
 297
 298   /**
 299    * Clear the accessibility focus from the current focused actor.
 300    * @return whether the focus is cleared or not.
 301    */
 302   virtual bool ClearAccessibilityFocus();
 303
 304   /**
 305    * Perform the accessibility action to move focus to the previous focusable actor (by one finger flick up).
 306    * @return whether the accessibility action is performed or not.
 307    */
 308   virtual bool AccessibilityActionPrevious();
 309
 310   /**
 311    * Perform the accessibility action to move focus to the next focusable actor (by one finger flick down).
 312    * @return whether the accessibility action is performed or not.
 313    */
 314   virtual bool AccessibilityActionNext();
 315
 316   /**
 317    * Perform the accessibility action to move focus to the previous focusable actor (by one finger flick left).
 318    * @return whether the accessibility action is performed or not.
 319    */
 320   virtual bool AccessibilityActionReadPrevious();
 321
 322   /**
 323    * Perform the accessibility action to move focus to the next focusable actor (by one finger flick right).
 324    * @return whether the accessibility action is performed or not.
 325    */
 326   virtual bool AccessibilityActionReadNext();
 327
 328   /**
 329    * Perform the accessibility action to focus and read the actor (by one finger tap or move).
 330    * @param allowReadAgain true if the action read again the same object (i.e. read action)
 331    *                       false if the action just read when the focus object is changed (i.e. over action)
 332    * @return whether the accessibility action is performed or not.
 333    */
 334   virtual bool AccessibilityActionRead(bool allowReadAgain);
 335
 336   /**
 337    * Perform the accessibility action to activate the current focused actor (by one finger double tap).
 338    * @return whether the accessibility action is performed or not.
 339    */
 340   virtual bool AccessibilityActionActivate();
 341
 342   /**
 343    * Perform the accessibility action to change the value when the current focused actor is a slider
 344    * (by double finger down and move up and right).
 345    * @return whether the accessibility action is performed or not.
 346    */
 347   virtual bool AccessibilityActionUp();
 348
 349   /**
 350    * Perform the accessibility action to change the value when the current focused actor is a slider
 351    * (by double finger down and move down and left).
 352    * @return whether the accessibility action is performed or not.
 353    */
 354   virtual bool AccessibilityActionDown();
 355
 356   /**
 357    * Perform the accessibility action to navigate back (by two fingers circle draw).
 358    * @return whether the accessibility action is performed or not.
 359    */
 360   virtual bool AccessibilityActionBack();
 361
 362 private:
 363
 364   // Undefined
 365   FocusManager(const FocusManager&);
 366
 367   FocusManager& operator=(const FocusManager& rhs);
 368
 369 private:
 370
 371   Toolkit::FocusManager::FocusChangedSignalV2 mFocusChangedSignalV2; ///< The signal to notify the focus change
 372   Toolkit::FocusManager::FocusOvershotSignalV2 mFocusOvershotSignalV2; ///< The signal to notify the focus overshooted
 373   Toolkit::FocusManager::FocusedActorActivatedSignalV2 mFocusedActorActivatedSignalV2; ///< The signal to notify the activation of focused actor
 374
 375   bool mIsWrapped; ///< Whether the focus movement is wrapped around or not
 376   bool mIsFocusWithinGroup; ///< Whether the focus movement is limited to the current focus group or not
 377
 378   bool mIsEndcapFeedbackEnabled; ///< Whether the endcap feedback need to be played when the focus leaves the end or vice versa
 379   bool mIsEndcapFeedbackPlayed; ///< Whether the endcap feedback was played or not
 380
 381   FocusIDContainer mFocusIDContainer; ///< The container to look up actor ID by focus order
 382   IDAdditionalInfoContainer mIDAdditionalInfoContainer; ///< The container to look up additional information by actor ID
 383
 384   FocusIDPair mCurrentFocusActor; ///< The focus order and actor ID of current focused actor
 385   Actor mCurrentGesturedActor; ///< The actor that will handle the gesture
 386
 387   Actor mFocusIndicatorActor; ///< The focus indicator actor shared by all the focusable actors for highlight
 388
 389   Vector2 mPreviousPosition; ///< The previous pan position; useful for calculating velocity for Gesture::Finished events
 390
 391   unsigned int mRecursiveFocusMoveCounter; ///< The counter to count the number of recursive focus movement attempted before the focus movement is successful.
 392
 393   bool mIsAccessibilityTtsEnabled; ///< Whether accessibility feature(screen-reader) turned on/off
 394
 395   bool mIsFocusIndicatorEnabled; ///< Whether indicator should be shown / hidden. It could be enabled when TTS enabled or 'Tab' key operated.
 396 };
 397
 398 } // namespace Internal
 399
 400 inline Internal::FocusManager& GetImpl(Dali::Toolkit::FocusManager& obj)
 401 {
 402   DALI_ASSERT_ALWAYS(obj);
 403
 404   Dali::BaseObject& handle = obj.GetBaseObject();
 405
 406   return static_cast<Internal::FocusManager&>(handle);
 407 }
 408
 409 inline const Internal::FocusManager& GetImpl(const Dali::Toolkit::FocusManager& obj)
 410 {
 411   DALI_ASSERT_ALWAYS(obj);
 412
 413   const Dali::BaseObject& handle = obj.GetBaseObject();
 414
 415   return static_cast<const Internal::FocusManager&>(handle);
 416 }
 417
 418 } // namespace Toolkit
 419
 420 } // namespace Dali
 421
 422 #endif // __DALI_TOOLKIT_INTERNAL_FOCUS_MANAGER_H__