Class sap.m.CarouselModule: sap/m/Carousel

extends Control

The carousel allows the user to browse through a set of items by swiping right or left.

Overview

The control is mostly used for showing a gallery of images, but can hold any sap.m control.

Structure

The carousel consists of a the following elements:

  • Content area - displays the different items.
  • Navigation - arrows to the left and right for switching between items.
  • (optional) Paging - indicator at the bottom to show the current position in the set.

The paging indicator can be configured as follows:

  • showPageIndicator - determines if the indicator is displayed.
  • If the pages are less than 9, the page indicator is represented with bullets.
  • If the pages are 9 or more, the page indicator is numeric.
  • pageIndicatorPlacement - determines where the indicator is located. Default (sap.m.PlacementType.Bottom) - below the content.

Additionally, you can also change the location of the navigation arrows. By setting arrowsPlacement to sap.m.CarouselArrowsPlacement.PageIndicator, the arrows will be located at the bottom by the paging indicator.

Usage

When to use

  • The items you want to display are very different from each other.
  • You want to display the items one after the other.

When not to use

  • The items you want to display need to be visible at the same time.
  • The items you want to display are uniform and very similar

Responsive Behavior

  • On touch devices, navigation is performed with swipe gestures (swipe right or swipe left).
  • On desktop, navigation is done with the navigation arrows.
  • The paging indicator (when activated) is visible on each form factor.
Constructor Summary
new sap.m.Carousel(sId?, mSettings?)Constructor for a new Carousel.
Event Summary
pageChanged(oControlEvent)This event is fired after a carousel swipe has been completed.
loadPage(oControlEvent)Carousel requires a new page to be loaded.
unloadPage(oControlEvent)Carousel does not display a page any longer and unloads it.
Events borrowed from class sap.ui.core.Control
Method Summary
sap.m.Carousel.extend(sClassName, oClassInfo?, FNMetaImpl?)Creates a new subclass of class sap.m.Carousel with name sClassName and enriches it with the information contained in oClassInfo.
sap.m.Carousel.getMetadata()Returns a metadata object for class sap.m.Carousel.
addPage(oPage)Adds some page to the aggregation pages.
attachPageChanged(oData?, fnFunction, oListener?)Attaches event handler fnFunction to the pageChanged event of this sap.m.Carousel.
destroyPages()Destroys all the pages in the aggregation pages.
detachPageChanged(fnFunction, oListener)Detaches event handler fnFunction from the pageChanged event of this sap.m.Carousel.
firePageChanged(mParameters?)Fires event pageChanged to attached listeners.
getActivePage()ID of the element which is the current target of the association activePage, or null.
getArrowsPlacement()Gets current value of property arrowsPlacement.
getHeight()Gets current value of property height.
getLoop()Gets current value of property loop.
getPageIndicatorPlacement()Gets current value of property pageIndicatorPlacement.
getPages()Gets content of aggregation pages.
getShowPageIndicator()Gets current value of property showPageIndicator.
getWidth()Gets current value of property width.
indexOfPage(oPage)Checks for the provided sap.ui.core.Control in the aggregation pages.
insertPage(oPage, iIndex)Inserts a page into the aggregation pages.
next()Call this method to display the next page (corresponds to a swipe right).
previous()Call this method to display the previous page (corresponds to a swipe left).
removeAllPages()Removes all the controls from the aggregation pages.
removePage(vPage)Removes a page from the aggregation pages.
setActivePage(oActivePage)Sets the associated activePage.
setArrowsPlacement(sArrowsPlacement)Sets a new value for property arrowsPlacement.
setHeight(sHeight)Sets a new value for property height.
setLoop(bLoop)Sets a new value for property loop.
setPageIndicatorPlacement(sPageIndicatorPlacement)Sets a new value for property pageIndicatorPlacement.
setShowPageIndicator(bShowPageIndicator)Sets a new value for property showPageIndicator.
setWidth(sWidth)Sets a new value for property width.
attachLoadPage(oData?, fnFunction, oListener?)Attaches event handler fnFunction to the loadPage event of this sap.m.Carousel.
attachUnloadPage(oData?, fnFunction, oListener?)Attaches event handler fnFunction to the unloadPage event of this sap.m.Carousel.
detachLoadPage(fnFunction, oListener)Detaches event handler fnFunction from the loadPage event of this sap.m.Carousel.
detachUnloadPage(fnFunction, oListener)Detaches event handler fnFunction from the unloadPage event of this sap.m.Carousel.
fireLoadPage(mParameters?)Fires event loadPage to attached listeners.
fireUnloadPage(mParameters?)Fires event unloadPage to attached listeners.
getBusyIndicatorSize()Gets current value of property busyIndicatorSize.
getShowBusyIndicator()Gets current value of property showBusyIndicator.
setBusyIndicatorSize(sBusyIndicatorSize)Sets a new value for property busyIndicatorSize.
setShowBusyIndicator(bShowBusyIndicator)Sets a new value for property showBusyIndicator.
Constructor Detail
new sap.m.Carousel(sId?, mSettings?)

