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