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