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