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