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    * @note If the parent of this actor has the KEYBOARD FOCUSABLE CHILDREN property set to false, it will not be focused.
 106    */
 107   bool SetCurrentFocusActor(Actor actor);
 108
 109   /**
 110    * @brief Gets the current focused actor.
 111    *
 112    * @SINCE_1_0.0
 113    * @return A handle to the current focused actor or an empty handle if no actor is focused
 114    * @pre The KeyboardFocusManager has been initialized.
 115    */
 116   Actor GetCurrentFocusActor();
 117
 118   /**
 119    * @brief Moves the focus to the next focusable actor in the focus
 120    * chain in the given direction (according to the focus traversal
 121    * order).
 122    *
 123    * @SINCE_1_0.0
 124    * @param direction The direction of focus movement
 125    * @return true if the movement was successful
 126    * @pre The KeyboardFocusManager has been initialized.
 127    */
 128   bool MoveFocus(Control::KeyboardFocus::Direction direction);
 129
 130   /**
 131    * @brief Clears the focus from the current focused actor if any, so
 132    * that no actor is focused in the focus chain.
 133    *
 134    * It will emit focus changed signal without current focused actor.
 135    * @SINCE_1_0.0
 136    * @pre The KeyboardFocusManager has been initialized.
 137    */
 138   void ClearFocus();
 139
 140   /**
 141    * @brief Sets whether the focus movement should be looped within the same focus group.
 142    *
 143    * The focus movement is not looped by default.
 144    * @SINCE_1_0.0
 145    * @param enabled Whether the focus movement should be looped
 146    * @pre The KeyboardFocusManager has been initialized.
 147    */
 148   void SetFocusGroupLoop(bool enabled);
 149
 150   /**
 151    * @brief Gets whether the focus movement should be looped within the same focus group.
 152    *
 153    * @SINCE_1_0.0
 154    * @return Whether the focus movement should be looped
 155    * @pre The KeyboardFocusManager has been initialized.
 156    */
 157   bool GetFocusGroupLoop() const;
 158
 159   /**
 160    * @brief Sets whether an actor is a focus group that can limit the
 161    * scope of focus movement to its child actors in the focus chain.
 162    *
 163    * Layout controls set themselves as focus groups by default.
 164    *
 165    * @SINCE_1_0.0
 166    * @param actor The actor to be set as a focus group
 167    * @param isFocusGroup Whether to set the actor as a focus group or not
 168    * @pre The KeyboardFocusManager has been initialized.
 169    * @pre The Actor has been initialized.
 170    */
 171   void SetAsFocusGroup(Actor actor, bool isFocusGroup);
 172
 173   /**
 174    * @brief Checks whether the actor is set as a focus group or not.
 175    *
 176    * @SINCE_1_0.0
 177    * @param actor The actor to be checked
 178    * @return Whether the actor is set as a focus group
 179    * @pre The KeyboardFocusManager has been initialized.
 180    * @pre The Actor has been initialized.
 181    */
 182   bool IsFocusGroup(Actor actor) const;
 183
 184   /**
 185    * @brief Returns the closest ancestor of the given actor that is a focus group.
 186    *
 187    * @SINCE_1_0.0
 188    * @param actor The actor to be checked for its focus group
 189    * @return The focus group the given actor belongs to or an empty handle if the given actor
 190    * doesn't belong to any focus group
 191    */
 192   Actor GetFocusGroup(Actor actor);
 193
 194   /**
 195    * @brief Sets the focus indicator actor.
 196    *
 197    * This will replace the default focus indicator actor in
 198    * KeyboardFocusManager and will be added to the focused actor as a
 199    * highlight.
 200    *
 201    * @SINCE_1_0.0
 202    * @param indicator The indicator actor to be added
 203    * @pre The KeyboardFocusManager has been initialized.
 204    * @pre The indicator actor has been initialized.
 205    */
 206   void SetFocusIndicatorActor(Actor indicator);
 207
 208   /**
 209    * @brief Gets the focus indicator actor.
 210    *
 211    * @SINCE_1_0.0
 212    * @return A handle to the focus indicator actor
 213    * @pre The KeyboardFocusManager has been initialized.
 214    */
 215   Actor GetFocusIndicatorActor();
 216
 217   /**
 218    * @brief Move the focus to prev focused actor
 219    *
 220    * @SINCE_1_2.19
 221    */
 222   void MoveFocusBackward();
 223
 224 public: // Signals
 225   /**
 226    * @brief This signal is emitted before the focus is going to be changed.
 227    *
 228    * KeyboardFocusManager makes the best guess for which actor to
 229    * focus towards the given direction, but applications might want to
 230    * change that. By connecting with this signal, they can check the
 231    * proposed actor to focus and return a different actor if they
 232    * wish. This signal is only emitted when the navigation key is
 233    * pressed and KeyboardFocusManager tries to move the focus
 234    * automatically. It won't be emitted for focus movement by calling
 235    * SetCurrentFocusActor directly.
 236    *
 237    * A callback of the following type may be connected:
 238    * @code
 239    *   Actor YourCallbackName(Actor currentFocusedActor, Actor proposedActorToFocus, Control::KeyboardFocus::Direction direction);
 240    * @endcode
 241    * @SINCE_1_0.0
 242    * @return The signal to connect to
 243    * @pre The Object has been initialized.
 244    */
 245   PreFocusChangeSignalType& PreFocusChangeSignal();
 246
 247   /**
 248    * @brief This signal is emitted after the current focused actor has been changed.
 249    *
 250    * A callback of the following type may be connected:
 251    * @code
 252    *   void YourCallbackName(Actor originalFocusedActor, Actor currentFocusedActor);
 253    * @endcode
 254    * @SINCE_1_0.0
 255    * @return The signal to connect to
 256    * @pre The Object has been initialized.
 257    */
 258   FocusChangedSignalType& FocusChangedSignal();
 259
 260   /**
 261    * @brief This signal is emitted when the focus group has been changed.
 262    *
 263    * If the current focus group has a parent layout control,
 264    * KeyboardFocusManager will make the best guess for the next focus
 265    * group to move the focus to in the given direction (forward or
 266    * backward). If not, the application has to set the new focus.
 267    *
 268    * A callback of the following type may be connected:
 269    * @code
 270    *   void YourCallbackName(Actor currentFocusedActor, bool forward);
 271    * @endcode
 272    * @SINCE_1_0.0
 273    * @return The signal to connect to
 274    * @pre The Object has been initialized.
 275    */
 276   FocusGroupChangedSignalType& FocusGroupChangedSignal();
 277
 278   /**
 279    * @brief This signal is emitted when the current focused actor has the enter key pressed on it.
 280    *
 281    * A callback of the following type may be connected:
 282    * @code
 283    *   void YourCallbackName(Actor enterPressedActor);
 284    * @endcode
 285    * @SINCE_1_0.0
 286    * @return The signal to connect to
 287    * @pre The Object has been initialized.
 288    */
 289   FocusedActorEnterKeySignalType& FocusedActorEnterKeySignal();
 290
 291   // Not intended for application developers
 292
 293   /// @cond internal
 294   /**
 295    * @brief Creates a new handle from the implementation.
 296    *
 297    * @SINCE_1_0.0
 298    * @param[in] impl A pointer to the object
 299    */
 300   explicit DALI_INTERNAL KeyboardFocusManager(Internal::KeyboardFocusManager* impl);
 301   /// @endcond
 302
 303 }; // class KeyboardFocusManager
 304
 305 /**
 306  * @}
 307  */
 308 } // namespace Toolkit
 309
 310 } // namespace Dali
 311
 312 #endif // DALI_TOOLKIT_KEYBOARD_FOCUS_MANAGER_H