You.i Engine
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 CYISceneViewFindNextFocus (const CYISceneNode *pSearchRoot, const CYIAABB &previousFocusRect, Direction direction, const CYIFocusSearchOptions &options=CYIFocusSearchOptions())
 
static CYISceneViewFindInitialFocus (const CYISceneNode *pSearchRoot, const CYIFocusSearchOptions &options=CYIFocusSearchOptions())
 
static CYISceneViewFindNextFocusInRegion (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

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: