Kanzi Framework  3.9.0
Kanzi Engine API
kanzi::FocusScope Class Referenceabstract

The FocusScope class holds the attributes of a focus scope: More...

#include <kanzi/core.ui/input/focus_scope.hpp>

Inheritance diagram for kanzi::FocusScope:
[legend]

Classes

class  FocusChain
 The FocusChain contains the snapshot of the focus chain of a focus scope. More...
 

Public Types

using FocusChainSharedPtr = shared_ptr< FocusChain >
 The focus chain pointer type. More...
 

Public Member Functions

bool canFocusEnter () const
 Returns whether the focus can enter the focus scope. More...
 
bool canFocusLeave () const
 Returns whether the focus can leave the focus scope. More...
 
bool canGetLastFocused () const
 Returns whether the focus scope node can be the last-focused node of its owning focus scope. More...
 
FocusChainNode getFocus () const
 Returns the focus node of a focus scope. More...
 
FocusChainSharedPtr getFocusChainSnapshot ()
 Returns a snapshot of the focus chain of a focus scope. More...
 
FocusNavigationManipulatorSharedPtr getFocusNavigationManipulator () const
 Returns the focus navigation manipulator of a focus scope. More...
 
ModalScopegetModalScope () const
 Returns the modal scope that owns the focus scope. More...
 
virtual FocusScopegetParent () const
 If a focus scope has a parent focus scope, returns the parent focus scope. More...
 
NodegetRoot () const
 Returns the focus scope node. More...
 
virtual FocusManager::FocusScopeType getType () const =0
 Returns the type of the focus scope. More...
 
bool isAttached () const
 Returns whether a focus scope node is attached. More...
 
bool isFocusChainEmpty () const
 Returns whether the focus chain of a focus scope is empty. More...
 
bool isFocused () const
 Returns the focused state of the focus scope. More...
 
virtual bool isNodeInScope (const Node &node) const
 Returns whether a node is in a focus scope. More...
 
void setFocusNavigationManipulator (FocusNavigationManipulatorSharedPtr newManipulator)
 Sets the focus navigation manipulator of the focus scope. More...
 
FocusChainNode tryMoveFocusInScope (FocusManager::FocusChainDirection direction)
 Tries to set the focus to a node relative to the current focus node of the focus scope using the focus chain navigation. More...
 
FocusChainNode tryRestoreScopeFocusedNode (FocusChainNode currentFocus, FocusManager::FocusReason reason, FocusManager::FocusChainDirection direction)
 Tries to restore the focus to the last-focused node of a focus scope. More...
 
Node::VisitorResult visitFocusChain (FocusScopeVisitor &visitor)
 Visits the focus chain of the focus scope, and calls the visitor on each node. More...
 
Node::VisitorResult visitFocusScope (FocusScopeVisitor &visitor)
 Visits the focusable nodes of the focus scope, including nested focus scope nodes. More...
 
virtual ~FocusScope ()
 Destructor. More...
 
The last-focused node
FocusChainIndex getLastFocused () const
 Returns the focus chain index of the last-focused node of a focus scope. More...
 
void setLastFocused (const FocusChainIndex &lastFocus)
 Sets the focus chain index of the last-focused node of the focus scope. More...
 
void clearLastFocused ()
 Clears the focus chain index of the last-focused node of a focus scope. More...
 
FocusChainNode getLastFocusedNode () const
 Returns the last-focused node of a focus scope. More...
 
FocusChainNode setLastFocusedNode (const Node &lastFocused)
 Sets the last-focused node of a focus scope. More...
 
void clearLastFocusedNode ()
 Set the Node::FocusedProperty value to false, and clears the last-focused node of a focus scope. More...
 

Static Public Member Functions

static FocusScopePtr create (FocusManager::FocusScopeType type, Node &rootNode, FocusManager::ScopeStack &scopeStack)
 Creates an instance of a focus scope type, with the rootNode as the focus scope node. More...
 

Protected Types

enum  ScopeFlag {
  ScopeFlag::EnterFocusWithNavigationAllowed, ScopeFlag::LeaveFocusWithNavigationAllowed, ScopeFlag::CanGetLastFocusedNode, ScopeFlag::DisableAll,
  ScopeFlag::EnableAll
}
 Defines the scope flags. More...
 

Protected Member Functions

void focusNavigationHandler (FocusManager::MoveFocusMessageArguments &args)
 Navigates the focus in a scope. More...
 
 FocusScope (Node &scopeNode, ScopeFlag flags)
 Constructor. More...
 
void invalidateFocusChain () override
 Overrides FocusScopeCore::invalidateFocusChain(). More...
 
void joinScope (FocusScope &target) override
 Overrides FocusScopeCore::joinScope(). More...
 
