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