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