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) 2015 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_focus_manager
  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  * | keyboardFocusedActorAenterKey | @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 Create a KeyboardFocusManager handle; this can be initialised with KeyboardFocusManager::New().
  76    *
  77    * Calling member functions with an uninitialised 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 Get 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 Move 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 Get 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 Move 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 Clear 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 Set 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 Get 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 Set 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 Check 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 Set 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 Get 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 public: // Signals
 221
 222   /**
 223    * @brief This signal is emitted before the focus is going to be changed.
 224    *
 225    * KeyboardFocusManager makes the best guess for which actor to
 226    * focus towards the given direction, but applications might want to
 227    * change that. By connecting with this signal, they can check the
 228    * proposed actor to focus and return a different actor if they
 229    * wish.  This signal is only emitted when the navigation key is
 230    * pressed and KeyboardFocusManager tries to move the focus
 231    * automatically. It won't be emitted for focus movement by calling
 232    * SetCurrentFocusActor directly.
 233    *
 234    * A callback of the following type may be connected:
 235    * @code
 236    *   Actor YourCallbackName(Actor currentFocusedActor, Actor proposedActorToFocus, Control::KeyboardFocus::Direction direction);
 237    * @endcode
 238    * @SINCE_1_0.0
 239    * @return The signal to connect to.
 240    * @pre The Object has been initialized.
 241    */
 242   PreFocusChangeSignalType& PreFocusChangeSignal();
 243
 244   /**
 245    * @brief This signal is emitted after the current focused actor has been changed.
 246    *
 247    * A callback of the following type may be connected:
 248    * @code
 249    *   void YourCallbackName(Actor originalFocusedActor, Actor currentFocusedActor);
 250    * @endcode
 251    * @SINCE_1_0.0
 252    * @return The signal to connect to.
 253    * @pre The Object has been initialized.
 254    */
 255   FocusChangedSignalType& FocusChangedSignal();
 256
 257   /**
 258    * @brief This signal is emitted when the focus group has been changed.
 259    *
 260    * If the current focus group has a parent layout control,
 261    * KeyboardFocusManager will make the best guess for the next focus
 262    * group to move the focus to in the given direction (forward or
 263    * backward). If not, the application has to set the new focus.
 264    *
 265    * A callback of the following type may be connected:
 266    * @code
 267    *   void YourCallbackName(Actor currentFocusedActor, bool forward);
 268    * @endcode
 269    * @SINCE_1_0.0
 270    * @return The signal to connect to.
 271    * @pre The Object has been initialized.
 272    */
 273   FocusGroupChangedSignalType& FocusGroupChangedSignal();
 274
 275   /**
 276    * @brief This signal is emitted when the current focused actor has the enter key pressed on it.
 277    *
 278    * A callback of the following type may be connected:
 279    * @code
 280    *   void YourCallbackName(Actor enterPressedActor);
 281    * @endcode
 282    * @SINCE_1_0.0
 283    * @return The signal to connect to.
 284    * @pre The Object has been initialized.
 285    */
 286   FocusedActorEnterKeySignalType& FocusedActorEnterKeySignal();
 287
 288   // Not intended for application developers
 289
 290   /**
 291    * @brief Creates a new handle from the implementation.
 292    *
 293    * @SINCE_1_0.0
 294    * @param[in] impl A pointer to the object.
 295    */
 296   explicit DALI_INTERNAL KeyboardFocusManager(Internal::KeyboardFocusManager *impl);
 297
 298 }; // class KeyboardFocusManager
 299
 300 /**
 301  * @}
 302  */
 303 } // namespace Toolkit
 304
 305 } // namespace Dali
 306
 307 #endif // __DALI_TOOLKIT_KEYBOARD_FOCUS_MANAGER_H__