Tizen Native API
Public Types | Public Member Functions | Static Public Member Functions
Dali::Toolkit::KeyboardFocusManager Class Reference
Managers

Provides the functionality of handling keyboard navigation and maintaining the two dimensional keyboard focus chain. More...

Inheritance diagram for Dali::Toolkit::KeyboardFocusManager:
Dali::BaseHandle

Public Types

typedef Signal< Actor(Actor,
Actor,
Control::KeyboardFocus::Direction) > 		PreFocusChangeSignalType
 Pre focus change signal.
typedef Signal< void(Actor,
Actor) > 		FocusChangedSignalType
 Focus changed signal.
typedef Signal< void(Actor, bool) > FocusGroupChangedSignalType
 Focus group changed signal.
typedef Signal< void(Actor) > FocusedActorEnterKeySignalType
 Focused actor has the enter key pressed signal.

Public Member Functions

 KeyboardFocusManager ()
 Create a KeyboardFocusManager handle; this can be initialised with KeyboardFocusManager::New().
 ~KeyboardFocusManager ()
 Destructor.
bool SetCurrentFocusActor (Actor actor)
 Move the keyboard focus to the given actor.
Actor GetCurrentFocusActor ()
 Get the current focused actor.
bool MoveFocus (Control::KeyboardFocus::Direction direction)
 Move the focus to the next focusable actor in the focus chain in the given direction (according to the focus traversal order).
void ClearFocus ()
 Clear the focus from the current focused actor if any, so that no actor is focused in the focus chain.
void SetFocusGroupLoop (bool enabled)
 Set whether the focus movement should be looped within the same focus group.
bool GetFocusGroupLoop () const
 Get whether the focus movement should be looped within the same focus group.
void SetAsFocusGroup (Actor actor, bool isFocusGroup)
 Set whether an actor is a focus group that can limit the scope of focus movement to its child actors in the focus chain.
bool IsFocusGroup (Actor actor) const
 Check whether the actor is set as a focus group or not.
Actor GetFocusGroup (Actor actor)
 Returns the closest ancestor of the given actor that is a focus group.
void SetFocusIndicatorActor (Actor indicator)
 Set the focus indicator actor.
Actor GetFocusIndicatorActor ()
 Get the focus indicator actor.
PreFocusChangeSignalType & PreFocusChangeSignal ()
 This signal is emitted before the focus is going to be changed.
FocusChangedSignalType & FocusChangedSignal ()
 This signal is emitted after the current focused actor has been changed.
FocusGroupChangedSignalType & FocusGroupChangedSignal ()
 This signal is emitted when the focus group has been changed.
FocusedActorEnterKeySignalType & FocusedActorEnterKeySignal ()
 This signal is emitted when the current focused actor has the enter key pressed on it.

Static Public Member Functions

static KeyboardFocusManager Get ()
 Get the singleton of KeyboardFocusManager object.

Detailed Description

Provides the functionality of handling keyboard navigation and maintaining the two dimensional keyboard focus chain.

It provides functionality of setting the focus and moving the focus in four directions (i.e. Left, Right, Up and Down). It also draws a highlight for the focused actor and emits a signal when the focus is changed.

Since :
2.4

Member Typedef Documentation

typedef Signal< void ( Actor, Actor ) > Dali::Toolkit::KeyboardFocusManager::FocusChangedSignalType

Focus changed signal.

Since :
2.4
typedef Signal< void ( Actor ) > Dali::Toolkit::KeyboardFocusManager::FocusedActorEnterKeySignalType

Focused actor has the enter key pressed signal.

Since :
2.4
typedef Signal< void ( Actor, bool ) > Dali::Toolkit::KeyboardFocusManager::FocusGroupChangedSignalType

Focus group changed signal.

Since :
2.4
typedef Signal< Actor ( Actor, Actor, Control::KeyboardFocus::Direction ) > Dali::Toolkit::KeyboardFocusManager::PreFocusChangeSignalType

Pre focus change signal.

Since :
2.4

Constructor & Destructor Documentation

Dali::Toolkit::KeyboardFocusManager::KeyboardFocusManager ( )

Create a KeyboardFocusManager handle; this can be initialised with KeyboardFocusManager::New().

Calling member functions with an uninitialised handle is not allowed.

Since :
2.4
Dali::Toolkit::KeyboardFocusManager::~KeyboardFocusManager ( )

Destructor.

This is non-virtual since derived Handle types must not contain data or virtual methods.

Since :
2.4

Member Function Documentation

void Dali::Toolkit::KeyboardFocusManager::ClearFocus ( )

Clear 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.

Since :
2.4
Precondition:
The KeyboardFocusManager has been initialized.
FocusChangedSignalType& Dali::Toolkit::KeyboardFocusManager::FocusChangedSignal ( )

This signal is emitted after the current focused actor has been changed.

A callback of the following type may be connected: 

   void YourCallbackName(Actor originalFocusedActor, Actor currentFocusedActor);
