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