Carousel

A virtualized container of items that can be scrolled either horizontally or vertically. As scrolling occurs, a configured number of visible items (slots) are dynamically positioned and reconfigured to give the appearance that all items in the specified range are present.

To create a carousel, a configureSlot function must be provided that will return the configuration object for a given slot index. Slot index 0 is special, and whenever the range is not empty, 0 must be included in the range. The meaning of a slot index, however, is defined by the developer and only interpreted by the developer-provided configureSlot function.

Slot indexes are converted into virtual scroll positions and given to an InfinityScroller. This special scroller allows for negative scroll positioning as well as unbounded scroll range.

This widget is not intended to be used standalone, but as part of higher-level widgets such as MultiDatePicker.

Configs

120

Common

listenersEvents

Other

configureSlot: String | functionAlso a property

A callback function that must be provided by the developer to produce configuration objects for the slots in the carousel.

Derived classes may set this config to the name of the instance method to call. The this pointer will be the carousel instance.

Parameter	Type	Description
`index`	Number	The slot index as defined by the range of the carousel.
`carousel`	Carousel	The carousel instance.
`slot`	Widget	The slot being reconfigured or `null` when creating a new slot.

Returns: ContainerItemConfig -

The slot's configuration object.

currentIndex: NumberAlso a property

The first visible slot index. This first visible slot can be read or written using this property. Setting currentIndex will determine if the transition can be animated by the distance being traveled.

See goto.

disableReserveSlots: Boolean | inert= false

The value to set for the disabled config on reserve slots. These slots are not visible to the user but can be tabbed into from visible slots.

When set to 'inert', the inert DOM attribute is also set. This prevents tabbing from a visible slot to a reserved slot.

emptyHtml: StringAlso a property

The HTML to render when the carousel's range is empty. To avoid XSS attacks, it is safer to use emptyText instead.

emptyText: String= No items to displayAlso a property

The text to render when the carousel's range is empty. This text is automatically encoded and is safe from XSS issues. To render markup when the carousel is empty, see emptyHtml.

range: Number[]Also a property

The range of slot indexes to be presented in the carousel. Slot indexes greater than or equal to range[0] and less than range[1] will be rendered.

If this value is null or [0, 0], the carousel will render no items (i.e., it will be empty). See emptyText.

By default, the carousel's range is unlimited, i.e., range = [-Infinity, Infinity].

reserveSlots: Number= 1Also a property

The number of slots to render beyond what is visible in the carousel. These reserve items are critical to giving the appearance of continuity as the carousel is being scrolled. A minimum of 1 is required and is generally sufficient for slots that are reasonably large. If slots are small (maybe less than 100px), it may be helpful to provide additional reserve slots.

scrollOnTab: Boolean= falseAlso a property

Set to true to use trapFocus to scroll the carousel when tabbing to slots that are not currently visible.

NOTE: This only works when configureSlot produces Panel instances.

shrinkWrap: Boolean | auto= autoAlso a property

Due to the position: absolute nature of carousel items, a carousel does not have a natural size. When the carousel is being sized by its container, this is not a problem, but can be an issue if the carousel is being used in a layout where its natural size would be important.

Specify true for the carousel to provide a natural size based on the size of its slots. This is done by setting min-width and/or min-height on the internal elements that contain the absolutely positioned slots. This may have a modest performance impact due to the required measuring of the slots to provide these minimums.

By default (shrinkWrap = 'auto'), the carousel enables shrinkWrap support when the carousel's main element is position: absolute. This can be disabled by setting shrinkWrap = false.

slots: NumberAlso a property

The number of slots to present in the carousel. When set to a number, each slot is given a percentage size (e.g., "50%" for slots = 2) so they fill the carousel. This is typically required when the carousel is using shrinkWrap (note: shrink wrapping is enabled by default for position: absolute carousels).

When null, as many slots as needed to fill the carousel are created. This can produce partially visible slots.

Setting this value to 'auto' will similarly fill the available space, but once the required number of slots is determined, they are assigned a percentage size so that they completely fill the carousel.

snap: Boolean= trueAlso a property

Set to false to disable scroll snapping and allow free scrolling through the carousel.

