ItemsSelection.md

API Documentation

ItemsSelection

Mixin which manages single-selection semantics for items in a list.

This mixin expects a component to provide an items array of all elements in the list. A standard way to do that with is the ContentAsItems mixin, which takes a component's content (typically its distributed children) as the set of list items; see that mixin for details.

This mixin tracks a single selected item in the list, and provides means to get and set that state by item position (selectedIndex) or item identity (selectedItem). The selection can be moved in the list via the methods selectFirst, selectLast, selectNext, and selectPrevious.

This mixin does not produce any user-visible effects to represent selection. Other mixins, such as SelectionAriaActive, SelectionHighlight and SelectionInView, modify the selected item in common ways to let the user know a given item is selected or not selected.

Kind: global class

• ItemsSelection
  • .applySelection(item, selected)
  • .canSelectNext : boolean
  • .canSelectPrevious : boolean
  • .itemAdded(item)
  • "selected-index-changed"
  • "selected-item-changed"
  • .selectedIndex : number
  • .selectedItem : object
  • .selectFirst()
  • .selectionRequired : boolean
  • .selectLast()
  • .selectNext()
  • .selectPrevious()

itemsSelection.applySelection(item, selected)

Apply the indicate selection state to the item.

The default implementation of this method does nothing. User-visible effects will typically be handled by other mixins.

Kind: instance method of ItemsSelection

Param	Type	Description
item	HTMLElement	the item being selected/deselected
selected	boolean	true if the item is selected, false if not

itemsSelection.canSelectNext : boolean

True if the selection can be moved to the next item, false if not (the selected item is the last item in the list).

Kind: instance property of ItemsSelection

itemsSelection.canSelectPrevious : boolean

True if the selection can be moved to the previous item, false if not (the selected item is the first one in the list).

Kind: instance property of ItemsSelection

itemsSelection.itemAdded(item)

Handle a new item being added to the list.

The default implementation of this method simply sets the item's selection state to false.

Kind: instance method of ItemsSelection

Param	Type	Description
item	HTMLElement	the item being added

"selected-index-changed"

Fires when the selectedIndex property changes.

Kind: event emitted by ItemsSelection

Param	Type	Description
detail.selectedIndex	number	The new selected index.

"selected-item-changed"

Fires when the selectedItem property changes.

Kind: event emitted by ItemsSelection

Param	Type	Description
detail.selectedItem	HTMLElement	The new selected item.
detail.previousItem	HTMLElement	The previously selected item.

itemsSelection.selectedIndex : number

The index of the item which is currently selected, or -1 if there is no selection.

Setting the index to -1 deselects any current-selected item.

Kind: instance property of ItemsSelection

itemsSelection.selectedItem : object

The currently selected item, or null if there is no selection.

Setting this property to null deselects any currently-selected item.

Kind: instance property of ItemsSelection

itemsSelection.selectFirst()

Select the first item in the list.

Kind: instance method of ItemsSelection

itemsSelection.selectionRequired : boolean

True if the list should always have a selection (if it has items).

Kind: instance property of ItemsSelection

itemsSelection.selectLast()

Select the last item in the list.

Kind: instance method of ItemsSelection

itemsSelection.selectNext()

Select the next item in the list.

Kind: instance method of ItemsSelection

itemsSelection.selectPrevious()

Select the previous item in the list.

Kind: instance method of ItemsSelection