API Documentation

Slideshow ⇐ ElementBase

Slideshow with animated transitions.

By default the slideshow will immediately begin playing when it is connected to the document, advance every 3000 ms (3 seconds), and use a simple crossfade effect.

This component can be used on its own. To incorporate slideshow behavior into a component of your own, apply the TimerSelection mixin. To add slideshow functionality to a component such as a carousel, wrap it with the auxiliary basic-slideshow-timer component.

Kind: global class Extends: ElementBase
Mixes: ContentAsItems , DistributedChildrenAsContent , FractionalSelection , ItemsSelection , ObserveContentChanges , SelectionAnimation , SelectionAriaActive , TimerSelection

• Slideshow ⇐ ElementBase
  • .applySelection(item, selected)
  • .applySelection(item, selected)
  • .canSelectNext : boolean
  • .canSelectPrevious : boolean
  • .content : Array.<HTMLElement>
  • "content-changed"
  • .contentChanged()
  • .itemAdded(item)
  • .itemAdded(item)
  • .items : Array.<HTMLElement>
  • "items-changed"
  • .itemsChanged()
  • .pause()
  • .play()
  • .playing : boolean
  • "selected-index-changed"
  • "selected-item-changed"
  • .selectedFraction : number
  • .selectedFraction : number
  • .selectedIndex : number
  • .selectedItem : object
  • .selectFirst()
  • .selectionAnimationDuration : number
  • .selectionAnimationEffect : string
  • .selectionAnimationKeyframes : Array.<cssRules>
  • .selectionRequired : boolean
  • .selectionTimerDuration : number
  • .selectionWraps : boolean
  • .selectLast()
  • .selectNext()
  • .selectPrevious()
  • .showTransition : boolean

slideshow.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 Slideshow. Defined by ItemsSelection mixin.

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

slideshow.applySelection(item, selected)

Apply the selection state to a single item.

Invoke this method to signal that the selected state of the indicated item has changed. By default, this applies a selected CSS class if the item is selected, and removed it if not selected.

Kind: instance method of Slideshow. Defined by ContentAsItems mixin.

| Param | Type | Description | | --- | --- | --- | | item | HTMLElement | The item whose selection state has changed. | | selected | boolean | True if the item is selected, false if not. |

slideshow.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 Slideshow. Defined by ItemsSelection mixin.

slideshow.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 Slideshow. Defined by ItemsSelection mixin.

slideshow.content : Array.<HTMLElement>

The content of this component, defined to be the flattened array of children distributed to the component.

Kind: instance property of Slideshow. Defined by DistributedChildrenAsContent mixin.

"content-changed"

This event is raised when the component's contents (including distributed children) have changed.

Kind: event emitted by Slideshow. Defined by ObserveContentChanges mixin.

slideshow.contentChanged()

Invoked when the contents of the component (including distributed children) have changed.

This method is also invoked when a component is first instantiated; the contents have essentially "changed" from being nothing. This allows the component to perform initial processing of its children.

Kind: instance method of Slideshow. Defined by ObserveContentChanges mixin.

slideshow.itemAdded(item)

This method is invoked whenever a new item is added to the list.

The default implementation of this method does nothing. You can override this to perform per-item initialization.

Kind: instance method of Slideshow. Defined by ContentAsItems mixin.

| Param | Type | Description | | --- | --- | --- | | item | HTMLElement | The item that was added. |

slideshow.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 Slideshow. Defined by ItemsSelection mixin.

| Param | Type | Description | | --- | --- | --- | | item | HTMLElement | the item being added |

slideshow.items : Array.<HTMLElement>

The current set of items in the list. See the top-level documentation for mixin for a description of how items differ from plain content.

Kind: instance property of Slideshow. Defined by ContentAsItems mixin.

"items-changed"

Fires when the items in the list change.

Kind: event emitted by Slideshow. Defined by ContentAsItems mixin.

slideshow.itemsChanged()

This method is invoked when the underlying contents change. It is also invoked on component initialization – since the items have "changed" from being nothing.

Kind: instance method of Slideshow. Defined by ContentAsItems mixin.

slideshow.pause()

Pause automatic progression of the selection.

Kind: instance method of Slideshow. Defined by TimerSelection mixin.

slideshow.play()

Begin automatic progression of the selection.

Kind: instance method of Slideshow. Defined by TimerSelection mixin.

slideshow.playing : boolean

True if the selection is being automatically advanced.

Kind: instance property of Slideshow. Defined by TimerSelection mixin. Default: false

"selected-index-changed"

Fires when the selectedIndex property changes.

Kind: event emitted by Slideshow. Defined by ItemsSelection mixin.

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

"selected-item-changed"

Fires when the selectedItem property changes.

Kind: event emitted by Slideshow. Defined by ItemsSelection mixin.

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

slideshow.selectedFraction : number

A fractional value indicating how far the user has currently advanced to the next/previous item. E.g., a selectedFraction of 3.5 indicates the user is halfway between items 3 and 4.

Kind: instance property of Slideshow. Defined by FractionalSelection mixin.

slideshow.selectedFraction : number

A fractional value indicating how far the user has currently advanced to the next/previous item. E.g., a selectedFraction of 3.5 indicates the user is halfway between items 3 and 4.

For more details, see the FractionalSelection mixin.

Kind: instance property of Slideshow. Defined by SelectionAnimation mixin.

slideshow.selectedIndex : number

The index of the item which is currently selected.

If selectionWraps is false, the index is -1 if there is no selection. In that case, setting the index to -1 will deselect any currently-selected item.

Kind: instance property of Slideshow. Defined by ItemsSelection mixin.

slideshow.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 Slideshow. Defined by ItemsSelection mixin.

slideshow.selectFirst()

Select the first item in the list.

Kind: instance method of Slideshow. Defined by ItemsSelection mixin.

slideshow.selectionAnimationDuration : number

The duration of a selection animation in milliseconds.

This measures the amount of time required for a selection animation to complete. This number remains constant, even if the number of items being animated increases.

The default value is 250 milliseconds (a quarter a second).

Kind: instance property of Slideshow. Defined by SelectionAnimation mixin. Default: 250

slideshow.selectionAnimationEffect : string

The name of a standard selection animation effect.

This is a shorthand for setting the selectionAnimationKeyframes property to standard keyframes. Supported string values:

• "crossfade"

• "reveal"

• "revealWithFade"

• "showAdjacent"

• "slide"

• "slideWithGap"

  Kind: instance property of Slideshow. Defined by SelectionAnimation mixin. Default: "&quot;slide&quot;"
  

slideshow.selectionAnimationKeyframes : Array.<cssRules>

The keyframes that define an animation that plays for an item when moving forward in the sequence.

This is an array of CSS rules that will be applied. These are used as keyframes to animate the item with the Web Animations API.

The animation represents the state of the next item as it moves from completely unselected (offstage, usually right), to selected (center stage), to completely unselected (offstage, usually left). The center time of the animation should correspond to the item's quiscent selected state, typically in the center of the stage and at the item's largest size.

The default forward animation is a smooth slide at full size from right to left.

When moving the selection backward, this animation is played in reverse.

Kind: instance property of Slideshow. Defined by SelectionAnimation mixin.

slideshow.selectionRequired : boolean

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

Kind: instance property of Slideshow. Defined by ItemsSelection mixin. Default: false

slideshow.selectionTimerDuration : number

The time in milliseconds that will elapse after the selection changes before the selection will be advanced to the next item in the list.

Kind: instance property of Slideshow. Defined by TimerSelection mixin. Default: 1000 (1 second)

slideshow.selectionWraps : boolean

True if selection navigations wrap from last to first, and vice versa.

Kind: instance property of Slideshow. Defined by ItemsSelection mixin. Default: false

slideshow.selectLast()

Select the last item in the list.

Kind: instance method of Slideshow. Defined by ItemsSelection mixin.

slideshow.selectNext()

Select the next item in the list.

Kind: instance method of Slideshow. Defined by ItemsSelection mixin.

slideshow.selectPrevious()

Select the previous item in the list.

Kind: instance method of Slideshow. Defined by ItemsSelection mixin.

slideshow.showTransition : boolean

Determine whether a transition should be shown during selection.

Components like carousels often define animated CSS transitions for sliding effects. Such a transition should usually not be applied while the user is dragging, because a CSS animation will introduce a lag that makes the swipe feel sluggish. Instead, as long as the user is dragging with their finger down, the transition should be suppressed. When the user releases their finger, the transition can be restored, allowing the animation to show the carousel sliding into its final position.

Note: This property is only intended to let a component cooperate with mixins that may be applied to it, and is not intended to let someone using component permanently enable or disable transition effects.

Kind: instance property of Slideshow. Defined by SelectionAnimation mixin.