You.i Engine
CYIFocusEngine Class Referenceabstract

Detailed Description

An interface for a focus engine. Focus engines manage focus navigation within You.i Engine.

A focus engine instance is created as part of the app's initialization.

#include <focus/YiFocusEngine.h>

Inheritance diagram for CYIFocusEngine:

Public Types

enum  FocusabilityStatus {
  FocusabilityStatus::CanBeFocused = 0x00,
  FocusabilityStatus::ViewNull = 0x01,
  FocusabilityStatus::ViewNotFocusable = 0x02,
  FocusabilityStatus::ViewInvisible = 0x04,
  FocusabilityStatus::ViewNotStaged = 0x08,
  FocusabilityStatus::FocusEngineSpecific = 0x10
}
 

Public Member Functions

 CYIFocusEngine ()
 
virtual ~CYIFocusEngine ()=default
 
virtual bool Init (CYISceneNode *pLogicalRoot)=0
 
virtual void Update ()=0
 
virtual void ClearFocus ()=0
 
virtual void HandleKeyInputs (const CYIKeyEvent *pKeyEvent)=0
 
virtual void HandleTrackpadInputs (const CYITrackpadEvent *pKeyEvent)=0
 
virtual void CancelTrackpadSwipes ()=0
 
virtual const CYISceneViewGetViewWithFocus () const =0
 
CYISceneViewGetViewWithFocus ()
 
const CYISceneViewGetViewWithFocus (const CYISceneNode *pRootNode) const
 
CYISceneViewGetViewWithFocus (const CYISceneNode *pRootNode)
 
virtual const CYISceneViewFindNextFocus (const CYISceneView *pSearchFrom, CYIFocus::Direction direction, const CYIFocusSearchOptions &options=CYIFocusSearchOptions())=0
 
virtual bool RequestFocus (const CYISceneView *pViewToFocus, CYIFocus::FocusRootRule focusRootRule=CYIFocus::FocusRootRule::DescendantsUpdateContext)=0
 
virtual bool MoveFocus (CYIFocus::Direction direction, const CYIFocusSearchOptions &options=CYIFocusSearchOptions())=0
 
bool CanBeFocused (const CYISceneView *pView) const
 
virtual FocusabilityStatus GetViewFocusability (const CYISceneView *pViewToFocus) const =0
 

Public Attributes

CYISignal< CYISceneView * > ViewWithFocusChanged
 

Member Enumeration Documentation

◆ FocusabilityStatus

An enum that lists the possible focusability states for a view.

Enumerator
CanBeFocused 

The view can be focused.

ViewNull 

The view can't be focused because it's null.

ViewNotFocusable 

The view can't be focused because it's not marked as focusable.

See also
CYISceneView::SetFocusable
ViewInvisible 

The view can't be focused because it's invisible.

See also
CYISceneNode::Show
ViewNotStaged 

The view can't be focused because it's not part of the scene tree.

See also
CYISceneManager::StageScene
FocusEngineSpecific 

The view can't be focused due to an unspecified focus engine-specific reason.

Constructor & Destructor Documentation

◆ CYIFocusEngine()

CYIFocusEngine::CYIFocusEngine ( )

◆ ~CYIFocusEngine()

virtual CYIFocusEngine::~CYIFocusEngine ( )
virtualdefault

Member Function Documentation

◆ CanBeFocused()

bool CYIFocusEngine::CanBeFocused ( const CYISceneView pView) const

Returns true if the given view can receive focus.

In order to receive focus a view must be reachable, have its visibility set to true, and be set to focusable.

See also
CYISceneView::IsFocusable
CYISceneNode::IsTrulyVisible
CYISceneManager::IsReachable

◆ CancelTrackpadSwipes()

virtual void CYIFocusEngine::CancelTrackpadSwipes ( )
pure virtual

Cancels any in-progress trackpad swipes.

Implemented in CYIYouiFocusEngine, and CYINullFocusEngine.

◆ ClearFocus()

virtual void CYIFocusEngine::ClearFocus ( )
pure virtual

Clears the currently focused view, if any.

Implemented in CYIYouiFocusEngine, and CYINullFocusEngine.

◆ FindNextFocus()

virtual const CYISceneView* CYIFocusEngine::FindNextFocus ( const CYISceneView pSearchFrom,
CYIFocus::Direction  direction,
const CYIFocusSearchOptions options = CYIFocusSearchOptions() 
)
pure virtual

Finds the next view that can take focus in direction direction, searching from pSearchFrom. If pSearchFrom is nullptr, a search from 'nothing' is performed. Returns nullptr if no new focus target could be found.

Implemented in CYIYouiFocusEngine, and CYINullFocusEngine.

◆ GetViewFocusability()

virtual FocusabilityStatus CYIFocusEngine::GetViewFocusability ( const CYISceneView pViewToFocus) const
pure virtual

Returns details about whether a view can be focused.

Implemented in CYIYouiFocusEngine, and CYINullFocusEngine.

◆ GetViewWithFocus() [1/4]

virtual const CYISceneView* CYIFocusEngine::GetViewWithFocus ( ) const
pure virtual

Returns the view that currently has focus, or null if no view has focus.

Implemented in CYIYouiFocusEngine, and CYINullFocusEngine.

◆ GetViewWithFocus() [2/4]

CYISceneView* CYIFocusEngine::GetViewWithFocus ( )

Returns the view that currently has focus, or null if no view has focus.

◆ GetViewWithFocus() [3/4]

const CYISceneView* CYIFocusEngine::GetViewWithFocus ( const CYISceneNode pRootNode) const

Returns the view that currently has focus, or null if no view has focus. Returns null if the view with focus is not a descendant of pRootNode and is not pRootNode itself.

◆ GetViewWithFocus() [4/4]

CYISceneView* CYIFocusEngine::GetViewWithFocus ( const CYISceneNode pRootNode)

Returns the view that currently has focus, or null if no view has focus. Returns null if the view with focus is not a descendant of pRootNode and is not pRootNode itself.

◆ HandleKeyInputs()

virtual void CYIFocusEngine::HandleKeyInputs ( const CYIKeyEvent pKeyEvent)
pure virtual

Handles focus changes given a CYIEvent::Type::KeyDown event.

Implemented in CYIYouiFocusEngine, and CYINullFocusEngine.

◆ HandleTrackpadInputs()

virtual void CYIFocusEngine::HandleTrackpadInputs ( const CYITrackpadEvent pKeyEvent)
pure virtual

Handles focus changes given a trackpad event. This generates focus moves requests (as necessary) as the trackpad events are received.

Implemented in CYIYouiFocusEngine, and CYINullFocusEngine.

◆ Init()

virtual bool CYIFocusEngine::Init ( CYISceneNode pLogicalRoot)
pure virtual

Initializes this focus engine. Returns false if initialization failed.

Implemented in CYIYouiFocusEngine, and CYINullFocusEngine.

◆ MoveFocus()

virtual bool CYIFocusEngine::MoveFocus ( CYIFocus::Direction  direction,
const CYIFocusSearchOptions options = CYIFocusSearchOptions() 
)
pure virtual

'Moves' the focus in direction direction, relative to the view that currently has focus. If no view currently has focus, a focus search is started from the current focus root.

options can be used to further restrict the set of valid focus candidates.

Returns true if focus was successfully moved.

Implemented in CYIYouiFocusEngine, and CYINullFocusEngine.

◆ RequestFocus()

virtual bool CYIFocusEngine::RequestFocus ( const CYISceneView pViewToFocus,
CYIFocus::FocusRootRule  focusRootRule = CYIFocus::FocusRootRule::DescendantsUpdateContext 
)
pure virtual

Requests that pViewToFocus receive focus. The view will receive focus if it is focusable. Returns true if pViewToFocus obtained focus or had focus before the request.

For a view to take focus, it must meet the following requirements: it is visible, attached to the tree, and focusable.

focusRootRule dictates whether the focus system will allow the focus request to move to a view outside of the current focus root. When CYIFocus::FocusRootRule::DescendantsUpdateContext is provided this method will return true if pViewToFocus's focus root is updated with pViewToFocus as the current focus in that context.

pViewToFocus must be non-null. If focus needs to be cleared, ClearFocus can be used.

See also
CYISceneView::RequestFocus

Implemented in CYIYouiFocusEngine, and CYINullFocusEngine.

◆ Update()

virtual void CYIFocusEngine::Update ( )
pure virtual

Called by CYISceneManager after the scene tree is updated. This allows the focus engine to update focus after modifications have been made to the scene tree.

Implemented in CYIYouiFocusEngine, and CYINullFocusEngine.

Member Data Documentation

◆ ViewWithFocusChanged

CYISignal<CYISceneView *> CYIFocusEngine::ViewWithFocusChanged

A signal called whenever the view with focus has changed. This signal may be called with null when no view has focus. Unlike CYIEvent::Type::FocusIn and CYIEvent::Type::FocusOut, this function is called synchronously as soon as the focus is moved.


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