Since :
2.4
Returns:
The signal to connect to
Precondition:
The Object has been initialized.
FocusedActorEnterKeySignalType& Dali::Toolkit::KeyboardFocusManager::FocusedActorEnterKeySignal ( )

This signal is emitted when the current focused actor has the enter key pressed on it.

A callback of the following type may be connected: 

   void YourCallbackName(Actor enterPressedActor);
Since :
2.4
Returns:
The signal to connect to
Precondition:
The Object has been initialized.
FocusGroupChangedSignalType& Dali::Toolkit::KeyboardFocusManager::FocusGroupChangedSignal ( )

This signal is emitted when the focus group has been changed.

If the current focus group has a parent layout control, KeyboardFocusManager will make the best guess for the next focus group to move the focus to in the given direction (forward or backward). If not, the application has to set the new focus.

A callback of the following type may be connected: 

   void YourCallbackName(Actor currentFocusedActor, bool forward);
Since :
2.4
Returns:
The signal to connect to
Precondition:
The Object has been initialized.
static KeyboardFocusManager Dali::Toolkit::KeyboardFocusManager::Get ( ) [static]

Get the singleton of KeyboardFocusManager object.

Since :
2.4
Returns:
A handle to the KeyboardFocusManager control
Actor Dali::Toolkit::KeyboardFocusManager::GetCurrentFocusActor ( )

Get the current focused actor.

Since :
2.4
Returns:
A handle to the current focused actor or an empty handle if no actor is focused.
Precondition:
The KeyboardFocusManager has been initialized.
Actor Dali::Toolkit::KeyboardFocusManager::GetFocusGroup ( Actor  actor)

Returns the closest ancestor of the given actor that is a focus group.

Since :
2.4
Parameters:
actorThe actor to be checked for its focus group
Returns:
The focus group the given actor belongs to or an empty handle if the given actor doesn't belong to any focus group
bool Dali::Toolkit::KeyboardFocusManager::GetFocusGroupLoop ( ) const

Get whether the focus movement should be looped within the same focus group.

Since :
2.4
Returns:
Whether the focus movement should be looped.
Precondition:
The KeyboardFocusManager has been initialized.
Actor Dali::Toolkit::KeyboardFocusManager::GetFocusIndicatorActor ( )

Get the focus indicator actor.

Since :
2.4
Returns:
A handle to the focus indicator actor
Precondition:
The KeyboardFocusManager has been initialized.
bool Dali::Toolkit::KeyboardFocusManager::IsFocusGroup ( Actor  actor) const

Check whether the actor is set as a focus group or not.

Since :
2.4
Parameters:
actorThe actor to be checked
Returns:
Whether the actor is set as a focus group.
Precondition:
The KeyboardFocusManager has been initialized.
The Actor has been initialized.
bool Dali::Toolkit::KeyboardFocusManager::MoveFocus ( Control::KeyboardFocus::Direction  direction)

Move the focus to the next focusable actor in the focus chain in the given direction (according to the focus traversal order).

Since :
2.4
Parameters:
directionThe direction of focus movement
Returns:
True if the movement was successful.
Precondition:
The KeyboardFocusManager has been initialized.
PreFocusChangeSignalType& Dali::Toolkit::KeyboardFocusManager::PreFocusChangeSignal ( )

This signal is emitted before the focus is going to be changed.

KeyboardFocusManager makes the best guess for which actor to 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 pressed and KeyboardFocusManager tries to move the focus automatically. It won't be emitted for focus movement by calling SetCurrentFocusActor directly.

A callback of the following type may be connected: 

   Actor YourCallbackName(Actor currentFocusedActor, Actor proposedActorToFocus, Control::KeyboardFocus::Direction direction);
Since :
2.4
Returns:
The signal to connect to
Precondition:
The Object has been initialized.
void Dali::Toolkit::KeyboardFocusManager::SetAsFocusGroup ( Actor  actor,
bool  isFocusGroup 
)

Set 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 :
2.4
Parameters:
actorThe actor to be set as a focus group
isFocusGroupWhether to set the actor as a focus group or not.
Precondition:
The KeyboardFocusManager has been initialized.
The Actor has been initialized.
bool Dali::Toolkit::KeyboardFocusManager::SetCurrentFocusActor ( Actor  actor)

Move 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.

Since :
2.4
Parameters:
actorThe actor to be focused
Returns:
Whether the focus is successful or not.
Precondition:
The KeyboardFocusManager has been initialized.
The Actor has been initialized.
void Dali::Toolkit::KeyboardFocusManager::SetFocusGroupLoop ( bool  enabled)

Set whether the focus movement should be looped within the same focus group.

The focus movement is not looped by default.

Since :
2.4
Parameters:
enabledWhether the focus movement should be looped.
Precondition:
The KeyboardFocusManager has been initialized.
void Dali::Toolkit::KeyboardFocusManager::SetFocusIndicatorActor ( Actor  indicator)

Set 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 :
2.4
Parameters:
indicatorThe indicator actor to be added
Precondition:
The KeyboardFocusManager has been initialized.
The indicator actor has been initialized.