cee614506b
Co-authored-by: Saadat Azim |
||
---|---|---|
demo | ||
src | ||
test | ||
.editorconfig | ||
.gitignore | ||
.npmignore | ||
.npmrc | ||
.travis.yml | ||
LICENSE | ||
gulpfile.js | ||
package-lock.json | ||
package.json | ||
readme.md | ||
tsconfig.json | ||
tslint.json |
readme.md
arcade-machine
arcade-machine is an Angular plugin to provide navigation and interactive semantics using the GamePad API. This allows the application to be navigated using a controller connected to a PC, the PC's keyboard, or on Universal Windows Platform (UWP) web applications running on the Xbox.
See the reference controller for mappings with buttons.
We use WinJS' navigation algorithm to move between focusable components on the page. Most interactive components, including link tags <a>
, buttons, and form controls are able to receive focus by default, and for those which are not focusable by default you can use the arc
directive.
Here we have a basic app which contains three buttons. The user can use their joystick to navigate between each selectable button. Note that the app itself is marked as focusable; this is how bootstrapping is done. More on this in a minute.
<my-app arc> <button>Button 1</button> <button>Button 2</button> <button>Button 3</button> </my-app>
For the majority of navigation, we represent controller actions as keyboard events; the left joystick or arrow keys on a keyboard can be used to fire up, down, left, and right events in order to navigate the page. We determine the next element to focus in a direction using WinJS' algorithm based on each focusable element's physical location, but you can also fine tune what happens when via directives. This can help to avoid inaccessible UI and provide more fined-tuned experiences on each platform.
By default only elements that explicity have
tabindex >= 0
are considered for focus
Demo App
You can see a demo Angular 2 app in the demo
folder and run it locally with npm start
.
Usage
Directives & Attributes
arc
You must define arc
directive on element which you want to be focusable that are not otherwise focusable, or when you want to define custom logic. That is, anything except the following tags:
a
button
input
select
textarea
[arc-exclude-this]="value"
You can pass a value to arc-exclude-this
which, if not false
, exclude this element from arcade-machine's focus.
[arc-exclude]="value"
You can pass a value to arc-exclude-this
which, if not false
, exclude this element and all its children from arcade-machine's focus.
[arc-set-focus]="Observable<boolean>"
You can pass an Observable to arc-set-focus
which, when fired, will forcefully cause the element to be focused.
arc-default-focus
When arc-focus
is on an element, that element will steal the page focus when it's instantiated. Setting this is a shortcut to passing Observable.of(undefined)
to arc-set-focus
to immediately trigger a focus capture.
It can also be used with *ngFor. For instance, following will focus the 3rd element in ngFor
<div
*ngFor="let box of boxes; let i = index"
arc [arc-default-focus]="i === 2">
</div>
arc-focus-inside
If arc-focus-inside is present on a focusable element; on focus, it transfers the focus to its next best child element. This is particularly useful to make elements focusable that are not directly in the focus direction.
<div tabindex="0" arc arc-focus-inside="true">
<div tabindex="0">I will be focused instead</div>
</div>
(arc-capture-outgoing)="onEvent(IArcEvent)"
arc-capture-outgoing
can be set to handle, and possibly cancel, events sent while the element or one of its children are focused. See the IArcEvent
type for more details:
(arc-capture-incoming)="onEvent(IArcEvent)"
arc-capture-incoming
can be set to handle, and possibly cancel, events sent while the element is the next target of navigation. See the IArcEvent
type for more details:
/**
* IArcEvents are fired on an element when an input occurs. They include
* information about the input and provide utilities similar to standard
* HTML events.
*/
export interface IArcEvent {
// The 'arc' directive reference, may not be filled for elements which
// are focusable without the directive, like form controls.
readonly directive?: IArcHandler;
// `next` is the element that we'll select next, on directional navigation,
// unless the element is cancelled. This *is* settable and you can use it
// to modify the focus target. This will be set to `null` on non-directional
// navigation or if we can't find a subsequent element to select.
next?: Element;
readonly event: Direction;
readonly target: Element;
readonly defaultPrevented: boolean;
stopPropagation(): void;
preventDefault(): void;
}
/**
* Direction is an enum of possible gamepad events which can fire.
*/
export enum Direction {
SUBMIT = 0,
BACK = 1,
X = 2,
Y = 3,
TABLEFT = 4, // Left Bumper
TABRIGHT = 5, // Right Bumper
TABUP = 6, // Left Trigger
TABDOWN = 7, // Right Trigger
UP = 12,
DOWN = 13,
LEFT = 14,
RIGHT = 15,
}
(arc-focus)="onFocusChange(Element?)"
arc-focus
is an event that's fired when the element or any of its children gain or lose focus. The newly-selected element will be passed to the function, and null
will be passed if none of the elements in the node's tree are selected.
(arc-submit)="onSubmit(IArcEvent)"
arc-submit
is a shortcut to create a handler via arc-capture-outgoing
that fires when a "submit" event is fired.
(arc-back)="onBack(IArcEvent)"
arc-back
is a shortcut to create a handler via arc-capture-outgoing
that fires when a "back" event is fired.
[arc-[left|right|up|down]]="Element"
Allows you to explicitly tell the directive which element to focus when off the element in the provided direction. Again, this is a shortcut to a arc-capture-outgoing
handler which sets the next
element if it matches the target direction.
[arc-focus-[left|right|up|down]]="Element | CSSQueryString"
Allows you to explicitly tell the directive which element to focus when off the element in the provided direction. This will take precedence over all other FindFocus strategies
Focus Service
trapFocus
trapFocus(newRootElem: HTMLElement)
To trap the focus inside newRootElem. To release the focus, call releaseFocus
releaseFocus
releaseFocus(releaseElem?: HTMLElement)
To trap the release the previously trapped focus. Multiple call to this method will precedurally remove focus traps all the way up to body. Further calls without releaseElem param will throw a warning on console while keeping the focus at body. If releaseElem is provided, this method will release focus only if the last trapped focus element was releaseElem.
releaseFocus
clearAllTraps()
Useful for resetting all focus traps e.g. on page navigation
Classes
By default, the arc--selected-direct
class is added to the selected node.
Events
arcselectingnode
Fired when arcade machine is about to select a node
arcfocuschanging
Fire when arcade-machine is about to call native focus method. This event can be canceled for example to smooth-scroll to the element before focusing it in browser.