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