Overview
Purpose: handles list box-style prefix typing, in which the user can type a string to move to the first item that begins with that string.
This mixin works in the middle of the Elix render pipeline:
events → methods ➞ setState → render DOM → post-render
Expects the component to provide:
[internal.state].texts
state member containing an array of text strings corresponding to the text content of the current set of items. You can supply that with ItemsTextMixin.currentIndex
state member, e.g., via ItemsCursorMixin.internal.keydown
method, usually defined by KeyboardMixin.
Provides the component with:
- Mappings of keyboard events to cursor operations.
Usage
import ItemsCursorMixin from "elix/src/base/ItemsCursorMixin.js";
import ItemsTextMixin from "elix/src/base/ItemsTextMixin.js";
import KeyboardMixin from "elix/src/base/KeyboardMixin.js";
import KeyboardPrefixCursorMixin from "elix/src/base/KeyboardPrefixCursorMixin.js";
class MyElement extends ItemsCursorMixin(
ItemsTextMixin(KeyboardMixin(KeyboardPrefixCursorMixin(HTMLElement)))
) {}
Example
If this component receives the focus, and you press the "b" or "B" key, the "Banana" item will be selected, because it's the first item that matches the prefix "b". (Matching is case-insensitive.) If you now presses the "l" or "L" key quickly, the prefix to match becomes "bl", so "Blackberry" will be selected.
The prefix typing feature has a one second timeout — the prefix to match will be reset after a second has passed since you last typed a key. If, in the above example, you wait a second between typing "b" and "l", the timeout will reset the prefix to empty. When the "l" key is pressed, "Lemon" will be selected.
If you press the Backspace key, the last character is removed from the prefix under construction. This re-selects the first item that matches the new, shorter prefix. Suppose you type "c", and "Cantaloupe" is selected, then type "h" to select "Cherry". If you now immediately press Backspace (before the aforementioned one second timeout elapses), the prefix will revert to "C", and "Cantaloupe" will be reselected.
Extracting item text
To extract the text of an item, the mixin invokes a method internal.getItemText on each item. The default behavior of that method is to return the item's aria-label
attribute, alt
attribute or, if that does not exist, its textContent
. This allows a component user to customize which text the prefix will be matched against.
API
Used by classes FilterListBox, ListBox, Menu, MultiSelectListBox, OptionList, PlainFilterListBox, PlainListBox, PlainMenu, PlainMultiSelectListBox, and PlainOptionList.
go To Item With Prefix(prefix) method
Go to the first item whose text content begins with the given prefix.
Parameters:
- prefix:
string
– The prefix string to search for
Returns: boolean