X-Git-Url: http://review.tizen.org/git/?p=platform%2Fcore%2Fuifw%2Fdali-toolkit.git;a=blobdiff_plain;f=dali-toolkit%2Fpublic-api%2Ffocus-manager%2Fkeyboard-focus-manager.h;h=df934f10c28638df6de491074955e61bf509a7c0;hp=3383a473548d98bdd25ba139f7dda87f41a925ca;hb=5a80f5b0c8814d86156be28bdcdafcfcd8486b49;hpb=235c866c63c1b2b493a5bff0508fa92cb70a9f2e diff --git a/dali-toolkit/public-api/focus-manager/keyboard-focus-manager.h b/dali-toolkit/public-api/focus-manager/keyboard-focus-manager.h index 3383a47..df934f1 100644 --- a/dali-toolkit/public-api/focus-manager/keyboard-focus-manager.h +++ b/dali-toolkit/public-api/focus-manager/keyboard-focus-manager.h @@ -1,8 +1,8 @@ -#ifndef __DALI_TOOLKIT_KEYBOARD_FOCUS_MANAGER_H__ -#define __DALI_TOOLKIT_KEYBOARD_FOCUS_MANAGER_H__ +#ifndef DALI_TOOLKIT_KEYBOARD_FOCUS_MANAGER_H +#define DALI_TOOLKIT_KEYBOARD_FOCUS_MANAGER_H /* - * Copyright (c) 2015 Samsung Electronics Co., Ltd. + * Copyright (c) 2020 Samsung Electronics Co., Ltd. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -23,14 +23,16 @@ namespace Dali { - namespace Toolkit { - namespace Internal DALI_INTERNAL { class KeyboardFocusManager; } +/** + * @addtogroup dali_toolkit_managers + * @{ + */ /** * @brief Provides the functionality of handling keyboard navigation @@ -42,135 +44,147 @@ class KeyboardFocusManager; * is changed. * * Signals - * | %Signal Name | Method | - * |----------------------------------|------------------------------------| - * | keyboard-pre-focus-change | @ref PreFocusChangeSignal() | - * | keyboard-focus-changed | @ref FocusChangedSignal() | - * | keyboard-focus-group-changed | @ref FocusGroupChangedSignal() | - * | keyboard-focused-actor-enter-key | @ref FocusedActorEnterKeySignal() | + * | %Signal Name | Method | + * |------------------------------|------------------------------------| + * | keyboardPreFocusChange | @ref PreFocusChangeSignal() | + * | keyboardFocusChanged | @ref FocusChangedSignal() | + * | keyboardFocusGroupChanged | @ref FocusGroupChangedSignal() | + * | keyboardFocusedActorEnterKey | @ref FocusedActorEnterKeySignal() | + * @SINCE_1_0.0 */ -class DALI_IMPORT_API KeyboardFocusManager : public BaseHandle +class DALI_TOOLKIT_API KeyboardFocusManager : public BaseHandle { - public: - /// @brief Pre focus change signal - typedef Signal< Actor ( Actor, Actor, Control::KeyboardFocus::Direction ) > PreFocusChangeSignalType; + typedef Signal PreFocusChangeSignalType; /// @brief Focus changed signal - typedef Signal< void ( Actor, Actor ) > FocusChangedSignalType; + typedef Signal FocusChangedSignalType; /// @brief Focus group changed signal - typedef Signal< void ( Actor, bool ) > FocusGroupChangedSignalType; + typedef Signal FocusGroupChangedSignalType; /// @brief Focused actor has the enter key pressed signal - typedef Signal< void ( Actor ) > FocusedActorEnterKeySignalType; + typedef Signal FocusedActorEnterKeySignalType; /** - * @brief Create a KeyboardFocusManager handle; this can be initialised with KeyboardFocusManager::New(). + * @brief Creates a KeyboardFocusManager handle; this can be initialized with KeyboardFocusManager::New(). * - * Calling member functions with an uninitialised handle is not allowed. + * Calling member functions with an uninitialized handle is not allowed. + * @SINCE_1_0.0 */ KeyboardFocusManager(); /** - * @brief Destructor + * @brief Destructor. * * This is non-virtual since derived Handle types must not contain data or virtual methods. + * @SINCE_1_0.0 */ ~KeyboardFocusManager(); /** - * @brief Get the singleton of KeyboardFocusManager object. + * @brief Gets the singleton of KeyboardFocusManager object. * - * @return A handle to the KeyboardFocusManager control. + * @SINCE_1_0.0 + * @return A handle to the KeyboardFocusManager control */ static KeyboardFocusManager Get(); /** - * @brief Move the keyboard focus to the given actor. + * @brief Moves the keyboard focus to the given actor. * * Only one actor can be focused at the same time. The actor must * be in the stage already and keyboard focusable. * - * @pre The KeyboardFocusManager has been initialized. - * @pre The Actor has been initialized. + * @SINCE_1_0.0 * @param actor The actor to be focused * @return Whether the focus is successful or not + * @pre The KeyboardFocusManager has been initialized. + * @pre The Actor has been initialized. + * @note If the parent of this actor has the KEYBOARD FOCUSABLE CHILDREN property set to false, it will not be focused. */ bool SetCurrentFocusActor(Actor actor); /** - * @brief Get the current focused actor. + * @brief Gets the current focused actor. * + * @SINCE_1_0.0 + * @return A handle to the current focused actor or an empty handle if no actor is focused * @pre The KeyboardFocusManager has been initialized. - * @return A handle to the current focused actor or an empty handle if no actor is focused. */ Actor GetCurrentFocusActor(); /** - * @brief Move the focus to the next focusable actor in the focus + * @brief Moves the focus to the next focusable actor in the focus * chain in the given direction (according to the focus traversal * order). * - * @pre The KeyboardFocusManager has been initialized. + * @SINCE_1_0.0 * @param direction The direction of focus movement * @return true if the movement was successful + * @pre The KeyboardFocusManager has been initialized. */ bool MoveFocus(Control::KeyboardFocus::Direction direction); /** - * @brief Clear the focus from the current focused actor if any, so + * @brief Clears the focus from the current focused actor if any, so * that no actor is focused in the focus chain. * - * It will emit focus changed signal without current focused actor + * It will emit focus changed signal without current focused actor. + * @SINCE_1_0.0 * @pre The KeyboardFocusManager has been initialized. */ void ClearFocus(); /** - * @brief Set whether the focus movement should be looped within the same focus group. + * @brief Sets whether the focus movement should be looped within the same focus group. * * The focus movement is not looped by default. - * @pre The KeyboardFocusManager has been initialized. + * @SINCE_1_0.0 * @param enabled Whether the focus movement should be looped + * @pre The KeyboardFocusManager has been initialized. */ void SetFocusGroupLoop(bool enabled); /** - * @brief Get whether the focus movement should be looped within the same focus group. + * @brief Gets whether the focus movement should be looped within the same focus group. * - * @pre The KeyboardFocusManager has been initialized. + * @SINCE_1_0.0 * @return Whether the focus movement should be looped + * @pre The KeyboardFocusManager has been initialized. */ bool GetFocusGroupLoop() const; /** - * @brief Set whether an actor is a focus group that can limit the + * @brief Sets whether an actor is a focus group that can limit the * scope of focus movement to its child actors in the focus chain. * * Layout controls set themselves as focus groups by default. * + * @SINCE_1_0.0 + * @param actor The actor to be set as a focus group + * @param isFocusGroup Whether to set the actor as a focus group or not * @pre The KeyboardFocusManager has been initialized. * @pre The Actor has been initialized. - * @param actor The actor to be set as a focus group. - * @param isFocusGroup Whether to set the actor as a focus group or not. */ void SetAsFocusGroup(Actor actor, bool isFocusGroup); /** - * @brief Check whether the actor is set as a focus group or not. + * @brief Checks whether the actor is set as a focus group or not. * + * @SINCE_1_0.0 + * @param actor The actor to be checked + * @return Whether the actor is set as a focus group * @pre The KeyboardFocusManager has been initialized. * @pre The Actor has been initialized. - * @param actor The actor to be checked. - * @return Whether the actor is set as a focus group. */ bool IsFocusGroup(Actor actor) const; /** * @brief Returns the closest ancestor of the given actor that is a focus group. * + * @SINCE_1_0.0 * @param actor The actor to be checked for its focus group * @return The focus group the given actor belongs to or an empty handle if the given actor * doesn't belong to any focus group @@ -178,28 +192,36 @@ public: Actor GetFocusGroup(Actor actor); /** - * @brief Set the focus indicator actor. + * @brief Sets the focus indicator actor. * * This will replace the default focus indicator actor in * KeyboardFocusManager and will be added to the focused actor as a * highlight. * + * @SINCE_1_0.0 + * @param indicator The indicator actor to be added * @pre The KeyboardFocusManager has been initialized. * @pre The indicator actor has been initialized. - * @param indicator The indicator actor to be added */ void SetFocusIndicatorActor(Actor indicator); /** - * @brief Get the focus indicator actor. + * @brief Gets the focus indicator actor. * - * @pre The KeyboardFocusManager has been initialized. + * @SINCE_1_0.0 * @return A handle to the focus indicator actor + * @pre The KeyboardFocusManager has been initialized. */ Actor GetFocusIndicatorActor(); -public: // Signals + /** + * @brief Move the focus to prev focused actor + * + * @SINCE_1_2.19 + */ + void MoveFocusBackward(); +public: // Signals /** * @brief This signal is emitted before the focus is going to be changed. * @@ -207,7 +229,7 @@ public: // Signals * focus towards the given direction, but applications might want to * change that. By connecting with this signal, they can check the * proposed actor to focus and return a different actor if they - * wish. This signal is only emitted when the navigation key is + * wish. This signal is only emitted when the navigation key is * pressed and KeyboardFocusManager tries to move the focus * automatically. It won't be emitted for focus movement by calling * SetCurrentFocusActor directly. @@ -216,8 +238,9 @@ public: // Signals * @code * Actor YourCallbackName(Actor currentFocusedActor, Actor proposedActorToFocus, Control::KeyboardFocus::Direction direction); * @endcode + * @SINCE_1_0.0 + * @return The signal to connect to * @pre The Object has been initialized. - * @return The signal to connect to. */ PreFocusChangeSignalType& PreFocusChangeSignal(); @@ -228,8 +251,9 @@ public: // Signals * @code * void YourCallbackName(Actor originalFocusedActor, Actor currentFocusedActor); * @endcode + * @SINCE_1_0.0 + * @return The signal to connect to * @pre The Object has been initialized. - * @return The signal to connect to. */ FocusChangedSignalType& FocusChangedSignal(); @@ -245,8 +269,9 @@ public: // Signals * @code * void YourCallbackName(Actor currentFocusedActor, bool forward); * @endcode + * @SINCE_1_0.0 + * @return The signal to connect to * @pre The Object has been initialized. - * @return The signal to connect to. */ FocusGroupChangedSignalType& FocusGroupChangedSignal(); @@ -257,24 +282,31 @@ public: // Signals * @code * void YourCallbackName(Actor enterPressedActor); * @endcode + * @SINCE_1_0.0 + * @return The signal to connect to * @pre The Object has been initialized. - * @return The signal to connect to. */ FocusedActorEnterKeySignalType& FocusedActorEnterKeySignal(); // Not intended for application developers + /// @cond internal /** * @brief Creates a new handle from the implementation. * - * @param[in] impl A pointer to the object. + * @SINCE_1_0.0 + * @param[in] impl A pointer to the object */ - explicit DALI_INTERNAL KeyboardFocusManager(Internal::KeyboardFocusManager *impl); + explicit DALI_INTERNAL KeyboardFocusManager(Internal::KeyboardFocusManager* impl); + /// @endcond }; // class KeyboardFocusManager +/** + * @} + */ } // namespace Toolkit } // namespace Dali -#endif // __DALI_TOOLKIT_KEYBOARD_FOCUS_MANAGER_H__ +#endif // DALI_TOOLKIT_KEYBOARD_FOCUS_MANAGER_H