vertical: Boolean= falseAlso a property

Set to true to enable vertical mode. By default, carousels scroll horizontally.

callOnFunctionsWidget

catchEventHandlerExceptionsEvents

columnWidget

defaultFocusContainer

detectCSSCompatibilityIssuesWidget

drawerPanel

inputFieldAlignContainer

labelPositionContainer

renditionContainer

rtlRTL

spanWidget

Accessibility

ariaDescriptionWidget

ariaLabelWidget

keyMapKeyMap

Content

bbarPanel

defaultsContainer

footerPanel

headerPanel

itemsContainer

lazyItemsContainer

namedItemsContainer

stripsPanel

tbarPanel

textContentContainer

toolsPanel

trapFocusPanel

CSS

bodyClsPanel

borderContainer

clsWidget

colorWidget

contentElementClsWidget

htmlClsWidget

itemClsContainer

styleWidget

uiPanel

DOM

adoptWidget

appendToWidget

contentWidget

datasetWidget

htmlWidget

idWidget

insertBeforeWidget

insertFirstWidget

tagWidget

Float & align

alignWidget

anchorWidget

centeredWidget

constrainToWidget

draggableWidget

floatingWidget

hideAnimationWidget

maximizeOnMobileWidget

positionedWidget

scrollActionWidget

showAnimationWidget

xWidget

yWidget

Layout

alignSelfWidget

collapsedPanel

collapsiblePanel

dockWidget

flexWidget

heightWidget

hiddenWidget

hideWhenEmptyContainer

layoutContainer

layoutStyleContainer

marginWidget

maxHeightWidget

maxWidthWidget

minHeightWidget

minWidthWidget

textAlignWidget

weightWidget

widthWidget

misc

tabBarItemsContainer

Misc

bubbleEventsEvents

dataFieldWidget

defaultBindPropertyWidget

disabledWidget

elementAttributesWidget

iconPanel

ignoreParentReadOnlyWidget

localeClassLocalizable

localizableLocalizable

localizablePropertiesLocalizable

maskDefaultsWidget

maskedWidget

monitorResizeWidget

ownerWidget

preventTooltipOnTouchWidget

readOnlyWidget

refWidget

rippleWidget

rootElementWidget

showTooltipWhenDisabledWidget

tabWidget

titlePanel

tooltipWidget

Record

autoUpdateRecordContainer

recordContainer

strictRecordMappingContainer

Scrolling

scrollableWidget

State

statefulState

statefulEventsState

stateIdState

stateProviderState

Properties

106

Class hierarchy

isCarousel: Boolean= truereadonly

Identifies an object as an instance of Carousel class, or subclass thereof.

isCarousel: Boolean= truereadonlystatic

Identifies an object as an instance of Carousel class, or subclass thereof.

isContainerContainer

isDelayableDelayable

isEventsEvents

isKeyMapKeyMap

isLocalizableLocalizable

isPanelPanel

isRTLRTL

isStateState

isToolableToolable

isWidgetWidget

Other

configureSlot: String | functionAlso a config

A callback function that must be provided by the developer to produce configuration objects for the slots in the carousel.

Derived classes may set this config to the name of the instance method to call. The this pointer will be the carousel instance.

Parameter	Type	Description
`index`	Number	The slot index as defined by the range of the carousel.
`carousel`	Carousel	The carousel instance.
`slot`	Widget	The slot being reconfigured or `null` when creating a new slot.

Returns: ContainerItemConfig -

The slot's configuration object.

currentIndex: NumberAlso a config

See goto.

emptyHtml: StringAlso a config

The HTML to render when the carousel's range is empty. To avoid XSS attacks, it is safer to use emptyText instead.

emptyText: String= No items to displayAlso a config

The text to render when the carousel's range is empty. This text is automatically encoded and is safe from XSS issues. To render markup when the carousel is empty, see emptyHtml.

range: Number[]Also a config

The range of slot indexes to be presented in the carousel. Slot indexes greater than or equal to range[0] and less than range[1] will be rendered.

If this value is null or [0, 0], the carousel will render no items (i.e., it will be empty). See emptyText.

By default, the carousel's range is unlimited, i.e., range = [-Infinity, Infinity].

reserveSlots: Number= 1Also a config

scrolling: Booleanreadonly

This will yield true when the carousel is currently scrolling.

scrollOnTab: Boolean= falseAlso a config

Set to true to use trapFocus to scroll the carousel when tabbing to slots that are not currently visible.

NOTE: This only works when configureSlot produces Panel instances.

shrinkWrap: Boolean | auto= autoAlso a config

By default (shrinkWrap = 'auto'), the carousel enables shrinkWrap support when the carousel's main element is position: absolute. This can be disabled by setting shrinkWrap = false.

slots: NumberAlso a config

When null, as many slots as needed to fill the carousel are created. This can produce partially visible slots.

snap: Boolean= trueAlso a config

Set to false to disable scroll snapping and allow free scrolling through the carousel.

vertical: Boolean= falseAlso a config

Set to true to enable vertical mode. By default, carousels scroll horizontally.

$namestaticWidget

catchEventHandlerExceptionsEvents

columnWidget

convertPinchToMousewheelstaticWidget

firstItemContainer

hasChangesContainer

inputFieldAlignContainer

isSettingValuesContainer

isStatefulState

isValidContainer

itemsContainer

labelPositionContainer

lastItemContainer

renditionContainer

rtlRTL

spanWidget

toolsPanel

typestaticWidget

valuesContainer

Accessibility

focusVisibleWidget

keyMapKeyMap

Content

bbarPanel

tbarPanel

CSS

clsWidget

DOM

appendToWidget

contentWidget

contentElementWidget

datasetWidget

elementWidget

focusableElementWidget

focusElementWidget

htmlWidget

idWidget

insertBeforeWidget

insertFirstWidget

overflowElementWidget

styleWidget

Float & align

anchorSizeWidget

maximizeOnMobileWidget

xWidget

yWidget

Layout

alignSelfWidget

collapsedPanel

collapsingPanel

expandingPanel

flexWidget

heightWidget

layoutContainer

layoutStyleContainer

marginWidget

maxHeightWidget

maxWidthWidget

minHeightWidget

minWidthWidget

scrollableWidget

widthWidget

Lifecycle

configBase

isConstructingBase

isDestroyedBase

isDestroyingBase

Misc

callOnFunctionsEvents

cellInfoWidget

disabledWidget

localeHelperLocalizable

localeManagerLocalizable

readOnlyWidget

refWidget

tabWidget

titlePanel

tooltipWidget

Record

recordContainer

strictRecordMappingContainer

ownerWidget

parentWidget

previousSiblingWidget

visibleChildCountContainer

widgetMapContainer

Functions

Other

backward

Step the carousel back one slot index.

Parameter	Type	Description
`animate`	Boolean	Pass `false` to disable smooth scrolling animation. Animations can only be disabled with this parameter, not enabled. For more details, see go

ensureVisible

Ensures that the given slot index is visible, scrolling if necessary to make it so.

Parameter	Type	Description
`options`	Object	Options to configure which slot should be visible and how to scroll if necessary.
`options.index`	Number	The index of the slot.
`options.animate`	Boolean	Pass `false` to disable scroll animation.

forward

Step the carousel forward one slot index. See go.

Parameter	Type	Description
`animate`	Boolean	Pass `false` to disable smooth scrolling animation. Animations can only be disabled with this parameter, not enabled. For more details, see go

Steps the slot index of the carousel forward or backward by the given increment.

Parameter	Type	Description
`increment`	Number	The number of slot indexes to advance forward (`> 0`) or backward (`< 0`).
`animate`	Boolean	Pass `false` to disable smooth scrolling animation. Animations can only be disabled with this parameter, not enabled. For more details, see goto

goto

Sets the slot index of the carousel to the given index.

Parameter	Type	Description
`index`	Number	The new slot index for the carousel.
`animate`	Boolean	Pass `false` to disable smooth scrolling animation. Animations can only be disabled with this parameter, not enabled. Animations are always disabled if animate is set to `false`. Further, if the slot index is changing by a large enough amount, animations will be also disabled. In other words, smooth scroll animation will be used as long as none of these conditions occur.