dali-toolkit/public-api/focus-manager/accessibility-focus-manager.h

   1 #ifndef __DALI_TOOLKIT_ACCESSIBILITY_FOCUS_MANAGER_H__
   2 #define __DALI_TOOLKIT_ACCESSIBILITY_FOCUS_MANAGER_H__
   3
   4 /*
   5  * Copyright (c) 2015 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 <dali/public-api/actors/actor.h>
  23 #include <dali/public-api/actors/image-actor.h>
  24
  25 namespace Dali
  26 {
  27
  28 namespace Toolkit
  29 {
  30
  31 namespace Internal DALI_INTERNAL
  32 {
  33 class AccessibilityFocusManager;
  34 }
  35
  36 /**
  37  * @brief Manages registration of actors in a accessibility focus chain and changing the
  38  * focused actor within that chain.
  39  *
  40  * This class provides the functionality of registering the focus order and description
  41  * of actors and maintaining the focus chain.
  42  *
  43  * It provides functionality of setting the
  44  * focus and moving the focus forward and backward. It also draws a highlight for the
  45  * focused actor and emits a signal when the focus is changed.
  46  *
  47  * Signals
  48  * | %Signal Name            | Method                             |
  49  * |-------------------------|------------------------------------|
  50  * | focus-changed           | @ref FocusChangedSignal()          |
  51  * | focus-overshot          | @ref FocusOvershotSignal()         |
  52  * | focused-actor-activated | @ref FocusedActorActivatedSignal() |
  53  */
  54 class DALI_IMPORT_API AccessibilityFocusManager : public BaseHandle
  55 {
  56 public:
  57
  58   /**
  59    * @brief Accessibility needs four information which will be read by screen-reader.
  60    *
  61    * Reading order : Label -> Trait -> Optional (Value and Hint)
  62    */
  63   enum AccessibilityAttribute
  64   {
  65     ACCESSIBILITY_LABEL = 0, ///< Simple text which contained in ui-control
  66     ACCESSIBILITY_TRAIT,     ///< Description of ui-control trait
  67     ACCESSIBILITY_VALUE,     ///< Current value of ui-control (Optional)
  68     ACCESSIBILITY_HINT,      ///< Hint for action (Optional)
  69     ACCESSIBILITY_ATTRIBUTE_NUM ///< Number of attributes
  70   };
  71
  72    /**
  73     * @brief Overshoot direction.
  74     */
  75   enum FocusOvershotDirection
  76   {
  77     OVERSHOT_PREVIOUS = -1, ///< Try to move previous of the first actor
  78     OVERSHOT_NEXT = 1,      ///< Try to move next of the last actor
  79   };
  80
  81  public:
  82
  83   /// @brief Focus changed signal
  84   typedef Signal< void ( Actor, Actor ) > FocusChangedSignalType;
  85
  86   /// @brief Focus overshooted signal
  87   typedef Signal< void ( Actor, FocusOvershotDirection ) > FocusOvershotSignalType;
  88
  89   /// @brief Focused actor activated signal
  90   typedef Signal< void ( Actor ) > FocusedActorActivatedSignalType;
  91
  92   /**
  93    * @brief Create a AccessibilityFocusManager handle; this can be initialised with AccessibilityFocusManager::New().
  94    *
  95    * Calling member functions with an uninitialised handle is not allowed.
  96    */
  97   AccessibilityFocusManager();
  98
  99   /**
 100    * @brief Destructor
 101    *
 102    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 103    */
 104   ~AccessibilityFocusManager();
 105
 106   /**
 107    * @brief Get the singleton of AccessibilityFocusManager object.
 108    *
 109    * @return A handle to the AccessibilityFocusManager control.
 110    */
 111   static AccessibilityFocusManager Get();
 112
 113   /**
 114    * @brief Set the information of the specified actor's accessibility attribute.
 115    *
 116    * @pre The AccessibilityFocusManager has been initialized.
 117    * @pre The Actor has been initialized.
 118    * @param actor The actor the text to be set with
 119    * @param type The attribute type the text to be set with
 120    * @param text The text for the actor's accessibility information
 121    */
 122   void SetAccessibilityAttribute(Actor actor, AccessibilityAttribute type, const std::string& text);
 123
 124   /**
 125    * @brief Get the text of the specified actor's accessibility attribute.
 126    *
 127    * @pre The AccessibilityFocusManager has been initialized.
 128    * @pre The Actor has been initialized.
 129    * @param actor The actor to be queried
 130    * @param type The attribute type to be queried
 131    * @return The text of the actor's accessibility information
 132    */
 133   std::string GetAccessibilityAttribute(Actor actor, AccessibilityAttribute type) const;
 134
 135   /**
 136    * @brief Set the focus order of the actor.
 137    *
 138    * The focus order of each actor in the focus chain is unique. If
 139    * there is another actor assigned with the same focus order
 140    * already, the new actor will be inserted to the focus chain with
 141    * that focus order, and the focus order of the original actor and
 142    * all the actors followed in the focus chain will be increased
 143    * accordingly. If the focus order assigned to the actor is 0, it
 144    * means that actor's focus order is undefined (e.g. the actor has a
 145    * description but with no focus order being set yet) and therefore
 146    * that actor is not focusable.
 147    *
 148    * @pre The AccessibilityFocusManager has been initialized.
 149    * @pre The Actor has been initialized.
 150    * @param actor The actor the focus order to be set with
 151    * @param order The focus order of the actor
 152    */
 153   void SetFocusOrder(Actor actor, const unsigned int order);
 154
 155   /**
 156    * @brief Get the focus order of the actor.
 157    *
 158    * When the focus order is 0, it means the focus order of the actor
 159    * is undefined.
 160    *
 161    * @pre The AccessibilityFocusManager has been initialized.
 162    * @pre The Actor has been initialized.
 163    * @param actor The actor to be queried
 164    * @return The focus order of the actor
 165    */
 166   unsigned int GetFocusOrder(Actor actor) const;
 167
 168   /**
 169    * @brief Generates a new focus order number which can be used to
 170    * assign to actors which need to be appended to the end of the
 171    * current focus order chain.
 172    *
 173    * The new number will be an increment over the very last focus
 174    * order number in the focus chain. If the focus chain is empty then
 175    * the function returns 1, else the number returned will be FOLast +
 176    * 1 where FOLast is the focus order of the very last control in the
 177    * focus chain.
 178    *
 179    * @pre The AccessibilityFocusManager has been initialized.
 180    * @return The focus order of the actor
 181    */
 182   unsigned int GenerateNewFocusOrder() const;
 183
 184   /**
 185    * @brief Get the actor that has the specified focus order.
 186    *
 187    * It will return an empty handle if the actor is not in the stage
 188    * or has a focus order of 0.
 189    *
 190    * @pre The AccessibilityFocusManager has been initialized.
 191    * @param order The focus order of the actor
 192    *
 193    * @return The actor that has the specified focus order or an empty
 194    * handle if no actor in the stage has the specified focus order.
 195    */
 196   Actor GetActorByFocusOrder(const unsigned int order);
 197
 198   /**
 199    * @brief Move the focus to the specified actor.
 200    *
 201    * Only one actor can be focused at the same time.  The actor must
 202    * have a defined focus order and must be focusable, visible and in
 203    * the stage.
 204    *
 205    * @pre The AccessibilityFocusManager has been initialized.
 206    * @pre The Actor has been initialized.
 207    * @param actor The actor to be focused
 208    * @return Whether the focus is successful or not
 209    */
 210   bool SetCurrentFocusActor(Actor actor);
 211
 212   /**
 213    * @brief Get the current focused actor.
 214    *
 215    * @pre The AccessibilityFocusManager has been initialized.
 216    * @return A handle to the current focused actor or an empty handle if no actor is focused.
 217    */
 218   Actor GetCurrentFocusActor();
 219
 220   /**
 221    * @brief Get the focus group of current focused actor.
 222    *
 223    * @pre The AccessibilityFocusManager has been initialized.
 224    *
 225    * @return A handle to the immediate parent of the current focused
 226    * actor which is also a focus group, or an empty handle if no actor
 227    * is focused.
 228    */
 229   Actor GetCurrentFocusGroup();
 230
 231   /**
 232    * @brief Get the focus order of currently focused actor.
 233    * @pre The AccessibilityFocusManager has been initialized.
 234    *
 235    * @return The focus order of the currently focused actor or 0 if no
 236    * actor is in focus.
 237    */
 238   unsigned int GetCurrentFocusOrder();
 239
 240   /**
 241    * @brief Move the focus to the next focusable actor in the focus
 242    * chain (according to the focus traversal order).
 243    *
 244    * When the focus movement is wrapped around, the focus will be moved
 245    * to the first focusable actor when it reaches the end of the focus chain.
 246    *
 247    * @pre The AccessibilityFocusManager has been initialized.
 248    * @return true if the moving was successful
 249    */
 250   bool MoveFocusForward();
 251
 252   /**
 253    * @brief Move the focus to the previous focusable actor in the
 254    * focus chain (according to the focus traversal order).
 255    *
 256    * When the focus movement is wrapped around, the focus will be
 257    * moved to the last focusable actor when it reaches the beginning
 258    * of the focus chain.
 259    *
 260    * @pre The AccessibilityFocusManager has been initialized.
 261    * @return true if the moving was successful
 262    */
 263   bool MoveFocusBackward();
 264
 265   /**
 266    * @brief Clear the focus from the current focused actor if any, so
 267    * that no actor is focused in the focus chain.
 268    *
 269    * It will emit focus changed signal without current focused actor
 270    * @pre The AccessibilityFocusManager has been initialized.
 271    */
 272   void ClearFocus();
 273
 274   /**
 275    * @brief Clear the every registered focusable actor from focus-manager.
 276    * @pre The AccessibilityFocusManager has been initialized.
 277    */
 278   void Reset();
 279
 280   /**
 281    * @brief Set whether an actor is a focus group that can limit the
 282    * scope of focus movement to its child actors in the focus chain.
 283    *
 284    * @pre The AccessibilityFocusManager has been initialized.
 285    * @pre The Actor has been initialized.
 286    * @param actor The actor to be set as a focus group.
 287    * @param isFocusGroup Whether to set the actor to be a focus group or not.
 288    */
 289   void SetFocusGroup(Actor actor, bool isFocusGroup);
 290
 291   /**
 292    * @brief Check whether the actor is set as a focus group or not.
 293    *
 294    * @pre The AccessibilityFocusManager has been initialized.
 295    * @pre The Actor has been initialized.
 296    * @param actor The actor to be checked.
 297    * @return Whether the actor is set as a focus group.
 298    */
 299   bool IsFocusGroup(Actor actor) const;
 300
 301   /**
 302    * @brief Set whether the group mode is enabled or not.
 303    *
 304    * When the group mode is enabled, the focus movement will be limited to the child actors
 305    * of the current focus group including the current focus group itself. The current focus
 306    * group is the closest ancestor of the current focused actor that set as a focus group.
 307    * @pre The AccessibilityFocusManager has been initialized.
 308    * @param enabled Whether the group mode is enabled or not
 309    */
 310   void SetGroupMode(bool enabled);
 311
 312   /**
 313    * @brief Get whether the group mode is enabled or not.
 314    *
 315    * @pre The AccessibilityFocusManager has been initialized.
 316    * @return Whether the group mode is enabled or not.
 317    */
 318   bool GetGroupMode() const;
 319
 320   /**
 321    * @brief Set whether focus will be moved to the beginning of the
 322    * focus chain when it reaches the end or vice versa.
 323    *
 324    * When both the wrap mode and the group mode are enabled, focus will be
 325    * wrapped within the current focus group. Focus will not be wrapped in default.
 326    * @pre The AccessibilityFocusManager has been initialized.
 327    * @param wrapped Whether the focus movement is wrapped around or not
 328    */
 329   void SetWrapMode(bool wrapped);
 330
 331   /**
 332    * @brief Get whether the wrap mode is enabled or not.
 333    *
 334    * @pre The AccessibilityFocusManager has been initialized.
 335    * @return Whether the wrap mode is enabled or not.
 336    */
 337   bool GetWrapMode() const;
 338
 339   /**
 340    * @brief Set the focus indicator actor.
 341    *
 342    * This will replace the default focus indicator actor in
 343    * AccessibilityFocusManager and will be added to the focused actor as a
 344    * highlight.
 345    *
 346    * @pre The AccessibilityFocusManager has been initialized.
 347    * @pre The indicator actor has been initialized.
 348    * @param indicator The indicator actor to be added
 349    */
 350   void SetFocusIndicatorActor(Actor indicator);
 351
 352   /**
 353    * @brief Get the focus indicator actor.
 354    *
 355    * @pre The AccessibilityFocusManager has been initialized.
 356    * @return A handle to the focus indicator actor
 357    */
 358   Actor GetFocusIndicatorActor();
 359
 360   /**
 361    * @brief Returns the closest ancestor of the given actor that is a focus group.
 362    *
 363    * @param actor The actor to be checked for its focus group
 364    * @return The focus group the given actor belongs to or an empty handle if the given actor doesn't belong to any focus group
 365    */
 366   Actor GetFocusGroup(Actor actor);
 367
 368  public: // Signals
 369
 370   /**
 371    * @brief This signal is emitted when the current focused actor is changed.
 372    *
 373    * A callback of the following type may be connected:
 374    * @code
 375    *   void YourCallbackName(Actor originalFocusedActor, Actor currentFocusedActor);
 376    * @endcode
 377    * @pre The Object has been initialized.
 378    * @return The signal to connect to.
 379    */
 380   FocusChangedSignalType& FocusChangedSignal();
 381
 382   /**
 383    * @brief This signal is emitted when there is no way to move focus further.
 384    *
 385    * A callback of the following type may be connected:
 386    * @code
 387    *   void YourCallbackName(Actor currentFocusedActor, FocusOvershotDirection direction);
 388    * @endcode
 389    * @pre The Object has been initialized.
 390    * @return The signal to connect to.
 391    */
 392   FocusOvershotSignalType& FocusOvershotSignal();
 393
 394   /**
 395    * @brief This signal is emitted when the current focused actor is activated.
 396    *
 397    * A callback of the following type may be connected:
 398    * @code
 399    *   void YourCallbackName(Actor activatedActor);
 400    * @endcode
 401    * @pre The Object has been initialized.
 402    * @return The signal to connect to.
 403    */
 404   FocusedActorActivatedSignalType& FocusedActorActivatedSignal();
 405
 406 private:
 407
 408   explicit DALI_INTERNAL AccessibilityFocusManager(Internal::AccessibilityFocusManager *impl);
 409
 410 }; // class AccessibilityFocusManager
 411
 412 } // namespace Toolkit
 413
 414 } // namespace Dali
 415
 416 #endif // __DALI_TOOLKIT_FOCUS_MANAGER_H__