Implements the base of overlay focus scopes. More...

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

Inheritance diagram for kanzi::OverlayScope:

Public Member Functions
virtual OverlayScope *	getInputPropagationOverlay () const =0
	Returns the overlay focus scope to which this overlay scope propagates user input. More...

OverlayScope *	getOverlayScope () const override
	Overrides FocusScope::getOverlayScope() by always returning nullptr, because overlay scopes have no owning overlay scopes. More...

FocusScope *	getParent () const override
	Overrides FocusScope::getParent() by always returning nullptr, because overlay scopes have no parent scopes. More...

bool	isForemostScope () const
	Checks whether the focus scope is the foremost scope of the overlay scope stack. More...

bool	isInputEnabled () const
	Returns whether input handling is enabled for the overlay scope. More...

bool	isNodeInScope (const Node &node) const override
	Overrides FocusScope::isNodeInScope(). More...

virtual void	notifyOverlayBelowGainedFocus (OverlayScope *overlay)
	Notifies an overlay focus scope that an overlay below it gained the focus. More...

void	removeFocus (kanzi::FocusReason reason)
	Removes focus from the overlay but preserves last-focused information. More...

FocusChainNode	tryMoveFocusAcrossNestedScopes (FocusChainDirection direction)
	Tries to set the focus to a node relative to the focused node of the overlay focus scope, using the focus chain navigation. More...

FocusChainNode	trySetFocus (Node &node)
	Tries to set the focus to a node of the focus scope. More...

	~OverlayScope () override
	Destructor. More...

Public Member Functions inherited from kanzi::FocusFence
	FocusFence (Node &root)
	Constructor. More...

FocusScopeType	getType () const override
	Returns the type of the focus scope. More...

Public Member Functions inherited from kanzi::FocusScope
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...

Node &	getRoot () const
	Returns the focus scope node. 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...

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

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

Protected Member Functions
void	enableInput (bool enable)
	Enables or disables input handling for the overlay scope. More...

void	joinScope (FocusScope &target) override
	Overrides FocusScope::joinScope();. More...

void	notifyNodeAttached (Node &node) override
	Overrides FocusScope::notifyNodeAttached(). More...

void	notifyNodeDetached (Node &node) override
	Overrides FocusScope::notifyNodeDetached(). More...

void	notifyNodeVisibilityChanged (Node &node) override
	FocusManager calls this method to notify the overlay focus scope about the Node::VisibleProperty value changes in a node. More...

void	notifyOverlayExcludedFromStack (bool wasFocused, bool wasForemost) final
	Notifies the overlay scope that it got excluded from the overlay scope stack. More...

void	notifyOverlayIncludedInStack (bool isFocused, bool isForemost) final
	Notifies the overlay scope that it got included in the overlay scope stack. More...

void	notifyScopeTypeChange (FocusScope &oldScopeData) override
	Overrides FocusScope::notifyScopeTypeChange();. More...

	OverlayScope (Node &root)
	Constructor. More...

void	splitScope (FocusScope *source, FocusChainNode targetLastFocusNode) override
	Overrides FocusScope::splitScope();. More...

void	updateContentVisibility (Node &node)
	Updates the visibility of the content of an overlay focus scope. More...

void	updateOverlayInFront (OverlayScope *previous)
	Notifies that this scope is brought to the front of the scope stack. More...

void	updateOverlayRemovedFromFront (OverlayScope *newForemost)
	Notifies that this focus scope is no longer the foremost focus scope in the focus scope stack. More...

Protected Member Functions inherited from kanzi::FocusFence
	FocusFence (Node &root, ScopeFlag flags)
	Constructor. More...

Protected Member Functions inherited from kanzi::FocusScope
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...

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

void	swapScopeData (FocusScope &other)
	Swaps the focus scope data of this scope with the focus scope data of the source scope. More...

Additional Inherited Members
Public Types inherited from kanzi::FocusScope
using	FocusChainSharedPtr = shared_ptr< FocusChain >
	The focus chain pointer type. More...

Static Public Member Functions inherited from kanzi::FocusScope
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...

Detailed Description

Implements the base of overlay focus scopes.

Kanzi keeps track of all overlay focus scopes that are attached to the node tree.

Since: Kanzi 3.9.2

Constructor & Destructor Documentation

◆ ~OverlayScope()

kanzi::OverlayScope::~OverlayScope ( )

override

Destructor.

◆ OverlayScope()

kanzi::OverlayScope::OverlayScope ( Node & root )

explicitprotected

Constructor.

Member Function Documentation

◆ getParent()

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

overridevirtual

Overrides FocusScope::getParent() by always returning nullptr, because overlay scopes have no parent scopes.

Returns: Returns nullptr.

Reimplemented from kanzi::FocusScope.

◆ getOverlayScope()

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

overridevirtual

Overrides FocusScope::getOverlayScope() by always returning nullptr, because overlay scopes have no owning overlay scopes.

Returns: Returns nullptr.

Reimplemented from kanzi::FocusScope.

◆ getInputPropagationOverlay()

virtual OverlayScope* kanzi::OverlayScope::getInputPropagationOverlay ( ) const

pure virtual

Returns the overlay focus scope to which this overlay scope propagates user input.

Returns: The overlay focus scope that precedes this overlay scope in the overlay scope stack. If this overlay scope is the only overlay focus scope in this application, or if this overlay scope does not propagate user input, returns nullptr.

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

◆ isForemostScope()

bool kanzi::OverlayScope::isForemostScope ( ) const

Checks whether the focus scope is the foremost scope of the overlay scope stack.

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

◆ trySetFocus()

FocusChainNode kanzi::OverlayScope::trySetFocus ( Node & node )

Tries to set the focus to a node of the focus scope.

Parameters

node	The node to which you want to set the focus.

Returns

The node to which Kanzi set the focus. This can be:

The node to which you set focus.
If you tried to set the focus to a focus scope node, one of its child nodes.
If the method cannot set the focus to any node, returns nullptr.
If the node is not within the focus scope boundaries, returns nullptr.

◆ tryMoveFocusAcrossNestedScopes()

FocusChainNode kanzi::OverlayScope::tryMoveFocusAcrossNestedScopes ( FocusChainDirection direction )

Tries to set the focus to a node relative to the focused node of the overlay focus scope, using the focus chain navigation.

The method takes the next focus candidate from the focus chain of the overlay 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 overlay focus scope, if the direction is FocusChainDirection::Next.
The last focusable node of the overlay focus scope, if the direction is FocusChainDirection::Previous.

The method fails if the overlay 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 node that has focus. If the scope has no focusable node in the requested direction, or the application has no focus, the method returns nullptr.

◆ isNodeInScope()

bool kanzi::OverlayScope::isNodeInScope ( const Node & node ) const

overridevirtual

Overrides FocusScope::isNodeInScope().

Reimplemented from kanzi::FocusScope.

◆ removeFocus()

void kanzi::OverlayScope::removeFocus ( kanzi::FocusReason reason )

Removes focus from the overlay but preserves last-focused information.

Parameters

reason The focus change reason used in the focus lost messages that this function dispatches.

See also: FocusManager::getFocus()

◆ notifyOverlayBelowGainedFocus()

virtual void kanzi::OverlayScope::notifyOverlayBelowGainedFocus ( OverlayScope * overlay )

virtual

Notifies an overlay focus scope that an overlay below it gained the focus.

Classes derived from OverlayScope can override this method for custom behavior. The default implementation does nothing.

Parameters

overlay The overlay focus scope that gained the focus.

Since: Kanzi 3.9.3

◆ isInputEnabled()

bool kanzi::OverlayScope::isInputEnabled ( ) const

Returns whether input handling is enabled for the overlay scope.

Returns: If input handling is enabled for the overlay scope, true, otherwise false.

See also: enableInput()

Since: Kanzi 3.9.4

◆ splitScope()

void kanzi::OverlayScope::splitScope	(	FocusScope *	source,
		FocusChainNode	targetLastFocusNode
	)

overrideprotectedvirtual

Overrides FocusScope::splitScope();.

Reimplemented from kanzi::FocusScope.

◆ joinScope()

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

overrideprotectedvirtual

Overrides FocusScope::joinScope();.

Reimplemented from kanzi::FocusScope.

◆ notifyScopeTypeChange()

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

overrideprotectedvirtual

Overrides FocusScope::notifyScopeTypeChange();.

Reimplemented from kanzi::FocusScope.

◆ notifyNodeAttached()

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

overrideprotected

Overrides FocusScope::notifyNodeAttached().

◆ notifyNodeDetached()

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

overrideprotected

Overrides FocusScope::notifyNodeDetached().

◆ notifyNodeVisibilityChanged()

void kanzi::OverlayScope::notifyNodeVisibilityChanged ( Node & node )

overrideprotected

FocusManager calls this method to notify the overlay focus scope about the Node::VisibleProperty value changes in a node.

Parameters

node	The node where the value of the Node::VisibleProperty changed.

◆ notifyOverlayIncludedInStack()

void kanzi::OverlayScope::notifyOverlayIncludedInStack	(	bool	isFocused,
		bool	isForemost
	)

finalprotected

Notifies the overlay scope that it got included in the overlay scope stack.

Parameters

isFocused	Whether the overlay scope gained the application focus after being included in the stack.
isForemost	Whether the overlay scope became the foremost overlay scope after being included in the stack.

◆ notifyOverlayExcludedFromStack()

void kanzi::OverlayScope::notifyOverlayExcludedFromStack	(	bool	wasFocused,
		bool	wasForemost
	)

finalprotected

Notifies the overlay scope that it got excluded from the overlay scope stack.

Parameters

wasFocused	Whether the overlay scope had the application focus before being excluded from the stack.
wasForemost	Whether the overlay scope was the foremost overlay scope before being excluded from the stack.

◆ updateContentVisibility()

void kanzi::OverlayScope::updateContentVisibility ( Node & node )

protected

Updates the visibility of the content of an overlay focus scope.

Parameters

node	The node in the overlay focus scope whose visibility changed.

◆ updateOverlayInFront()

void kanzi::OverlayScope::updateOverlayInFront ( OverlayScope * previous )

protected

Notifies that this scope is brought to the front of the scope stack.

Parameters

previous The previous foremost focus scope. If there is no previous foremost focus scope in Kanzi, pass nullptr.

◆ updateOverlayRemovedFromFront()

void kanzi::OverlayScope::updateOverlayRemovedFromFront ( OverlayScope * newForemost )

protected

Notifies that this focus scope is no longer the foremost focus scope in the focus scope stack.

Parameters

newForemost The focus scope to become the foremost focus scope.

◆ enableInput()

void kanzi::OverlayScope::enableInput ( bool enable )

protected

Enables or disables input handling for the overlay scope.

Disabling input handling excludes the overlay scope from the overlay scope stack.

Parameters

enable To enable input handling for the overlay scope, set to true. To disable input handling for the overlay scope, set to false.

Since: Kanzi 3.9.4

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

kanzi/core.ui/input/focus_scope.hpp

Public Member Functions

Protected Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ ~OverlayScope()

◆ OverlayScope()

Member Function Documentation

◆ getParent()

◆ getOverlayScope()

◆ getInputPropagationOverlay()

◆ isForemostScope()

◆ trySetFocus()

◆ tryMoveFocusAcrossNestedScopes()

◆ isNodeInScope()

◆ removeFocus()

◆ notifyOverlayBelowGainedFocus()

◆ isInputEnabled()

◆ splitScope()

◆ joinScope()

◆ notifyScopeTypeChange()

◆ notifyNodeAttached()

◆ notifyNodeDetached()

◆ notifyNodeVisibilityChanged()

◆ notifyOverlayIncludedInStack()

◆ notifyOverlayExcludedFromStack()

◆ updateContentVisibility()

◆ updateOverlayInFront()

◆ updateOverlayRemovedFromFront()

◆ enableInput()