limestone/VirtualList

Edit on GitHub

Provides Limestone-themed virtual list components and behaviors.

Members

VirtualList Component

A Limestone-styled scrollable and spottable virtual list component.

Extends: ui/VirtualListui/VirtualList.VirtualListBasic

Properties

Required Property • itemSize

Numberui/VirtualList.itemSizesShape

Size of an item for the VirtualList; valid value is a number generally. For different item size, value is an object that has minSize and size as properties. If the direction for the list is vertical, itemSize means the height of an item. For horizontal, it means the width of an item.

Usage:

<VirtualList itemSize={ri.scale(144)} />

cbScrollTo

Function

A callback function that receives a reference to the scrollTo feature.

Once received, the scrollTo method can be called as an imperative interface.

The scrollTo function accepts the following parameters:

{position: {x, y}} - Pixel value for x and/or y position
{align} - Where the scroll area should be aligned. Values are: 'left', 'right', 'top', 'bottom', 'topleft', 'topright', 'bottomleft', and 'bottomright'.
{index} - Index of specific item. (0 or positive integer) This option is available for only VirtualList kind.
{node} - Node to scroll into view
{animate} - When true, scroll occurs with animation. When false, no animation occurs.
{focus} - When true, attempts to focus item after scroll. Only valid when scrolling by index or node.

Note: Only specify one of: position, align, index or node

Example:

// If you set cbScrollTo prop like below;
cbScrollTo: (fn) => {this.scrollTo = fn;}
// You can simply call like below;
this.scrollTo({align: 'top'}); // scroll to the top

continue5WayHold

Boolean

When this value is true, scrolling in a VirtualList with holding a 5-way key continues to outer Scoller.

data-webos-voice-disabled

Boolean

Disable voice control feature of component.

data-webos-voice-focused

Boolean

Activates the component for voice control.

data-webos-voice-group-label

String

The voice control group label.

direction

'horizontal''vertical'

The layout direction of the list.

Default: 'vertical'

horizontalScrollbar

'auto''visible''hidden'

Specifies how to show horizontal scrollbar.

Default: 'auto'

horizontalScrollThumbAriaLabel

String

Sets the hint string read when focusing the scroll thumb in the horizontal scroll bar.

Default: $L('scroll up or down with up down button')

hoverToScroll

Boolean

Enables scroll by hover on edges in scroll direction.

id

String

Unique identifier for the component.

When defined and when the VirtualList is within a limestone/Panelslimestone/Panels.Panel, the VirtualList will store its scroll position and restore that position when returning to the Panel.

noScrollByWheel

Boolean

Prevents scroll by wheeling on the list.

Default: false

onScroll

Function

Called when scrolling.

Passes scrollLeft, scrollTop, and moreInfo. It is not recommended to set this prop since it can cause performance degradation. Use onScrollStart or onScrollStop instead.

onScrollStart

Function

Called when scroll starts.

Passes scrollLeft, scrollTop, and moreInfo. You can get firstVisibleIndex and lastVisibleIndex from VirtualList with moreInfo.

Example:

onScrollStart = ({scrollLeft, scrollTop, moreInfo}) => {
    const {firstVisibleIndex, lastVisibleIndex} = moreInfo;
    // do something with firstVisibleIndex and lastVisibleIndex
}

render = () => (
    <VirtualList
        ...
        onScrollStart={this.onScrollStart}
        ...
    />
)

onScrollStop

Function

Called when scroll stops.

Passes scrollLeft, scrollTop, and moreInfo. You can get firstVisibleIndex and lastVisibleIndex from VirtualList with moreInfo.

Example:

onScrollStop = ({scrollLeft, scrollTop, moreInfo}) => {
    const {firstVisibleIndex, lastVisibleIndex} = moreInfo;
    // do something with firstVisibleIndex and lastVisibleIndex
}

render = () => (
    <VirtualList
        ...
        onScrollStop={this.onScrollStop}
        ...
    />
)

role

String

The ARIA role for the list.

Default: 'list'

scrollMode

String

Specifies how to scroll.

Valid values are:

'translate',
'native'.

Default: 'native'

spotlightId

String

The container id for spotlight/SpotlightContainerDecorator/#SpotlightContainerDecoratorspotlight/SpotlightContainerDecorator/#SpotlightContainerDecorator.spotlightId.

It is a required prop to restore focus after remounting VirtualList.

For example, with this prop specified, when a VirtualList is used in a limestone/Panelslimestone/Panels.Panel, the Spotlight will store the last focus information based on SpotlightId while navigating to another Panel. And the VirtualList will restore the focus when it remounts while the navigation returns to the Panel.

stickTo

'start'

Anchors the focused item to a fixed "focus position" at the start edge while the list scrolls beneath it.

When set to 'start', moving focus with 5-way keys keeps the focus indicator at a fixed slot at the start of the list (top for vertical, leading edge for horizontal) and scrolls so the newly focused item lands in that slot. At the end of the list, the list scrolls only to its last position so the focused item stays visible.

This is ignored when snapToCenter is set.

verticalScrollbar

'auto''visible''hidden'

Specifies how to show vertical scrollbar.

Valid values are:

'auto',
'visible', and
'hidden'.

Default: 'auto'

verticalScrollThumbAriaLabel

String

Sets the hint string read when focusing the scroll thumb in the vertical scroll bar.

Default: $L('scroll left or right with left right button')

wrap

Boolean'noAnimation'

When it's true and the spotlight focus cannot move to the given direction anymore by 5-way keys, a list is scrolled with an animation to the other side and the spotlight focus moves in wraparound manner.

When it's 'noAnimation', the spotlight focus moves in wraparound manner as same as when it's true except that a list is scrolled without an animation.

Valid values are:

false,
true, and
'noAnimation'

Default: false

VirtualGridList Component

A Limestone-styled scrollable and spottable virtual grid list component.

Extends: ui/VirtualListui/VirtualList.VirtualListBasic

Properties

Required Property • itemSize

ui/VirtualList.gridListItemSizeShape

Size of an item for the VirtualGridList; valid value is an object that has minWidth and minHeight as properties.

Usage:

<VirtualGridList
	itemSize={{
		minWidth: ri.scale(360),
		minHeight: ri.scale(540)
	}}
/>

cbScrollTo

Function

A callback function that receives a reference to the scrollTo feature.

Once received, the scrollTo method can be called as an imperative interface.

The scrollTo function accepts the following parameters:

{position: {x, y}} - Pixel value for x and/or y position
{align} - Where the scroll area should be aligned. Values are: 'left', 'right', 'top', 'bottom', 'topleft', 'topright', 'bottomleft', and 'bottomright'.
{index} - Index of specific item. (0 or positive integer) This option is available for only VirtualList kind.
{node} - Node to scroll into view
{animate} - When true, scroll occurs with animation. When false, no animation occurs.
{focus} - When true, attempts to focus item after scroll. Only valid when scrolling by index or node.

Note: Only specify one of: position, align, index or node

Example:

// If you set cbScrollTo prop like below;
cbScrollTo: (fn) => {this.scrollTo = fn;}
// You can simply call like below;
this.scrollTo({align: 'top'}); // scroll to the top

continue5WayHold

Boolean

When this value is true, scrolling in a VirtualGridList with holding a 5-way key continues to outer Scroller.

data-webos-voice-disabled

Boolean

Disable voice control feature of component.

data-webos-voice-focused

Boolean

Activates the component for voice control.

data-webos-voice-group-label

String

The voice control group label.

direction

'horizontal''vertical'

The layout direction of the list.

Default: 'vertical'

horizontalScrollbar

'auto''visible''hidden'

Specifies how to show horizontal scrollbar.

Default: 'auto'

horizontalScrollThumbAriaLabel

String

Sets the hint string read when focusing the scroll thumb in the horizontal scroll bar.

Default: $L('scroll up or down with up down button')

hoverToScroll

Boolean

Enables scroll by hover on edges in scroll direction.

id

String

Unique identifier for the component.

When defined and when the VirtualGridList is within a limestone/Panelslimestone/Panels.Panel, the VirtualGridList will store its scroll position and restore that position when returning to the Panel.

noAffordance

Boolean

Removes affordance area on the list. Set this to true only if the item needs to stick to the bottom for vertical direction, to the right for horizontal direction, when scrolling by keys.

Default: false

noScrollByWheel

Boolean

Prevents scroll by wheeling on the list.

Default: false

onScroll

Function

Called when scrolling.

Passes scrollLeft, scrollTop, and moreInfo. It is not recommended to set this prop since it can cause performance degradation. Use onScrollStart or onScrollStop instead.

onScrollStart

Function

Called when scroll starts.

Passes scrollLeft, scrollTop, and moreInfo. You can get firstVisibleIndex and lastVisibleIndex from VirtualGridList with moreInfo.

Example:

onScrollStart = ({scrollLeft, scrollTop, moreInfo}) => {
    const {firstVisibleIndex, lastVisibleIndex} = moreInfo;
    // do something with firstVisibleIndex and lastVisibleIndex
}

render = () => (
    <VirtualGridList
        ...
        onScrollStart={this.onScrollStart}
        ...
    />
)

onScrollStop

Function

Called when scroll stops.

Passes scrollLeft, scrollTop, and moreInfo. You can get firstVisibleIndex and lastVisibleIndex from VirtualGridList with moreInfo.

Example:

onScrollStop = ({scrollLeft, scrollTop, moreInfo}) => {
    const {firstVisibleIndex, lastVisibleIndex} = moreInfo;
    // do something with firstVisibleIndex and lastVisibleIndex
}

render = () => (
    <VirtualGridList
        ...
        onScrollStop={this.onScrollStop}
        ...
    />
)

role

String

The ARIA role for the list.

Default: 'list'

scrollMode

String

Specifies how to scroll.

Valid values are:

'translate',
'native'.

Default: 'native'

snapToCenter

Boolean

When it's true, the item snaps to center.

spotlightId

String

The container id for spotlight/SpotlightContainerDecorator/#SpotlightContainerDecoratorspotlight/SpotlightContainerDecorator/#SpotlightContainerDecorator.spotlightId.

It is a required prop to restore focus after remounting VirtualGridList.

For example, with this prop specified, when a VirtualGridList is used in a limestone/Panelslimestone/Panels.Panel, the Spotlight will store the last focus information based on SpotlightId while navigating to another Panel. And the VirtualGridList will restore the focus when it remounts while the navigation returns to the Panel.

stickTo

'start'

Anchors the focused item to a fixed "focus position" at the start edge while the list scrolls beneath it.

This is ignored when snapToCenter is set.

verticalScrollbar

'auto''visible''hidden'

Specifies how to show vertical scrollbar.

Valid values are:

'auto',
'visible', and
'hidden'.

Default: 'auto'

verticalScrollThumbAriaLabel

String

Sets the hint string read when focusing the scroll thumb in the vertical scroll bar.

Default: $L('scroll left or right with left right button')

wrap

Boolean'noAnimation'

When it's 'noAnimation', the spotlight focus moves in wraparound manner as same as when it's true except that a list is scrolled without an animation.

Valid values are:

false,
true, and
'noAnimation'

Default: false