Constructor for a new Carousel.

Accepts an object literal mSettings that defines initial property values, aggregated and associated objects as well as event handlers. See sap.ui.base.ManagedObject for a general description of the syntax of the settings object.

The supported settings are:

  • Properties

  • Aggregations

    • pages : sap.ui.core.Control[] (default)

  • Associations

    • activePage : (sap.ui.core.ID | sap.ui.core.Control)

  • Events

    • loadPage : fnListenerFunction or [fnListenerFunction, oListenerObject] or [oData, fnListenerFunction, oListenerObject]
    • unloadPage : fnListenerFunction or [fnListenerFunction, oListenerObject] or [oData, fnListenerFunction, oListenerObject]
    • pageChanged : fnListenerFunction or [fnListenerFunction, oListenerObject] or [oData, fnListenerFunction, oListenerObject]

In addition, all settings applicable to the base type sap.ui.core.Control can be used as well.

Parameters:
stringsId?ID for the new control, generated automatically if no ID is given
objectmSettings?Initial settings for the new control
Event Detail
pageChanged(oControlEvent)
This event is fired after a carousel swipe has been completed. It is triggered both by physical swipe events and through API carousel manipulations such as calling 'next', 'previous' or 'setActivePageId' functions.
Parameters:
sap.ui.base.EventoControlEvent
sap.ui.base.EventProvideroControlEvent.getSource
objectoControlEvent.getParameters
stringoControlEvent.getParameters.oldActivePageIdId of the page which was active before the page change.
stringoControlEvent.getParameters.newActivePageIdId of the page which is active after the page change.
loadPage(oControlEvent)
Carousel requires a new page to be loaded. This event may be used to fill the content of that page
Parameters:
sap.ui.base.EventoControlEvent
sap.ui.base.EventProvideroControlEvent.getSource
objectoControlEvent.getParameters
stringoControlEvent.getParameters.pageIdId of the page which will be loaded
Deprecated API:
Since version 1.18.7. Since 1.18.7 pages are no longer loaded or unloaded
unloadPage(oControlEvent)
Carousel does not display a page any longer and unloads it. This event may be used to clean up the content of that page.
Parameters:
sap.ui.base.EventoControlEvent
sap.ui.base.EventProvideroControlEvent.getSource
objectoControlEvent.getParameters
stringoControlEvent.getParameters.pageIdId of the page which will be unloaded
Deprecated API:
Since version 1.18.7. Since 1.18.7 pages are no longer loaded or unloaded
Method Detail
sap.m.Carousel.extend(sClassName, oClassInfo?, FNMetaImpl?): function

Creates a new subclass of class sap.m.Carousel with name sClassName and enriches it with the information contained in oClassInfo.

oClassInfo might contain the same kind of information as described in sap.ui.core.Control.extend.

Parameters:
stringsClassNameName of the class being created
objectoClassInfo?Object literal with information about the class
functionFNMetaImpl?Constructor function for the metadata object; if not given, it defaults to sap.ui.core.ElementMetadata
Returns:
functionCreated class / constructor function
sap.m.Carousel.getMetadata(): sap.ui.base.Metadata
Returns a metadata object for class sap.m.Carousel.
Returns:
sap.ui.base.MetadataMetadata object describing this class
addPage(oPage): sap.m.Carousel
Adds some page to the aggregation pages.
Parameters:
sap.ui.core.ControloPagethe page to add; if empty, nothing is inserted
Returns:
sap.m.CarouselReference to this in order to allow method chaining
attachPageChanged(oData?, fnFunction, oListener?): sap.m.Carousel

