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

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