capi/dali-toolkit/public-api/focus-manager/keyboard-focus-manager.h

   1 #ifndef __DALI_TOOLKIT_KEYBOARD_FOCUS_MANAGER_H__
   2 #define __DALI_TOOLKIT_KEYBOARD_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 #include <dali-toolkit/public-api/controls/control.h>
  28
  29 namespace Dali DALI_IMPORT_API
  30 {
  31
  32 namespace Toolkit
  33 {
  34
  35 namespace Internal DALI_INTERNAL
  36 {
  37 class KeyboardFocusManager;
  38 }
  39
  40 /**
  41  * @brief Provides the functionality of handling keyboard navigation
  42  * and maintaining the two dimensional keyboard focus chain.
  43  *
  44  * It provides functionality of setting the focus and moving the focus
  45  * in four directions (i.e. Left, Right, Up and Down). It also draws a
  46  * highlight for the focused actor and emits a signal when the focus
  47  * is changed.
  48  */
  49 class KeyboardFocusManager : public BaseHandle
  50 {
  51 public:
  52   //Signal Names
  53   static const char* const SIGNAL_PRE_FOCUS_CHANGE; ///< name "keyboard-pre-focus-change"
  54   static const char* const SIGNAL_FOCUS_CHANGED; ///< name "keyboard-focus-changed"
  55   static const char* const SIGNAL_FOCUS_GROUP_CHANGED; ///< name "keyboard-focus-group-changed"
  56   static const char* const SIGNAL_FOCUSED_ACTOR_ACTIVATED; ///< name "keyboard-focused-actor-activated"
  57
  58 public:
  59
  60   /// @brief Pre focus change signal
  61   typedef SignalV2< Actor ( Actor, Actor, Control::KeyboardFocusNavigationDirection ) > PreFocusChangeSignalV2;
  62
  63   /// @brief Focus changed signal
  64   typedef SignalV2< void ( Actor, Actor ) > FocusChangedSignalV2;
  65
  66   /// @brief Focus group changed signal
  67   typedef SignalV2< void ( Actor, bool ) > FocusGroupChangedSignalV2;
  68
  69   /// @brief Focused actor activated signal
  70   typedef SignalV2< void ( Actor ) > FocusedActorActivatedSignalV2;
  71
  72   /**
  73    * @brief Create a KeyboardFocusManager handle; this can be initialised with KeyboardFocusManager::New().
  74    *
  75    * Calling member functions with an uninitialised handle is not allowed.
  76    */
  77   KeyboardFocusManager();
  78
  79   /**
  80    * @brief Virtual destructor.
  81    */
  82   virtual ~KeyboardFocusManager();
  83
  84   /**
  85    * @brief Get the singleton of KeyboardFocusManager object.
  86    *
  87    * @return A handle to the KeyboardFocusManager control.
  88    */
  89   static KeyboardFocusManager Get();
  90
  91   /**
  92    * @brief Move the keyboard focus to the given actor.
  93    *
  94    * Only one actor can be focused at the same time.  The actor must
  95    * be in the stage already and keyboard focusable.
  96    *
  97    * @pre The KeyboardFocusManager has been initialized.
  98    * @pre The Actor has been initialized.
  99    * @param actor The actor to be focused
 100    * @return Whether the focus is successful or not
 101    */
 102   bool SetCurrentFocusActor(Actor actor);
 103
 104   /**
 105    * @brief Get the current focused actor.
 106    *
 107    * @pre The KeyboardFocusManager has been initialized.
 108    * @return A handle to the current focused actor or an empty handle if no actor is focused.
 109    */
 110   Actor GetCurrentFocusActor();
 111
 112   /**
 113    * @brief Move the focus to the next focusable actor in the focus
 114    * chain in the given direction (according to the focus traversal
 115    * order).
 116    *
 117    * @pre The KeyboardFocusManager has been initialized.
 118    * @param direction The direction of focus movement
 119    * @return true if the movement was successful
 120    */
 121   bool MoveFocus(Control::KeyboardFocusNavigationDirection direction);
 122
 123   /**
 124    * @brief Clear the focus from the current focused actor if any, so
 125    * that no actor is focused in the focus chain.
 126    *
 127    * It will emit focus changed signal without current focused actor
 128    * @pre The KeyboardFocusManager has been initialized.
 129    */
 130   void ClearFocus();
 131
 132   /**
 133    * @brief Set whether the focus movement should be looped within the same focus group.
 134    *
 135    * The focus movement is not looped by default.
 136    * @pre The KeyboardFocusManager has been initialized.
 137    * @param enabled Whether the focus movement should be looped
 138    */
 139   void SetFocusGroupLoop(bool enabled);
 140
 141   /**
 142    * @brief Get whether the focus movement should be looped within the same focus group.
 143    *
 144    * @pre The KeyboardFocusManager has been initialized.
 145    * @return Whether the focus movement should be looped
 146    */
 147   bool GetFocusGroupLoop() const;
 148
 149   /**
 150    * @brief Set whether an actor is a focus group that can limit the
 151    * scope of focus movement to its child actors in the focus chain.
 152    *
 153    * Layout controls set themselves as focus groups by default.
 154    *
 155    * @pre The KeyboardFocusManager has been initialized.
 156    * @pre The Actor has been initialized.
 157    * @param actor The actor to be set as a focus group.
 158    * @param isFocusGroup Whether to set the actor as a focus group or not.
 159    */
 160   void SetAsFocusGroup(Actor actor, bool isFocusGroup);
 161
 162   /**
 163    * @brief Check whether the actor is set as a focus group or not.
 164    *
 165    * @pre The KeyboardFocusManager has been initialized.
 166    * @pre The Actor has been initialized.
 167    * @param actor The actor to be checked.
 168    * @return Whether the actor is set as a focus group.
 169    */
 170   bool IsFocusGroup(Actor actor) const;
 171
 172   /**
 173    * @brief Returns the closest ancestor of the given actor that is a focus group.
 174    *
 175    * @param actor The actor to be checked for its focus group
 176    * @return The focus group the given actor belongs to or an empty handle if the given actor
 177    * doesn't belong to any focus group
 178    */
 179   Actor GetFocusGroup(Actor actor);
 180
 181   /**
 182    * @brief Set the focus indicator actor.
 183    *
 184    * This will replace the default focus indicator actor in
 185    * KeyboardFocusManager and will be added to the focused actor as a
 186    * highlight.
 187    *
 188    * @pre The KeyboardFocusManager has been initialized.
 189    * @pre The indicator actor has been initialized.
 190    * @param indicator The indicator actor to be added
 191    */
 192   void SetFocusIndicatorActor(Actor indicator);
 193
 194   /**
 195    * @brief Get the focus indicator actor.
 196    *
 197    * @pre The KeyboardFocusManager has been initialized.
 198    * @return A handle to the focus indicator actor
 199    */
 200   Actor GetFocusIndicatorActor();
 201
 202 public: // Signals
 203
 204   /**
 205    * @brief This signal is emitted before the focus is going to be changed.
 206    *
 207    * KeyboardFocusManager makes the best guess for which actor to
 208    * focus towards the given direction, but applications might want to
 209    * change that. By connecting with this signal, they can check the
 210    * proposed actor to focus and return a different actor if they
 211    * wish.  This signal is only emitted when the navigation key is
 212    * pressed and KeyboardFocusManager tries to move the focus
 213    * automatically. It won't be emitted for focus movement by calling
 214    * SetCurrentFocusActor directly.
 215    *
 216    * A callback of the following type may be connected:
 217    * @code
 218    *   Actor YourCallbackName(Actor currentFocusedActor, Actor proposedActorToFocus, Control::KeyboardFocusNavigationDirection direction);
 219    * @endcode
 220    * @pre The Object has been initialized.
 221    * @return The signal to connect to.
 222    */
 223   PreFocusChangeSignalV2& PreFocusChangeSignal();
 224
 225   /**
 226    * @brief This signal is emitted after the current focused actor has been changed.
 227    *
 228    * A callback of the following type may be connected:
 229    * @code
 230    *   void YourCallbackName(Actor originalFocusedActor, Actor currentFocusedActor);
 231    * @endcode
 232    * @pre The Object has been initialized.
 233    * @return The signal to connect to.
 234    */
 235   FocusChangedSignalV2& FocusChangedSignal();
 236
 237   /**
 238    * @brief This signal is emitted when the focus group has been changed.
 239    *
 240    * If the current focus group has a parent layout control,
 241    * KeyboardFocusManager will make the best guess for the next focus
 242    * group to move the focus to in the given direction (forward or
 243    * backward). If not, the application has to set the new focus.
 244    *
 245    * A callback of the following type may be connected:
 246    * @code
 247    *   void YourCallbackName(Actor currentFocusedActor, bool forward);
 248    * @endcode
 249    * @pre The Object has been initialized.
 250    * @return The signal to connect to.
 251    */
 252   FocusGroupChangedSignalV2& FocusGroupChangedSignal();
 253
 254   /**
 255    * @brief This signal is emitted when the current focused actor is activated.
 256    *
 257    * A callback of the following type may be connected:
 258    * @code
 259    *   void YourCallbackName(Actor activatedActor);
 260    * @endcode
 261    * @pre The Object has been initialized.
 262    * @return The signal to connect to.
 263    */
 264   FocusedActorActivatedSignalV2& FocusedActorActivatedSignal();
 265
 266   // Not intended for application developers
 267
 268   /**
 269    * @brief Creates a new handle from the implementation.
 270    *
 271    * @param[in] impl A pointer to the object.
 272    */
 273   explicit DALI_INTERNAL KeyboardFocusManager(Internal::KeyboardFocusManager *impl);
 274
 275 }; // class KeyboardFocusManager
 276
 277 } // namespace Toolkit
 278
 279 } // namespace Dali
 280
 281 /**
 282  * @}
 283  */
 284 #endif // __DALI_TOOLKIT_KEYBOARD_FOCUS_MANAGER_H__