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

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

Inheritance diagram for kanzi::FocusScope:

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

FocusChainSharedPtr	getFocusChainSnapshot (bool onlyEffectivelyVisible)
	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...

ModalScope *	getModalScope () const
	Returns the modal scope that owns the focus scope. More...

virtual FocusScope *	getParent () const
	If a focus scope has a parent focus scope, returns the parent focus scope. More...

Node &	getRoot () 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	isFocusChainEmpty (bool onlyEffectivelyVisible) const
	Returns whether the focus chain of a focus scope is empty. 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

using kanzi::FocusScope::FocusChainSharedPtr = shared_ptr<FocusChain>

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

scopeNode	The focus scope node.
flags	The 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

type	The focus scope type to create.
rootNode	The focus scope node.
scopeStack	The 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

node	The 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

lastFocus The 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

lastFocused The 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

visitor The 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

visitor The focus chain visitor.

Returns: The result of the visit.

Since: Kanzi 3.9.0

◆ getFocusChainSnapshot() [1/2]

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

◆ getFocusChainSnapshot() [2/2]

FocusChainSharedPtr kanzi::FocusScope::getFocusChainSnapshot ( bool onlyEffectivelyVisible )

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

The snapshot contains either:

Those focusable nodes that are effectively visible
All focusable nodes that have the Node::VisibleProperty set to true

Parameters

onlyEffectivelyVisible If you pass true, Kanzi returns a focus chain snapshot which contains the effectively visible nodes. If you pass false, Kanzi returns a focus chain snapshot which contains the visible, but effectively invisible nodes.

Returns: The focus chain snapshot of a focus scope. The snapshot stays valid until the focus scope content changes. Invalidates the previous focus scope snapshot created with a different node visibility configuration.

Since: Kanzi 3.9.1

◆ isFocusChainEmpty() [1/2]

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

◆ isFocusChainEmpty() [2/2]

bool kanzi::FocusScope::isFocusChainEmpty ( bool onlyEffectivelyVisible ) 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.

Parameters

onlyEffectivelyVisible To include in the check only effectively visible nodes, pass true. To include also nodes that have the Node::VisibleProperty set to true but are effectively invisible, pass false.

Returns: If the focus chain of the focus scope is empty, true, otherwise false.

Since: Kanzi 3.9.1

◆ 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

newManipulator The 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

currentFocus	The node from which to remove the focus.
reason	The reason to move the focus.
direction	The 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 first focusable node of the focus scope, if the direction is FocusManager::NextFocusable.
The last focusable node of the focus scope, if the direction is FocusManager::PreviousFocusable.

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

Parameters

direction The 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

other The 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

args	The 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:

kanzi/core.ui/input/focus_scope.hpp

Classes

Public Types

Public Member Functions

Static Public Member Functions

Protected Types

Protected Member Functions

Protected Attributes

Detailed Description

Member Typedef Documentation

◆ FocusChainSharedPtr

Member Enumeration Documentation

◆ ScopeFlag

Constructor & Destructor Documentation

◆ ~FocusScope()

◆ FocusScope()

Member Function Documentation

◆ create()

◆ isAttached()

◆ getRoot()

◆ getParent()

◆ getModalScope()

◆ getType()

◆ isNodeInScope()

◆ getFocus()

◆ getLastFocused()

◆ setLastFocused()

◆ clearLastFocused()

◆ getLastFocusedNode()

◆ setLastFocusedNode()

◆ clearLastFocusedNode()

◆ visitFocusScope()

◆ visitFocusChain()

◆ getFocusChainSnapshot() [1/2]

◆ getFocusChainSnapshot() [2/2]

◆ isFocusChainEmpty() [1/2]

◆ isFocusChainEmpty() [2/2]

◆ getFocusNavigationManipulator()

◆ setFocusNavigationManipulator()

◆ canFocusEnter()

◆ canFocusLeave()

◆ canGetLastFocused()

◆ tryRestoreScopeFocusedNode()

◆ tryMoveFocusInScope()

◆ invalidateFocusChain()

◆ splitScope()

◆ joinScope()

◆ notifyScopeTypeChange()

◆ notifyNodeAttached()

◆ notifyNodeDetached()

◆ swapScopeData()

◆ focusNavigationHandler()

Member Data Documentation

◆ m_scopeFlags