void notifyNodeAttached (Node &node) override
 Overrides FocusScopeCore::notifyNodeAttached(). More...
 
void notifyNodeDetached (Node &node) override
 Overrides FocusScopeCore::notifyNodeDetached(). More...
 
void notifyScopeTypeChange (FocusScope &oldScopeData) override
 Overrides FocusScopeCore::notifyScopeTypeChange(). More...
 
void splitScope (FocusScope *target, FocusChainNode targetLastFocusedNode) override
 Overrides FocusScopeCore::splitScope(). More...
 
void swapScopeData (FocusScope &other)
 Swaps the focus scope data of this scope with the focus scope data of the source scope. More...
 

Protected Attributes

const ScopeFlag m_scopeFlags
 The scope flags. More...
 

Detailed Description

The FocusScope class holds the attributes of a focus scope:

  • The root node
  • The last-focused node
  • The focused state of that focus scope.

The root node of a focus scope is called the focus scope node. The FocusManager keeps track of all popup-type focus scopes that are attached to the node tree.

The Node class creates the focus scope information when you set the FocusManager::FocusScopeTypeProperty on a node. When you attach a popup-type focus scope node to the node tree, Kanzi registers the scope to the FocusManager. After Kanzi registers a popup-type focus scope to the FocusManager, you can activate the scope either by calling FocusManager::bringScopeToFront() or by dispatching the FocusManager::BringScopeToFrontMessage to the node or a child node of that popup-type scope.

The class provides the interface for FocusManager on testing focusable node candidates. When testing a node, or querying the focus scope for the next focus candidate, FocusScope checks that:

  • The node is in the tested focus scope
  • The node is attached or in the process of being attached
  • The node is visible
  • The node is enabled
  • The node is focusable
  • If the last-focused node is valid, that the node is in the same focus fence as the last-focused node
Since
Kanzi 3.7.0

Member Typedef Documentation

◆ FocusChainSharedPtr

The focus chain pointer type.

Since
Kanzi 3.9.0

Member Enumeration Documentation

◆ ScopeFlag

enum kanzi::FocusScope::ScopeFlag
strongprotected

Defines the scope flags.

Since
Kanzi 3.9.0
Enumerator
EnterFocusWithNavigationAllowed 

Enables focus navigation to enter in the scope.

LeaveFocusWithNavigationAllowed 

Enables focus navigation to leave the scope.

CanGetLastFocusedNode 

The focus scope node can get the last-focused node of its parent focus scope.

DisableAll 

Everything is disabled on the scope.

EnableAll 

Everything is enabled on the scope.

Constructor & Destructor Documentation

◆ ~FocusScope()

virtual kanzi::FocusScope::~FocusScope ( )
virtual

Destructor.

◆ FocusScope()

kanzi::FocusScope::FocusScope ( Node scopeNode,
ScopeFlag  flags 
)
explicitprotected

Constructor.

Parameters
scopeNodeThe focus scope node.
flagsThe focus scope flags.

Member Function Documentation

◆ create()

static FocusScopePtr kanzi::FocusScope::create ( FocusManager::FocusScopeType  type,
Node rootNode,
FocusManager::ScopeStack scopeStack 
)
static

Creates an instance of a focus scope type, with the rootNode as the focus scope node.

Parameters
typeThe focus scope type to create.
rootNodeThe focus scope node.
scopeStackThe stack with the modal and popup scopes.
Returns
The focus scope data.
Since
Kanzi 3.9.0

◆ isAttached()

bool kanzi::FocusScope::isAttached ( ) const

Returns whether a focus scope node is attached.

Returns
If the focus scope is attached, true, otherwise false.

◆ getRoot()

Node& kanzi::FocusScope::getRoot ( ) const

Returns the focus scope node.

Returns
The reference to the focus scope node.

◆ getParent()

virtual FocusScope* kanzi::FocusScope::getParent ( ) const
virtual

If a focus scope has a parent focus scope, returns the parent focus scope.

Returns
The parent focus scope. If there is no parent focus scope, nullptr.

Reimplemented in kanzi::ModalScope.

◆ getModalScope()

ModalScope* kanzi::FocusScope::getModalScope ( ) const

Returns the modal scope that owns the focus scope.

Returns
The modal scope that owns the focus scope. If the focus scope node is not attached to the UI scene, or the focus scope node has no modal scope ancestor set, returns nullptr
Since
Kanzi 3.9.0

◆ getType()

virtual FocusManager::FocusScopeType kanzi::FocusScope::getType ( ) const
pure virtual

Returns the type of the focus scope.

Returns
The type of the focus scope.

