Overview
Purpose: maps direction semantics (e.g., up or down) to item cursor semantics (e.g., go previous or go next).
This mixin works in the middle of the Elix render pipeline:
events → methods ➞ methods → setState → render DOM → post-render
Expects the component to provide:
internal.goNext
,internal.goPrevious
,internal.goLast
,internal.goFirst
methods.
Provides the component with:
internal.goDown
,internal.goEnd
,internal.goLeft
,internal.goRight
,internal.goStart
,internal.goUp
that map to cursor methods. See below.
canGoDown
,canGoLeft
,canGoRight
, andcanGoUp
state members to indicate whether it is currently possible for the user to navigate in the indicate directions.
Usage
import DirectionCursorMixin from "elix/src/base/DirectionCursorMixin.js";
class MyElement extends DirectionCursorMixin(HTMLElement) {}
This mixin is designed to complement input mixins that map input events to directions, including ArrowDirectionMixin, KeyboardDirectionMixin, and TouchSwipeMixin. Those mixins can focus exclusively on direction. You can use DirectionCursorMixin
to map those directions (e.g., left and right) to item cursor operations (e.g., go previous and go next). The level of abstraction provided by DirectionCursorMixin
allows the input mixins to be used that don't deal with a cursor, and want to interpret direction semantics in other ways.
Mapping direction semantics to item cursor semantics
When a direction method with a standard identifier is invoked, a corresponding cursor method is invoked:
- internal.goDown →
internal.goNext
- internal.goEnd →
internal.goLast
- internal.goLeft →
internal.goPrevious
(orinternal.goNext
in right-to-left languages) - internal.goRight →
internal.goNext
(orinternal.goPrevious
in right-to-left languages) - internal.goStart →
internal.goFirst
- internal.goUp →
internal.goPrevious
If the component has a rightToLeft
property that is true, the mapping of left/right to previous/next is reversed. That is, going left means going to the next item, not the previous one. You can define such a rightToLeft
property with LanguageDirectionMixin.
A common use of DirectionCursorMixin
will be to connect the KeyboardMixin and KeyboardDirectionMixin above to the Elix ItemsCursorMixin and a mixin like SingleSelectAPIMixin. This effectively creates a chain of actions that convert keyboard events to changes in selection.
Example: a press of the Down arrow key can be handled in the following steps:
- KeyboardMixin receives the
keydown
event for the Down arrow key and invokes the component'sinternal.keydown
method. - KeyboardDirectionMixin handles
internal.keydown
for the key, and invokesinternal.goDown
. DirectionCursorMixin
handlesinternal.goDown
and invokesinternal.goNext
.- ItemsCursorMixin handles
internal.goNext
and updates the current item. - SingleSelectAPIMixin raises the
selectedindexchange
event.
This sequence may seem circuitous, but factoring the behaviors this way allows other forms of interaction. E.g., a separate mixin to handle touch gestures only has to map a "swipe left" gesture to a direction method like goRight
in order to patch into this chain. This saves the touch logic from having to know anything about selection.
API
Used by classes Carousel, CarouselSlideshow, CarouselWithThumbnails, FilterListBox, ListBox, Menu, MultiSelectListBox, OptionList, PlainCarousel, PlainCarouselSlideshow, PlainCarouselWithThumbnails, PlainFilterListBox, PlainListBox, PlainMenu, PlainMultiSelectListBox, PlainOptionList, PlainSlideshowWithPlayControls, PlainSlidingPages, PlainTabStrip, SlideshowWithPlayControls, SlidingPages, and TabStrip.
go Down() method
Interprets goDown
to mean "move to the next item".
go End() method
Interprets goEnd
to mean "move to the last item".
go Left() method
Interprets goLeft
to mean "move to the previous item".
If the element has a rightToLeft
property and it is true, then this
moves to the next item.
go Right() method
Interprets goRight
to mean "move to the next item".
If the element has a rightToLeft
property and it is true, then this
moves to the previous item.
go Start() method
Interprets goStart
to mean "move to the first item".
go Up() method
Interprets goUp
to mean "move to the previous item".