You.i Engine
Public Types | Static Public Member Functions | List of all members
CYIFocus Class Reference
Utilities

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 <utility/YiFocus.h>

Public Types

enum  FOCUS_DIRECTION {
  FOCUS_UP,
  FOCUS_DOWN,
  FOCUS_RIGHT,
  FOCUS_LEFT,
  FOCUS_FORWARD,
  FOCUS_REVERSE,
  FOCUS_MAX
}
 
enum  FOCUS_ROOT_RULE {
  FOCUS_ROOT_DESCENDANTS,
  FOCUS_ROOT_DESCENDANTS_UPDATE_CONTEXT,
  FOCUS_ROOT_ANY
}
 

Static Public Member Functions

static CYISceneView * FindNextFocus (const CYISceneNode *pSearchRoot, const CYIAABB &previousFocusRect, FOCUS_DIRECTION eDirection, const CYIFocusSearchOptions &options=CYIFocusSearchOptions())
 
static CYISceneView * FindInitialFocus (const CYISceneNode *pSearchRoot, const CYIFocusSearchOptions &options=CYIFocusSearchOptions())
 
static CYISceneView * FindNextFocusInRegion (const CYISceneNode *pSearchRoot, const CYIAABB &previousFocusRect, FOCUS_DIRECTION eDirection, const CYIAABB &searchRegion, const CYIFocusSearchOptions &options=CYIFocusSearchOptions())
 
static CYIAABB GetScreenSpaceFocusRegion (const CYISceneView *pView)
 
static bool IsRelativeDirection (FOCUS_DIRECTION eDirection)
 
static bool IsAbsoluteDirection (FOCUS_DIRECTION eDirection)
 

Member Enumeration Documentation

enum CYIFocus::FOCUS_DIRECTION

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

Enumerator
FOCUS_UP 

Corresponds to CYIKeyEvent::YI_KEY_ARROW_UP. Represents up on screen.

FOCUS_DOWN 

Corresponds to CYIKeyEvent::YI_KEY_ARROW_DOWN. Represents down on screen.

FOCUS_RIGHT 

Corresponds to CYIKeyEvent::YI_KEY_RIGHT. Represents right on screen.

FOCUS_LEFT 

Corresponds to CYIKeyEvent::YI_KEY_ARROW_LEFT. Represents left on screen.

FOCUS_FORWARD 

Corresponds to CYIKeyEvent::YI_KEY_TAB. Represents navigation to the next focusable item.

FOCUS_REVERSE 

Corresponds to CYIKeyEvent::YI_KEY_TAB a shift modifier (CYIKeyEvent::m_bShiftKey is true). Represents navigation to the previous focusable item.

FOCUS_MAX 

Represents the number of items in this enum, not a valid FOCUS_DIRECTION.

enum CYIFocus::FOCUS_ROOT_RULE

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

FOCUS_ROOT_DESCENDANTS_UPDATE_CONTEXT 

Similar to CYIFocus::FOCUS_ROOT_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

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

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::FOCUS_FORWARD direction.

See also
FindNextFocus
static CYISceneView* CYIFocus::FindNextFocus ( const CYISceneNode *  pSearchRoot,
const CYIAABB &  previousFocusRect,
FOCUS_DIRECTION  eDirection,
const CYIFocusSearchOptions &  options = CYIFocusSearchOptions() 
)
static

Returns the next view capable of receiving focus (if any) in eDirection, 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.

static CYISceneView* CYIFocus::FindNextFocusInRegion ( const CYISceneNode *  pSearchRoot,
const CYIAABB &  previousFocusRect,
FOCUS_DIRECTION  eDirection,
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
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.

static bool CYIFocus::IsAbsoluteDirection ( FOCUS_DIRECTION  eDirection)
static

Returns true if eDirection is an absolute focus direction.

Absolute focus directions are FOCUS_UP, FOCUS_DOWN, FOCUS_LEFT, FOCUS_RIGHT.

static bool CYIFocus::IsRelativeDirection ( FOCUS_DIRECTION  eDirection)
static

Returns true if eDirection is a relative focus direction.

Relative focus directions are FOCUS_FORWARD and FOCUS_REVERSE.

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