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