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