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

NodeSharedPtr	findNodeToRecoverFocusWhenScopeChangeTo (FocusScopePtr &newScopeInfo) const
	Finds a node to which Kanzi tries to set the focus after this focus scope changes to newScopeInfo and the scope type change itself did not restore focus to any node. More...

FocusChainNode	findNodeToRestoreFocusOn ()
	Finds a focusable node to which tryRestoreScopeFocusedNode() restores the focus when called with Direction set to Next and Reason set to Force. 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...

virtual OverlayScope *	getOverlayScope () const
	Returns the overlay 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 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 (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 (Node *currentFocus, FocusReason reason, 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, Node::FocusStateProperty to FocusState::NoFocus, and clears the last-focused node of a focus scope. More...

Static Public Member Functions
static FocusScopePtr	create (FocusScopeType type, Node &rootNode)
	Creates an instance of a focus scope type, with the rootNode as the focus scope node. More...

static FocusScopePtr	create (Node &rootNode)
	Creates a focus scope type instance with the rootNode as the root of the focus scope. More...

static void	swapScope (FocusScopePtr &newScopeInfo, FocusScopePtr &nodeScopeInfo)
	Safely swaps the focus scope info nodeScopeInfo of a node with the newScopeInfo. 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 ()
	Invalidates the focus chain of the focus scope, including the focus chain snapshots of its nested focus scopes. More...

virtual void	joinScope (FocusScope &target)
	Joins the last-focused node of this scope with the target focus scope, if the last-focused node of the target scope is the scope node of this focus scope. More...

void	notifyInvalidateFocusChain () override
	Kanzi calls this method to invalidate the focus chain snapshots of the focus scope. More...

void	notifyNodeAttached (Node &node) override
	FocusManager calls this method when a node is attached to the node tree. More...

void	notifyNodeDetached (Node &node) override
	FocusManager calls this method to notify that a node from the scope is detached. More...

virtual void	notifyScopeTypeChange (FocusScope &oldScopeData)
	Notifies that the focus scope type of this scope changed from oldScopeData. More...

virtual void	splitScope (FocusScope *target, FocusChainNode targetLastFocusedNode)
	Splits the last-focused node of a target scope with this focus scope. More...

void	swapScopeData (FocusScope &other)
	Swaps the focus scope data of this scope with the focus scope data of the source scope. 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 Node class creates the focus scope information when you set the FocusManager::FocusScopeTypeProperty on a node. When you attach an overlay focus scope node to the node tree, Kanzi registers the scope to the FocusManager.

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

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

The focus chain pointer type.

Since: Kanzi 3.9.0

Constructor & Destructor Documentation

virtual kanzi::FocusScope::~FocusScope ( )

virtual

Destructor.

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

explicitprotected

Constructor.

Parameters

scopeNode	The focus scope node.
flags	The focus scope flags.

Member Function Documentation

static FocusScopePtr kanzi::FocusScope::create	(	FocusScopeType	type,
		Node &	rootNode
	)

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.

Returns: The focus scope data.

Since: Kanzi 3.9.0. Kanzi 3.9.2 removes scopeStack argument.

static FocusScopePtr kanzi::FocusScope::create ( Node & rootNode )

static

Creates a focus scope type instance with the rootNode as the root of the focus scope.

The FocusManager::FocusScopeTypeProperty attached to the rootNode defines the type of the focus scope instance.

Parameters

rootNode The focus scope node.

Returns: The focus scope data.

Since: Kanzi 3.9.2

static void kanzi::FocusScope::swapScope	(	FocusScopePtr &	newScopeInfo,
		FocusScopePtr &	nodeScopeInfo
	)

static

Safely swaps the focus scope info nodeScopeInfo of a node with the newScopeInfo.

Joins, splits or updates the new nodeScopeInfo based on the new scope info passed as argument. The function asserts if the two focus scope types have different root node.

Parameters

newScopeInfo	The new focus scope info to swap with the scope info.
nodeScopeInfo	The address of the focus scope info structure to swap.

Since: Kanzi 3.9.2

bool kanzi::FocusScope::isAttached ( ) const

Returns whether a focus scope node is attached.

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

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

Returns the focus scope node.

Returns: The reference to the focus scope node.

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

virtual OverlayScope* kanzi::FocusScope::getOverlayScope ( ) const

virtual

Returns the overlay scope that owns the focus scope.

Returns: The overlay 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 overlay scope ancestor set, returns nullptr

Since: Kanzi 3.9.2

Reimplemented in kanzi::OverlayScope.

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

pure virtual

Returns the type of the focus scope.

Returns: The type of the focus scope.

Implemented in kanzi::AutoClosingModelessScope, kanzi::ModelessScope, kanzi::AutoClosingModalScope, kanzi::ModalScope, kanzi::FocusFence, and kanzi::FocusGroup.

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 overlay focus scopes.

Returns: If the node is in the current focus scope, true, otherwise false.

Reimplemented in kanzi::OverlayScope.

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. When last-focused node is not set and the root node of the focus scope is not the last-focused node of the scope, returns an invalid FocusChainNode.

Since: Kanzi 3.9.0

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.

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.

void kanzi::FocusScope::clearLastFocused ( )

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

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

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

void kanzi::FocusScope::clearLastFocusedNode ( )

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

Since: Kanzi 3.9.0

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

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

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

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

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

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

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

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

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

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

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

FocusChainNode kanzi::FocusScope::tryRestoreScopeFocusedNode	(	Node *	currentFocus,
		FocusReason	reason,
		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. If the root node of the focus scope has no focusable children, but the root node can hold focus, sets focus to the root 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

FocusChainNode kanzi::FocusScope::tryMoveFocusInScope ( 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 FocusChainDirection::Next.
The last focusable node of the focus scope, if the direction is FocusChainDirection::Previous.

The method fails if the focus scope has no focusable descendant node, or if there is no existing application focus.

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, or the application has no focus, the method returns an invalid focus chain node instance.

Since: Kanzi 3.9.0

FocusChainNode kanzi::FocusScope::findNodeToRestoreFocusOn ( )

Finds a focusable node to which tryRestoreScopeFocusedNode() restores the focus when called with Direction set to Next and Reason set to Force.

Returns: If the focus scope has no last-focused node, returns the first focusable node of the focus scope or its nested scope.

Since: Kanzi 3.9.3

NodeSharedPtr kanzi::FocusScope::findNodeToRecoverFocusWhenScopeChangeTo ( FocusScopePtr & newScopeInfo ) const

Finds a node to which Kanzi tries to set the focus after this focus scope changes to newScopeInfo and the scope type change itself did not restore focus to any node.

Returns: The node to which to try to set the focus after this scope changes to newScopeInfo.

Since: Kanzi 3.9.3

void kanzi::FocusScope::invalidateFocusChain ( )

protected

Invalidates the focus chain of the focus scope, including the focus chain snapshots of its nested focus scopes.

virtual void kanzi::FocusScope::splitScope	(	FocusScope *	target,
		FocusChainNode	targetLastFocusedNode
	)

protectedvirtual

Splits the last-focused node of a target scope with this focus scope.

Kanzi assumes that the target scope is the parent focus scope of this scope. If the target focus scope holds the focus node, the last-focused node of target is set to the last-focused node of this scope.

Parameters

target	The target focus scope to split.
targetLastFocusedNode	The last-focused node of the target focus scope.

Reimplemented in kanzi::OverlayScope.

virtual void kanzi::FocusScope::joinScope ( FocusScope & target )

protectedvirtual

Joins the last-focused node of this scope with the target focus scope, if the last-focused node of the target scope is the scope node of this focus scope.

Prepares this scope for destruction.

Parameters

target The focus scope to which you want to merge this focus scope.

Reimplemented in kanzi::OverlayScope.

virtual void kanzi::FocusScope::notifyScopeTypeChange ( FocusScope & oldScopeData )

protectedvirtual

Notifies that the focus scope type of this scope changed from oldScopeData.

Parameters

oldScopeData The previous scope data of the focus scope that changed.

Reimplemented in kanzi::OverlayScope.

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

overrideprotected

FocusManager calls this method when a node is attached to the node tree.

Parameters

node	The node attached to the node tree.

Since: Kanzi 3.9.0

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

overrideprotected

FocusManager calls this method to notify that a node from the scope is detached.

Parameters

node	The detached node.

Since: Kanzi 3.9.0

void kanzi::FocusScope::notifyInvalidateFocusChain ( )

inlineoverrideprotected

Kanzi calls this method to invalidate the focus chain snapshots of the focus scope.

When Kanzi invalidates a focus chain snapshot, all its nested focus chain snapshots are also invalidated.

Since: Kanzi 3.9.2

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

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

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 Member Functions

Detailed Description

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation