Carousel¶

Overview¶

A carousel UI component.

A set of N items is divided into M 'pages', based on how many items are visible in the carousel. Pressing the next and previous buttons moves through the pages. Movement through the pages is animated, so that items appear to scroll by.

Note that Carousel wraps each item (Node) in an alignBox to ensure all items have an equal "footprint" dimension.

The Carousel handles dynamic layout as far as carousel items changing sizes - it will resize to fit all of the items. If you want to align or stretch item content, that can be done with CarouselItem's alignBoxOptions (align:stretch will cause the item to be expanded to its section in the Carousel).

Carousel currently is not sizable on its own (you can't set a preferred width/height that causes it to expand).

@author Chris Malley (PixelZoom, Inc.) @author Sam Reid (PhET Interactive Simulations)

Class Carousel¶

import { Carousel } from 'scenerystack/sun';

Constructor¶

new Carousel( items : CarouselItem[], providedOptions? : CarouselOptions )¶

Instance Methods¶

dispose()¶

NOTE: This will dispose the item Nodes

reset( animationEnabled )¶

Resets the carousel to its initial state. @param animationEnabled - whether to enable animation during reset

scrollToItem( item : CarouselItem )¶

Given an item, scrolls the carousel to the page that contains that item. This will only scroll if item is in the Carousel and visible.

scrollToAlignBox( alignBox : AlignBox )¶

Public for ScrollingFlowBox only

setItemVisible( item : CarouselItem, visible : boolean )¶

Set the visibility of an item in the Carousel. This toggles visibility and will reflow the layout, such that hidden items do not leave a gap in the layout.

getNodeForItem( item : CarouselItem ) : Node¶

Returns the Node that was created for a given item.

getVisibleAlignBoxes() : AlignBox[]¶

The order of alignBoxes might be tweaked in scrollingNode's children. We need to respect this order

Instance Properties¶

carouselItemNodes : Node[]¶

(readonly)

created from createNode() in CarouselItem

numberOfPagesProperty : ReadOnlyProperty<number>¶

(readonly)

number of pages in the carousel

pageNumberProperty : Property<number>¶

(readonly)

page number that is currently visible

animationEnabled : boolean¶

enables animation when scrolling between pages

backgroundWidth : number¶

These are public for layout - NOTE: These are mutated if the size changes after construction

backgroundHeight : number¶

isAnimatingProperty : BooleanProperty¶

(readonly)

Type CarouselItem¶

import type { CarouselItem } from 'scenerystack/sun';

GroupItemOptions & { alignBoxOptions?: AlignBoxOptions }

Type CarouselOptions¶

import type { CarouselOptions } from 'scenerystack/sun';

• orientation?: LayoutOrientation
  container
• fill?: TPaint
• stroke?: TPaint
• lineWidth?: number
• cornerRadius?: number
• defaultPageNumber?: number
• itemsPerPage?: number
  items
• spacing?: number
• margin?: number
• alignBoxOptions?: AlignBoxOptions
  options for the AlignBoxes (particularly if alignment of items should be changed, or if specific margins are desired)
• buttonOptions?: CarouselButtonOptions
  next/previous button options
• separatorsVisible?: boolean
  item separator options
• separatorOptions?: SeparatorOptions
• animationEnabled?: boolean
  animation, scrolling between pages
• animationOptions?: StrictOmit<AnimationOptions<number>, "to" | "setValue" | "getValue">
• & StrictOmit<NodeOptions, "children">

Source Code¶

See the source for Carousel.ts in the sun repository.