KeyboardPagedCursorMixin

Maps the Page Up and Page Down keys to item cursor operations

Overview

Purpose: map the Page Up and Page Down keys to a cursor operation.

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

events → methodssetState → render DOM → post-render

Expects the component to provide:

  • currentIndex state member updatable.
  • internal.keydown method, usually defined by KeyboardMixin.

Provides the component with:

  • Mappings from page navigation keyboard events to cursor operations.

Usage

import KeyboardPagedCursorMixin from "elix/src/base/KeyboardPagedCursorMixin.js";
class MyElement extends KeyboardPagedCursorMixin(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 move the item cursor, rather than just scrolling. (In single-selection lists, this also moves the selection.) This Windows behavior lets the user see where the selection is, and more 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 KeyboardPagedCursorMixin only updates the cursor by setting the cursorIndex state member. It does not itself scroll the component. That responsibility can be fulfilled with CursorInViewMixin.

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, Menu, MultiSelectListBox, OptionList, PlainFilterListBox, PlainListBox, PlainMenu, PlainMultiSelectListBox, and PlainOptionList.

pageDown() method

Scroll down one page.

pageUp() method

Scroll up one page.

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 scrollTarget.

Type: HTMLElement