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 → render DOM → post-render

Expects the component to provide:

  • [internal.state].selectedIndex state member updatable via setState.
  • internal.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
Akee
Apple
Apricot
Avocado
Banana
Bilberry
Black sapote
Blackberry
Blackcurrant
Blood orange
Blueberry
Boysenberry
Cantaloupe
Cherimoya
Cherry
Chico fruit
Clementine
Cloudberry
Coconut
Crab apple
Cranberry
Cucumber
Currant
Damson
Date
Dragonfruit
Durian
Elderberry
Feijoa
Fig
Goji berry
Gooseberry
Grape
Grapefruit
Guava
Honeyberry
Honeydew
Horned melon
Huckleberry
Jabuticaba
Jackfruit
Jambul
Japanese plum
Jostaberry
Jujube
Juniper berry
Kiwifruit
Kumquat
Lemon
Lime
Longan
Loquat
Lychee
Mandarin
Mango
Mangosteen
Marionberry
Miracle fruit
Mulberry
Nance
Nectarine
Orange
Papaya
Passionfruit
Peach
Pear
Persimmon
Pineapple
Pineberry
Plantain
Plum
Pluot
Pomegranate
Pomelo
Purple mangosteen
Quince
Rambutan
Raspberry
Redcurrant
Salak
Salal berry
Salmonberry
Satsuma
Soursop
Star apple
Star fruit
Strawberry
Surinam cherry
Tamarillo
Tamarind
Tangerine
Ugli fruit
Watermelon
White currant
White sapote
Yuzu
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 internal.keydown being invoked. That will typically be done with KeyboardMixin, but you can also invoke that yourself.

API

Used by classes FilterListBox, ListBox, and Menu.

[internal.scrollTarget] property

The element that will be scrolled when the user presses Page Up or Page Down. The default value is calculated by defaultScrollTarget.

See internal.scrollTarget.

Type: HTMLElement

pageDown() method

Scroll down one page.

pageUp() method

Scroll up one page.