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