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>
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) |
|
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. |
|
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.
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. |
|
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.
|
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.
|
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.
|
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 |
Returns true if direction is an absolute focus direction.
Absolute focus directions are Direction::Up, Direction::Down, Direction::Left, Direction::Right.
|
static |
Returns true if direction is a relative focus direction.
Relative focus directions are Direction::Forward and Direction::Reverse.