Implemented in kanzi::PopupScope, kanzi::ModalScope, kanzi::FocusFence, and kanzi::FocusGroup.

◆ isNodeInScope()

virtual bool kanzi::FocusScope::isNodeInScope ( const Node node) const
virtual

Returns whether a node is in a focus scope.

Parameters
nodeThe node to check whether it is in the current focus scope. Skips nested popup and modal focus scopes.
Returns
If the node is in the current focus scope, true, otherwise false.

Reimplemented in kanzi::ModalScope.

◆ getFocus()

FocusChainNode kanzi::FocusScope::getFocus ( ) const

Returns the focus node of a focus scope.

Returns
The focus node of the focus scope or the nested scope. If no last-focused node is set, returns an invalid FocusChainNode.
Since
Kanzi 3.9.0

◆ getLastFocused()

FocusChainIndex kanzi::FocusScope::getLastFocused ( ) const

Returns the focus chain index of the last-focused node of a focus scope.

Returns
The focus chain index of the last-focused node of a focus scope.

◆ setLastFocused()

void kanzi::FocusScope::setLastFocused ( const FocusChainIndex lastFocus)

Sets the focus chain index of the last-focused node of the focus scope.

Parameters
lastFocusThe focus chain index of the last-focused node.

◆ clearLastFocused()

void kanzi::FocusScope::clearLastFocused ( )

Clears the focus chain index of the last-focused node of a focus scope.

◆ getLastFocusedNode()

FocusChainNode kanzi::FocusScope::getLastFocusedNode ( ) const

Returns the last-focused node of a focus scope.

Returns
The last-focused node of the focus scope. If no last-focused node is set, returns an invalid FocusChainNode.
Since
Kanzi 3.9.0

◆ setLastFocusedNode()

FocusChainNode kanzi::FocusScope::setLastFocusedNode ( const Node lastFocused)

Sets the last-focused node of a focus scope.

Parameters
lastFocusedThe node to set as the last-focused node of the focus scope.
Returns
The last-focused node of the focus scope.
Since
Kanzi 3.9.0

◆ clearLastFocusedNode()

void kanzi::FocusScope::clearLastFocusedNode ( )

Set the Node::FocusedProperty value to false, and clears the last-focused node of a focus scope.

Since
Kanzi 3.9.0

◆ visitFocusScope()

Node::VisitorResult kanzi::FocusScope::visitFocusScope ( FocusScopeVisitor visitor)

Visits the focusable nodes of the focus scope, including nested focus scope nodes.

Generates the focus order offset for each node of the focus scope, and calls the visitor on each focusable node.

Parameters
visitorThe focus scope visitor.
Returns
The result of the visit.
Since
Kanzi 3.9.0

◆ visitFocusChain()

Node::VisitorResult kanzi::FocusScope::visitFocusChain ( FocusScopeVisitor visitor)

Visits the focus chain of the focus scope, and calls the visitor on each node.

Parameters
visitorThe focus chain visitor.
Returns
The result of the visit.
Since
Kanzi 3.9.0

◆ getFocusChainSnapshot()

FocusChainSharedPtr kanzi::FocusScope::getFocusChainSnapshot ( )

Returns a snapshot of the focus chain of a focus scope.

Returns
The focus chain snapshot of a focus scope. The snapshot stays valid as long as the focus scope content stays the same.
Since
Kanzi 3.9.0

◆ isFocusChainEmpty()

bool kanzi::FocusScope::isFocusChainEmpty ( ) const

Returns whether the focus chain of a focus scope is empty.

The focus chain of a focus scope is empty if the focus scope does not contain any focusable nodes.

Returns
If the focus chain of the focus scope is empty, returns true, otherwise returns false.
Since
Kanzi 3.9.0

◆ isFocused()

bool kanzi::FocusScope::isFocused ( ) const

Returns the focused state of the focus scope.

A focus scope is focused when the focus scope node has the Node::FocusedProperty value set to true. A focus scope node is set as focused when it holds the focus node of the application.

Returns
If the focus scope holds the focus node of the application, returns true, otherwise returns false.
Since
Kanzi 3.9.0

◆ getFocusNavigationManipulator()

FocusNavigationManipulatorSharedPtr kanzi::FocusScope::getFocusNavigationManipulator ( ) const

Returns the focus navigation manipulator of a focus scope.

Returns
The pointer to the focus navigation manipulator of a focus scope.
Since
Kanzi 3.8.0

◆ setFocusNavigationManipulator()

void kanzi::FocusScope::setFocusNavigationManipulator ( FocusNavigationManipulatorSharedPtr  newManipulator)

Sets the focus navigation manipulator of the focus scope.

To remove the focus navigation manipulator from an attached node, pass a nullptr as argument.

Parameters
newManipulatorThe pointer to the focus navigation manipulator to set. To remove the focus manipulator from the focus scope, use nullptr.
Since
Kanzi 3.8.0

◆ canFocusEnter()

bool kanzi::FocusScope::canFocusEnter ( ) const

Returns whether the focus can enter the focus scope.

Returns
If the focus can enter the focus scope, returns true, otherwise false.
Since
Kanzi 3.9.0

◆ canFocusLeave()

bool kanzi::FocusScope::canFocusLeave ( ) const

Returns whether the focus can leave the focus scope.

Returns
If the focus can leave the focus scope, returns true, otherwise false.
Since
Kanzi 3.9.0

◆ canGetLastFocused()

bool kanzi::FocusScope::canGetLastFocused ( ) const

Returns whether the focus scope node can be the last-focused node of its owning focus scope.

Returns
If the focus scope node can be the last-focused node of its owning focus scope, returns true, otherwise false.
Since
Kanzi 3.9.0

◆ tryRestoreScopeFocusedNode()

FocusChainNode kanzi::FocusScope::tryRestoreScopeFocusedNode ( FocusChainNode  currentFocus,
FocusManager::FocusReason  reason,
FocusManager::FocusChainDirection  direction 
)

Tries to restore the focus to the last-focused node of a focus scope.

If the focus scope has no last-focused node, sets the focus to the first or last focusable node of the focus scope.

Parameters
currentFocusThe node from which to remove the focus.
reasonThe reason to move the focus.
directionThe direction based on which Kanzi moves the focus to the first or last focusable node of the focus chain.
Returns
The node to which Kanzi sets focus. This can be the last-focused node, the first focusable node, or the last focusable node of the focus scope. If the method does not find a focusable node in the scope, returns an invalid last-focused node.
Since
Kanzi 3.9.0

◆ tryMoveFocusInScope()

FocusChainNode kanzi::FocusScope::tryMoveFocusInScope ( FocusManager::FocusChainDirection  direction)

Tries to set the focus to a node relative to the current focus node of the focus scope using the focus chain navigation.

The method takes the next focus candidate from the focus chain of the focus scope and its nested focus scopes in the given direction.

If the focus scope has no last-focused node set, the method sets the focus to:

The method fails if the focus scope has no focusable descendant node.

Parameters
directionThe direction in which to query for the next focusable node.
Returns
The focus chain node that has focus. If the scope has no focusable node in the requested direction, the method returns an invalid focus chain node instance.
Since
Kanzi 3.9.0

◆ invalidateFocusChain()

void kanzi::FocusScope::invalidateFocusChain ( )
overrideprotected

Overrides FocusScopeCore::invalidateFocusChain().

Since
Kanzi 3.9.0

◆ splitScope()

void kanzi::FocusScope::splitScope ( FocusScope target,
FocusChainNode  targetLastFocusedNode 
)
overrideprotected

Overrides FocusScopeCore::splitScope().

Since
Kanzi 3.9.0

◆ joinScope()

void kanzi::FocusScope::joinScope ( FocusScope target)
overrideprotected

Overrides FocusScopeCore::joinScope().

Since
Kanzi 3.9.0

◆ notifyScopeTypeChange()

void kanzi::FocusScope::notifyScopeTypeChange ( FocusScope oldScopeData)
overrideprotected

Overrides FocusScopeCore::notifyScopeTypeChange().

Since
Kanzi 3.9.0

◆ notifyNodeAttached()

void kanzi::FocusScope::notifyNodeAttached ( Node node)
overrideprotected

Overrides FocusScopeCore::notifyNodeAttached().

Since
Kanzi 3.9.0

◆ notifyNodeDetached()

void kanzi::FocusScope::notifyNodeDetached ( Node node)
overrideprotected

Overrides FocusScopeCore::notifyNodeDetached().

Since
Kanzi 3.9.0

◆ swapScopeData()

void kanzi::FocusScope::swapScopeData ( FocusScope other)
protected

Swaps the focus scope data of this scope with the focus scope data of the source scope.

Parameters
otherThe focus scope with which the scope data is to switch.
Since
Kanzi 3.9.0

◆ focusNavigationHandler()

void kanzi::FocusScope::focusNavigationHandler ( FocusManager::MoveFocusMessageArguments args)
protected

Navigates the focus in a scope.

Parameters
argsThe navigation message arguments received from the FocusNavigationManipulator.
Since
Kanzi 3.9.0

Member Data Documentation

◆ m_scopeFlags

const ScopeFlag kanzi::FocusScope::m_scopeFlags
protected

The scope flags.

Since
Kanzi 3.9.0

The documentation for this class was generated from the following file: