CYIFocus Class Reference

Detailed Description

A collection focus-finding utilities.

These functions are used by the focus system to automatically find the next view to receive focus in response to user input. The directional keys as well as the tab key are translated to a focus direction. Directional (arrow) keys map to up / down / left / right. The tab key, in conjunction with shift + tab are mapped to forward and reverse directions.

At the end of each frame the focus system will also check if the current focus view is still a valid focus candidate. If it is not, a new view will be assigned focus.

A valid focus candidate meets these requirements: 1) It is focusable. That is, CYISceneView::GetFocusable() returns true. 2) It is visible, and all of its ancestors are visible. 3) It is reachable from the scene manager it associates with.

While not a requirement, focusable views should be able to visually indicate they have received focus. They should also perform some action based on key events they receive while focused.

When implementing a focus handling view, these functions can be used to perform custom focus searches within parts of the tree. Whether using these functions or creating your own focus finding logic, all searches should be performed in screen space to ensure that the navigation always feels natural to the end user of the application.

#include <focus/YiFocus.h>

Public Types
enum	Direction {   Direction::Up,   Direction::Down,   Direction::Right,   Direction::Left,   Direction::Forward,   Direction::Reverse,   Direction::DirectionsCount }
enum	FocusRootRule {   FocusRootRule::Descendants,   FocusRootRule::DescendantsUpdateContext,   FocusRootRule::Any }

Static Public Member Functions
static CYISceneView *	FindNextFocus (const CYISceneNode *pSearchRoot, const CYIAABB &previousFocusRect, Direction direction, const CYIFocusSearchOptions &options=CYIFocusSearchOptions())
static CYISceneView *	FindInitialFocus (const CYISceneNode *pSearchRoot, const CYIFocusSearchOptions &options=CYIFocusSearchOptions())
static CYISceneView *	FindNextFocusInRegion (const CYISceneNode *pSearchRoot, const CYIAABB &previousFocusRect, Direction direction, const CYIAABB &searchRegion, const CYIFocusSearchOptions &options=CYIFocusSearchOptions())
static CYIAABB	GetScreenSpaceFocusRegion (const CYISceneView *pView)
static bool	IsRelativeDirection (Direction direction)
static bool	IsAbsoluteDirection (Direction direction)

Member Enumeration Documentation

Direction

enum CYIFocus::Direction

strong

CYISceneManager will translate a CYIKeyEvent into a Direction for use in automatic focus navigation.

Enumerator
Up	Corresponds to CYIKeyEvent::KeyCode::ArrowUp. Represents up on screen.
Down	Corresponds to CYIKeyEvent::KeyCode::ArrowDown. Represents down on screen.
Right	Corresponds to CYIKeyEvent::KeyCode::ArrowRight. Represents right on screen.
Left	Corresponds to CYIKeyEvent::KeyCode::ArrowLeft. Represents left on screen.
Forward	Corresponds to CYIKeyEvent::KeyCode::Tab. Represents navigation to the next focusable item.
Reverse	Corresponds to CYIKeyEvent::KeyCode::Tab a shift modifier (CYIKeyEvent::m_shiftKey is true). Represents navigation to the previous focusable item.
DirectionsCount	Represents the number of items in this enum, not a valid Direction.

FocusRootRule

enum CYIFocus::FocusRootRule

strong

When focus is requested on a view the focus root rule dictates how the focus system will behave if the request would result in active focus moving out of the current focus root.

See also

CYISceneView::RequestFocus

Enumerator
Descendants	Specifies that the focus system will prevent focus from moving to a view that is not a descendant of the current focus root. This will prevent moving to a new focus root if it is not a descendant of the current.
DescendantsUpdateContext	Similar to CYIFocus::FocusRootRule::Descendants, the focus system will not move focus to a view if it is not a descendant of the current focus root. With this rule if the view requested is focusable the system will update the focus in the context of the focus root to which the view belongs. If that focus root is not the active focus root the main focus will not be changed. The main focus will move to the requested view if focus later enters the view's focus root
Any	Specifies that the focus system will allow the request to move focus to any view even if it is not a descendant of the current focus root. This allows focus to move from one focus root to another regardless of its position in the scene tree.

Member Function Documentation

FindInitialFocus()

static CYISceneView* CYIFocus::FindInitialFocus ( const CYISceneNode *  pSearchRoot, const CYIFocusSearchOptions &  options = CYIFocusSearchOptions()  )

static

Same as FindNextFocus, but intended to be used when no view currently has focus. The search will be performed from the top left corner of the screen searching in the CYISceneView::Direction::Forward direction.

See also

FindNextFocus

FindNextFocus()

static CYISceneView* CYIFocus::FindNextFocus ( const CYISceneNode *  pSearchRoot, const CYIAABB &  previousFocusRect, Direction  direction, const CYIFocusSearchOptions &  options = CYIFocusSearchOptions()  )

static

Returns the next view capable of receiving focus (if any) in direction, starting from the screen space bounding box specified by previousFocusRect.

To perform the search, a list of all focus candidates under pSearchRoot is collected. The screen space bounding boxes of each candidate is considered, and the best candidate (if any) is returned.

The requirements to be a focus candidate are covered in the class documentation for CYIFocus. options can be used to further restrict the set of valid focus candidates.

FindNextFocusInRegion()

static CYISceneView* CYIFocus::FindNextFocusInRegion ( const CYISceneNode *  pSearchRoot, const CYIAABB &  previousFocusRect, Direction  direction, const CYIAABB &  searchRegion, const CYIFocusSearchOptions &  options = CYIFocusSearchOptions()  )

static

Same as FindNextFocus, but for a view to be considered a focus candidate its screen space bounding box must intersect searchRegion - which is also specified in screen space.

See also

FindNextFocus

GetScreenSpaceFocusRegion()

static CYIAABB CYIFocus::GetScreenSpaceFocusRegion ( const CYISceneView *  pView )

static

Returns the clip box of pView if clipping is on. Otherwise the bounding box representing the size of the view is returned.

The returned value is expressed in screen space. If pView is null, returns a default constructed CYIAABB.

IsAbsoluteDirection()

static bool CYIFocus::IsAbsoluteDirection ( Direction  direction )

static

Returns true if direction is an absolute focus direction.

Absolute focus directions are Direction::Up, Direction::Down, Direction::Left, Direction::Right.

IsRelativeDirection()

static bool CYIFocus::IsRelativeDirection ( Direction  direction )

static

Returns true if direction is a relative focus direction.

Relative focus directions are Direction::Forward and Direction::Reverse.

---

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

• focus/YiFocus.h