Attaches event handler fnFunction to the pageChanged event of this sap.m.Carousel.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.m.Carousel itself.

This event is fired after a carousel swipe has been completed. It is triggered both by physical swipe events and through API carousel manipulations such as calling 'next', 'previous' or 'setActivePageId' functions.

Parameters:
objectoData?An application-specific payload object that will be passed to the event handler along with the event object when firing the event
functionfnFunctionThe function to be called when the event occurs
objectoListener?Context object to call the event handler with. Defaults to this sap.m.Carousel itself
Returns:
sap.m.CarouselReference to this in order to allow method chaining
destroyPages(): sap.m.Carousel
Destroys all the pages in the aggregation pages.
Returns:
sap.m.CarouselReference to this in order to allow method chaining
detachPageChanged(fnFunction, oListener): sap.m.Carousel

Detaches event handler fnFunction from the pageChanged event of this sap.m.Carousel.

The passed function and listener object must match the ones used for event registration.

Parameters:
functionfnFunctionThe function to be called, when the event occurs
objectoListenerContext object on which the given function had to be called
Returns:
sap.m.CarouselReference to this in order to allow method chaining
firePageChanged(mParameters?): sap.m.Carousel
Fires event pageChanged to attached listeners.
Parameters:
objectmParameters?Parameters to pass along with the event
stringmParameters.oldActivePageId?Id of the page which was active before the page change.
stringmParameters.newActivePageId?Id of the page which is active after the page change.
Returns:
sap.m.CarouselReference to this in order to allow method chaining
getActivePage(): sap.ui.core.ID
ID of the element which is the current target of the association activePage, or null.
Returns:
sap.ui.core.ID
getArrowsPlacement(): sap.m.CarouselArrowsPlacement

Gets current value of property arrowsPlacement.

Defines where the carousel's arrows are placed. Default is sap.m.CarouselArrowsPlacement.Content used to place the arrows on the sides of the carousel. Alternatively sap.m.CarouselArrowsPlacement.PageIndicator can be used to place the arrows on the sides of the page indicator.

Default value is Content.

Returns:
sap.m.CarouselArrowsPlacementValue of property arrowsPlacement
getHeight(): sap.ui.core.CSSSize

Gets current value of property height.

The height of the carousel. Note that when a percentage value is used, the height of the surrounding container must be defined.

Default value is 100%.

Returns:
sap.ui.core.CSSSizeValue of property height
getLoop(): boolean

Gets current value of property loop.

Defines whether the carousel should loop, i.e show the first page after the last page is reached and vice versa.

Default value is false.

Returns:
booleanValue of property loop
getPageIndicatorPlacement(): sap.m.PlacementType

Gets current value of property pageIndicatorPlacement.

Defines where the carousel's page indicator is displayed. Possible values are sap.m.PlacementType.Top, sap.m.PlacementType.Bottom. Other values are ignored and the default value will be applied. The default value is sap.m.PlacementType.Bottom.

Default value is Bottom.

Returns:
sap.m.PlacementTypeValue of property pageIndicatorPlacement
getPages(): sap.ui.core.Control[]

Gets content of aggregation pages.

The content which the carousel displays.

Returns:
sap.ui.core.Control[]
getShowPageIndicator(): boolean

Gets current value of property showPageIndicator.

Show or hide carousel's page indicator.

Default value is true.

Returns:
booleanValue of property showPageIndicator
getWidth(): sap.ui.core.CSSSize

Gets current value of property width.

The width of the carousel. Note that when a percentage value is used, the height of the surrounding container must be defined.

Default value is 100%.

Returns:
sap.ui.core.CSSSizeValue of property width
indexOfPage(oPage): int
Checks for the provided sap.ui.core.Control in the aggregation pages. and returns its index if found or -1 otherwise.
Parameters:
sap.ui.core.ControloPageThe page whose index is looked for
Returns:
intThe index of the provided control in the aggregation if found, or -1 otherwise
insertPage(oPage, iIndex): sap.m.Carousel
Inserts a page into the aggregation pages.
Parameters:
sap.ui.core.ControloPagethe page to insert; if empty, nothing is inserted
intiIndexthe 0-based index the page should be inserted at; for a negative value of iIndex, the page is inserted at position 0; for a value greater than the current size of the aggregation, the page is inserted at the last position
Returns:
sap.m.CarouselReference to this in order to allow method chaining
removeAllPages(): sap.ui.core.Control[]

