Kanzi  3.9.9
Kanzi Engine C++ API
kanzi::OverlayScope Class Referenceabstract

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

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

Inheritance diagram for kanzi::OverlayScope:
[legend]

Public Member Functions

virtual OverlayScopegetInputPropagationOverlay () const =0
 Returns the overlay focus scope to which this overlay scope propagates user input. More...
 
OverlayScopegetOverlayScope () const override
 Overrides FocusScope::getOverlayScope() by always returning nullptr, because overlay scopes have no owning overlay scopes. More...
 
FocusScopegetParent () 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...
 
NodegetRoot () 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, Node::FocusStateProperty to FocusState::NoFocus, 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...
 
FocusChainNode trySetFocus (Node &node, FocusReason reason) override
 Overrides OverlayScopeCore::trySetFocus();. 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

kanzi::OverlayScope::~OverlayScope ( )
override

Destructor.

kanzi::OverlayScope::OverlayScope ( Node root)
explicitprotected

Constructor.

Member Function Documentation

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.

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.

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.

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.
FocusChainNode kanzi::OverlayScope::trySetFocus ( Node node)

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

Parameters
nodeThe 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.
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 method fails if the overlay 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 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.
bool kanzi::OverlayScope::isNodeInScope ( const Node node) const
overridevirtual

Overrides FocusScope::isNodeInScope().

Reimplemented from kanzi::FocusScope.

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

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

Parameters
reasonThe focus change reason used in the focus lost messages that this function dispatches.
See also
FocusManager::getFocus()
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
overlayThe overlay focus scope that gained the focus.
Since
Kanzi 3.9.3
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
void kanzi::OverlayScope::splitScope ( FocusScope source,
FocusChainNode  targetLastFocusNode 
)
overrideprotectedvirtual

Overrides FocusScope::splitScope();.

Reimplemented from kanzi::FocusScope.

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

Overrides FocusScope::joinScope();.

Reimplemented from kanzi::FocusScope.

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

Overrides FocusScope::notifyScopeTypeChange();.

Reimplemented from kanzi::FocusScope.

void kanzi::OverlayScope::notifyNodeAttached ( Node node)
overrideprotected
void kanzi::OverlayScope::notifyNodeDetached ( Node node)
overrideprotected
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
nodeThe node where the value of the Node::VisibleProperty changed.
void kanzi::OverlayScope::notifyOverlayIncludedInStack ( bool  isFocused,
bool  isForemost 
)
finalprotected

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

Parameters
isFocusedWhether the overlay scope gained the application focus after being included in the stack.
isForemostWhether the overlay scope became the foremost overlay scope after being included in the stack.
void kanzi::OverlayScope::notifyOverlayExcludedFromStack ( bool  wasFocused,
bool  wasForemost 
)
finalprotected

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

Parameters
wasFocusedWhether the overlay scope had the application focus before being excluded from the stack.
wasForemostWhether the overlay scope was the foremost overlay scope before being excluded from the stack.
void kanzi::OverlayScope::updateContentVisibility ( Node node)
protected

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

Parameters
nodeThe node in the overlay focus scope whose visibility changed.
void kanzi::OverlayScope::updateOverlayInFront ( OverlayScope previous)
protected

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

Parameters
previousThe previous foremost focus scope. If there is no previous foremost focus scope in Kanzi, pass nullptr.
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
newForemostThe focus scope to become the foremost focus scope.
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
enableTo 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
FocusChainNode kanzi::OverlayScope::trySetFocus ( Node node,
FocusReason  reason 
)
overrideprotected

Overrides OverlayScopeCore::trySetFocus();.

Since
Kanzi 3.9.7

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