Kanzi  3.9.9
Kanzi Engine C++ 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...
 
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 OverlayScopegetOverlayScope () const
 Returns the overlay 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 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

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
scopeNodeThe focus scope node.
flagsThe 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
typeThe focus scope type to create.
rootNodeThe 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
rootNodeThe 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
newScopeInfoThe new focus scope info to swap with the scope info.
nodeScopeInfoThe 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
nodeThe 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
lastFocusThe 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
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
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
visitorThe 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
visitorThe 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
onlyEffectivelyVisibleIf 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
onlyEffectivelyVisibleTo 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
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
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
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
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 method fails if the focus scope has no focusable descendant node, or if there is no existing application focus.

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, 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
targetThe target focus scope to split.
targetLastFocusedNodeThe 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
targetThe 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
oldScopeDataThe 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
nodeThe 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
nodeThe 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
otherThe 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
argsThe navigation message arguments received from the FocusNavigationManipulator.
Since
Kanzi 3.9.0

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