Removes all the controls from the aggregation pages.

Additionally, it unregisters them from the hosting UIArea.

Returns:
sap.ui.core.Control[]An array of the removed elements (might be empty)
removePage(vPage): sap.ui.core.Control
Removes a page from the aggregation pages.
Parameters:
int|string|sap.ui.core.ControlvPageThe page to remove or its index or id
Returns:
sap.ui.core.ControlThe removed page or null
setActivePage(oActivePage): sap.m.Carousel
Sets the associated activePage.
Parameters:
sap.ui.core.ID|sap.ui.core.ControloActivePageID of an element which becomes the new target of this activePage association; alternatively, an element instance may be given
Returns:
sap.m.CarouselReference to this in order to allow method chaining
setArrowsPlacement(sArrowsPlacement): sap.m.Carousel

Sets a new value for property arrowsPlacement.

Defines where the carousel's arrows are placed. Default is sap.m.CarouselArrowsPlacement.Content used to place the arrows on the sides of the carousel. Alternatively sap.m.CarouselArrowsPlacement.PageIndicator can be used to place the arrows on the sides of the page indicator.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is Content.

Parameters:
sap.m.CarouselArrowsPlacementsArrowsPlacementNew value for property arrowsPlacement
Returns:
sap.m.CarouselReference to this in order to allow method chaining
setHeight(sHeight): sap.m.Carousel

Sets a new value for property height.

The height of the carousel. Note that when a percentage value is used, the height of the surrounding container must be defined.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is 100%.

Parameters:
sap.ui.core.CSSSizesHeightNew value for property height
Returns:
sap.m.CarouselReference to this in order to allow method chaining
setLoop(bLoop): sap.m.Carousel

Sets a new value for property loop.

Defines whether the carousel should loop, i.e show the first page after the last page is reached and vice versa.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is false.

Parameters:
booleanbLoopNew value for property loop
Returns:
sap.m.CarouselReference to this in order to allow method chaining
setPageIndicatorPlacement(sPageIndicatorPlacement): sap.m.Carousel

Sets a new value for property pageIndicatorPlacement.

Defines where the carousel's page indicator is displayed. Possible values are sap.m.PlacementType.Top, sap.m.PlacementType.Bottom. Other values are ignored and the default value will be applied. The default value is sap.m.PlacementType.Bottom.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is Bottom.

Parameters:
sap.m.PlacementTypesPageIndicatorPlacementNew value for property pageIndicatorPlacement
Returns:
sap.m.CarouselReference to this in order to allow method chaining
setShowPageIndicator(bShowPageIndicator): sap.m.Carousel

Sets a new value for property showPageIndicator.

Show or hide carousel's page indicator.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is true.

Parameters:
booleanbShowPageIndicatorNew value for property showPageIndicator
Returns:
sap.m.CarouselReference to this in order to allow method chaining
setWidth(sWidth): sap.m.Carousel

Sets a new value for property width.

The width of the carousel. Note that when a percentage value is used, the height of the surrounding container must be defined.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is 100%.

Parameters:
sap.ui.core.CSSSizesWidthNew value for property width
Returns:
sap.m.CarouselReference to this in order to allow method chaining
attachLoadPage(oData?, fnFunction, oListener?): sap.m.Carousel

Attaches event handler fnFunction to the loadPage event of this sap.m.Carousel.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.m.Carousel itself.

Carousel requires a new page to be loaded. This event may be used to fill the content of that page

Parameters:
objectoData?An application-specific payload object that will be passed to the event handler along with the event object when firing the event
functionfnFunctionThe function to be called when the event occurs
objectoListener?Context object to call the event handler with. Defaults to this sap.m.Carousel itself
Returns:
sap.m.CarouselReference to this in order to allow method chaining
Deprecated API:
Since version 1.18.7. Since 1.18.7 pages are no longer loaded or unloaded
attachUnloadPage(oData?, fnFunction, oListener?): sap.m.Carousel

Attaches event handler fnFunction to the unloadPage event of this sap.m.Carousel.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.m.Carousel itself.

Carousel does not display a page any longer and unloads it. This event may be used to clean up the content of that page.

Parameters:
objectoData?An application-specific payload object that will be passed to the event handler along with the event object when firing the event
functionfnFunctionThe function to be called when the event occurs
objectoListener?Context object to call the event handler with. Defaults to this sap.m.Carousel itself
Returns:
sap.m.CarouselReference to this in order to allow method chaining
Deprecated API:
Since version 1.18.7. Since 1.18.7 pages are no longer loaded or unloaded
detachLoadPage(fnFunction, oListener): sap.m.Carousel

Detaches event handler fnFunction from the loadPage event of this sap.m.Carousel.

The passed function and listener object must match the ones used for event registration.

Parameters:
functionfnFunctionThe function to be called, when the event occurs
objectoListenerContext object on which the given function had to be called
Returns:
sap.m.CarouselReference to this in order to allow method chaining
Deprecated API:
Since version 1.18.7. Since 1.18.7 pages are no longer loaded or unloaded
detachUnloadPage(fnFunction, oListener): sap.m.Carousel

Detaches event handler fnFunction from the unloadPage event of this sap.m.Carousel.

The passed function and listener object must match the ones used for event registration.

Parameters:
functionfnFunctionThe function to be called, when the event occurs
objectoListenerContext object on which the given function had to be called
Returns:
sap.m.CarouselReference to this in order to allow method chaining
Deprecated API:
Since version 1.18.7. Since 1.18.7 pages are no longer loaded or unloaded
fireLoadPage(mParameters?): sap.m.Carousel
Fires event loadPage to attached listeners.
Parameters:
objectmParameters?Parameters to pass along with the event
stringmParameters.pageId?Id of the page which will be loaded
Returns:
sap.m.CarouselReference to this in order to allow method chaining
Deprecated API:
Since version 1.18.7. Since 1.18.7 pages are no longer loaded or unloaded
fireUnloadPage(mParameters?): sap.m.Carousel
Fires event unloadPage to attached listeners.
Parameters:
objectmParameters?Parameters to pass along with the event
stringmParameters.pageId?Id of the page which will be unloaded
Returns:
sap.m.CarouselReference to this in order to allow method chaining
Deprecated API:
Since version 1.18.7. Since 1.18.7 pages are no longer loaded or unloaded
getBusyIndicatorSize(): sap.ui.core.CSSSize

Gets current value of property busyIndicatorSize.

Size of the busy indicators which can be displayed in the carousel.

Default value is 6em.

Returns:
sap.ui.core.CSSSizeValue of property busyIndicatorSize
Deprecated API:
Since version 1.18.7. Since 1.18.7 pages are no longer loaded or unloaded. Therefore busy indicator is not necessary any longer.
getShowBusyIndicator(): boolean

Gets current value of property showBusyIndicator.

Show or hide busy indicator in the carousel when loading pages after swipe.

Default value is true.

Returns:
booleanValue of property showBusyIndicator
Deprecated API:
Since version 1.18.7. Since 1.18.7 pages are no longer loaded or unloaded. Therefore busy indicator is not necessary any longer.
setBusyIndicatorSize(sBusyIndicatorSize): sap.m.Carousel

Sets a new value for property busyIndicatorSize.

Size of the busy indicators which can be displayed in the carousel.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is 6em.

Parameters:
sap.ui.core.CSSSizesBusyIndicatorSizeNew value for property busyIndicatorSize
Returns:
sap.m.CarouselReference to this in order to allow method chaining
Deprecated API:
Since version 1.18.7. Since 1.18.7 pages are no longer loaded or unloaded. Therefore busy indicator is not necessary any longer.
setShowBusyIndicator(bShowBusyIndicator): sap.m.Carousel

Sets a new value for property showBusyIndicator.

Show or hide busy indicator in the carousel when loading pages after swipe.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is true.

Parameters:
booleanbShowBusyIndicatorNew value for property showBusyIndicator
Returns:
sap.m.CarouselReference to this in order to allow method chaining
Deprecated API:
Since version 1.18.7. Since 1.18.7 pages are no longer loaded or unloaded. Therefore busy indicator is not necessary any longer.