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