DirectionSelectionMixin

Overview

Purpose: maps direction semantics (e.g., "down") to selection semantics ("selectNext").

This mixin works in the middle of the Elix render pipeline:

events → methodsmethods → setState → render → update DOM

Expects the component to provide:

  • selectNext, selectPrevious, selectLast, selectFirst methods.

Provides the component with:

  • symbols.canGoLeft, symbols.canGoRight properties.
  • symbols.goDown, symbols.goUp, symbols.goLeft, symbols.goRight methods.

Usage

import DirectionSelectionMixin from 'elix/src/DirectionSelectionMixin.js';
class MyElement extends DirectionSelectionMixin(HTMLElement) {}

This mixin is designed to complement input mixins that map input events to directions, including ArrowDirectionMixin, KeyboardDirectionMixin, and TouchSwipeMixin. Those mixins can focus exlusively on direction instead of selection. You can use DirectionSelectionMixin to map those directions to selection operations. The level of abstraction provided by DirectionSelectionMixin allows the input mixins to be used that don't deal with selection, and want to interpret direction semantics in other ways.

Mapping direction semantics to selection semantics

When a direction method with a standard identifier is invoked, a corresponding selection method is invoked:

*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. A typicaly way to define such a rightToLeft property is with LanguageDirectionMixin.

A common use of DirectionSelectionMixin will be to connect the KeyboardMixin and KeyboardDirectionMixin above to the Elix SingleSelectionMixin. 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:

  1. KeyboardMixin receives the keydown event for the Down arrow key and invokes the component's symbols.keydown method.
  2. KeyboardDirectionMixin handles symbols.keydown for the key, and invokes symbols.goDown.
  3. DirectionSelectionMixin handles symbols.goDown and invokes selectNext.
  4. SingleSelectionMixin handles selectNext and updates the selection.

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, ListBox, Menu, SlideshowWithPlayControls, SlidingPages, and TabStrip.

symbols.canGoLeft property

Returns true if it's currently possible to go left.

Type: boolean

symbols.canGoRight property

Returns true if it's currently possible to go right.

Type: boolean

symbols.goDown() method

Invokes selectNext to select the next item.

symbols.goEnd() method

Invokes selectLast to select the next item.

symbols.goLeft() method

Invokes selectPrevious to select the previous item.

If the element has a rightToLeft property and it is true, then this selects the next item.

symbols.goRight() method

Invokes selectNext to select the next item.

If the element has a rightToLeft property and it is true, then this selects the previous item.

symbols.goStart() method

Invokes selectFirst to select the first item.

symbols.goUp() method

Invokes selectPrevious to select the previous item.