KeyboardPagedSelectionMixin

Maps the Page Up and Page Down keys to selection operations

Overview

Purpose: map the Page Up and Page Down keys to selection operations.

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

events → methodssetState → updates → render DOM → post-render

Expects the component to provide:

  • state.selectedIndex state member updatable via setState.
  • symbols.keydown method, usually defined by KeyboardMixin.

Provides the component with:

  • Mappings from page navigation keyboard events to selection operations.

Usage

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

Example

The following ListBox shows the mixin in use:

Acai
Acerola
Apple
Apricot
Banana
Blackberry
Blueberry
Cantaloupe
Cherry
Cranberry
Currant
Date
Durian
Fig
Goji berry
Gooseberry
Grape
Grapefruit
Honeydew
Jackfruit
Kiwi
Kumquat
Lemon
Lime
Lychee
Mango
Mangosteen
Mulberry
Nectarine
Orange
Papaya
Passion Fruit
Peach
Pear
Pineapple
Plum
Pomegranate
Pomelo
Prickly Pear
Raspberry
Strawberry
Tangerine
Watermelon
Demo: A list box that supports Page Up and Page Down

The paging behavior is modeled after that of standard Microsoft Windows list boxes, which seem to provide more useful keyboard paging than those in macOS:

  • The Page Up and Page Down keys actually change the selection, rather than just scrolling. The former behavior seems more generally useful for keyboard users, as they can see where the selection is, and can easily refine the selection after paging by using the arrow keys.

  • Pressing Page Up/Page Down will change the selection to the topmost/bottommost visible item if the selection is not already there. Thereafter, the key will move the selection up/down by a page.

The KeyboardPagedSelectionMixin only updates the selection by setting the selectedIndex property. It does not itself scroll the component. That responsibility can be fulfilled with SelectionInViewMixin.

This mixin relies on symbols.keydown being invoked. That will typically be done with KeyboardMixin, but you can also invoke that yourself.

API

Used by classes ListBox and Menu.

getIndexOfItemAtY() method

Return the item whose content spans the given y position (relative to the top of the list's scrolling client area), or null if not found.

If downward is true, move down the list of items to find the first item found at the given y position; if downward is false, move up the list of

items to find the last item at that position.

KeyboardPagedSelection#symbols.scrollTarget property

Type: HTMLElement

pageDown() method

Scroll down one page.

pageUp() method

Scroll up one page.

scrollOnePage() method

Move by one page downward (if downward is true), or upward (if false). Return true if we ended up changing the selection, false if not.