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