class sap.m.Carousel

Control sample: sap.m.Carousel
Visiblity: public
UX Guidelines: Carousel
Implements:
Available since: N/A
Module: sap/m/Carousel
Application Component: CA-UI5-CTR

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:

The paging indicator can be configured as follows: 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. Note: When the content is of type sap.m.Image add "Image" text at the end of the "alt" description in order to provide accessibility info for the UI element.

Usage

When to use

When not to use

Responsive Behavior


Constructor

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#constructor for a general description of the syntax of the settings object.

new sap.m.Carousel(sId?, mSettings?)
Param Type Default Value Description
sId? string

ID for the new control, generated automatically if no ID is given

mSettings? object

Initial settings for the new control


Properties

Name Type Default Value Description
arrowsPlacement sap.m.CarouselArrowsPlacement Content

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.

Visibility: public
height sap.ui.core.CSSSize 100%

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

Visibility: public
loop boolean false

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

Visibility: public
pageIndicatorPlacement sap.m.PlacementType Bottom

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.

Visibility: public
showBusyIndicator boolean true

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

Visibility: public
showPageIndicator boolean true

Show or hide carousel's page indicator.

Visibility: public
width sap.ui.core.CSSSize 100%

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

Visibility: public

Aggregations

Default Aggregation: pages

Name Cardinality Type Description
customLayout 0..1 sap.m.CarouselLayout

Defines how many pages are displayed in the visible area of the Carousel control.

Note: When this property is used, the loop property is ignored.

Since: 1.62.

pages (default) 0..n sap.ui.core.Control

The content which the carousel displays.


Associations

Name Cardinality Type Description
activePage 0..1 sap.ui.core.Control

Provides getter and setter for the currently displayed page. For the setter, argument may be the control itself, which must be member of the carousel's page list, or the control's id. The getter will return the control id


Events Overview

Event Description
beforePageChanged

This event is fired before 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.

loadPage

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

pageChanged

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.

unloadPage

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

beforePageChanged

This event is fired before 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.

Param Type Description
oControlEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object
activePages array

Indexes of all active pages after the page change.

Since: 1.63.

loadPage

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

Since 1.18.7 pages are no longer loaded or unloaded
Param Type Description
oControlEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object
pageId string

Id of the page which will be loaded

pageChanged

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.

Param Type Description
oControlEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object
oldActivePageId string

ID of the page which was active before the page change.

newActivePageId string

ID of the page which will be active after the page change.

activePages array

Indexes of all active pages after the page change.

Since: 1.62.

unloadPage

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

Since 1.18.7 pages are no longer loaded or unloaded
Param Type Description
oControlEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object
pageId string

Id of the page which will be unloaded


Methods Overview

Method Description
addPage

Adds some page to the aggregation pages.

attachBeforePageChanged

Attaches event handler fnFunction to the beforePageChanged 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 before 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.

attachLoadPage

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

Since 1.18.7 Since 1.18.7 pages are no longer loaded or unloaded
attachPageChanged

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.

attachUnloadPage

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.

Since 1.18.7 Since 1.18.7 pages are no longer loaded or unloaded
destroyCustomLayout

Destroys the customLayout in the aggregation customLayout.

destroyPages

Destroys all the pages in the aggregation pages.

detachBeforePageChanged

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

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

detachLoadPage

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.

Since 1.18.7 Since 1.18.7 pages are no longer loaded or unloaded
detachPageChanged

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.

detachUnloadPage

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.

Since 1.18.7 Since 1.18.7 pages are no longer loaded or unloaded
sap.m.Carousel.extend

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.

fireBeforePageChanged

Fires event beforePageChanged to attached listeners.

fireLoadPage

Fires event loadPage to attached listeners.

Since 1.18.7 Since 1.18.7 pages are no longer loaded or unloaded
firePageChanged

Fires event pageChanged to attached listeners.

fireUnloadPage

Fires event unloadPage to attached listeners.

Since 1.18.7 Since 1.18.7 pages are no longer loaded or unloaded
getActivePage

ID of the element which is the current target of the association activePage, or null.

getArrowsPlacement

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.

getCustomLayout

Gets content of aggregation customLayout.

Defines how many pages are displayed in the visible area of the Carousel control.

Note: When this property is used, the loop property is ignored.

getHeight

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%'.

getLoop

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.

sap.m.Carousel.getMetadata

Returns a metadata object for class sap.m.Carousel.

getPageIndicatorPlacement

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.

getPages

Gets content of aggregation pages.

The content which the carousel displays.

getShowBusyIndicator

Gets current value of property showBusyIndicator.

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

Default value is true.

Since 1.18.7 Since 1.18.7 pages are no longer loaded or unloaded. Therefore busy indicator is not necessary any longer.
getShowPageIndicator

Gets current value of property showPageIndicator.

Show or hide carousel's page indicator.

Default value is true.

getWidth

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%'.

indexOfPage

Checks for the provided sap.ui.core.Control in the aggregation pages. and returns its index if found or -1 otherwise.

insertPage

Inserts a page into the aggregation pages.

next

Call this method to display the next page (corresponds to a swipe right). Returns 'this' for method chaining.

previous

Call this method to display the previous page (corresponds to a swipe left). Returns 'this' for method chaining.

removeAllPages

Removes all the controls from the aggregation pages.

Additionally, it unregisters them from the hosting UIArea.

removePage

Removes a page from the aggregation pages.

setActivePage

Sets the associated activePage.

setArrowsPlacement

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.

setCustomLayout

Sets the aggregated customLayout.

setHeight

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%'.

setLoop

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.

setPageIndicatorPlacement

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.

setShowBusyIndicator

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.

Since 1.18.7 Since 1.18.7 pages are no longer loaded or unloaded. Therefore busy indicator is not necessary any longer.
setShowPageIndicator

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.

setWidth

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%'.

addPage

Adds some page to the aggregation pages.

Param Type DefaultValue Description
oPage sap.ui.core.Control

The page to add; if empty, nothing is inserted

attachBeforePageChanged

Attaches event handler fnFunction to the beforePageChanged 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 before 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.

Param Type DefaultValue Description
oData object

An application-specific payload object that will be passed to the event handler along with the event object when firing the event

fnFunction function(sap.ui.base.Event) : void

The function to be called when the event occurs

oListener object

Context object to call the event handler with. Defaults to this sap.m.Carousel itself

attachLoadPage

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

Since 1.18.7 Since 1.18.7 pages are no longer loaded or unloaded
Param Type DefaultValue Description
oData object

An application-specific payload object that will be passed to the event handler along with the event object when firing the event

fnFunction function(sap.ui.base.Event) : void

The function to be called when the event occurs

oListener object

Context object to call the event handler with. Defaults to this sap.m.Carousel itself

attachPageChanged

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.

Param Type DefaultValue Description
oData object

An application-specific payload object that will be passed to the event handler along with the event object when firing the event

fnFunction function(sap.ui.base.Event) : void

The function to be called when the event occurs

oListener object

Context object to call the event handler with. Defaults to this sap.m.Carousel itself

attachUnloadPage

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.

Since 1.18.7 Since 1.18.7 pages are no longer loaded or unloaded
Param Type DefaultValue Description
oData object

An application-specific payload object that will be passed to the event handler along with the event object when firing the event

fnFunction function(sap.ui.base.Event) : void

The function to be called when the event occurs

oListener object

Context object to call the event handler with. Defaults to this sap.m.Carousel itself

destroyCustomLayout

Destroys the customLayout in the aggregation customLayout.

destroyPages

Destroys all the pages in the aggregation pages.

detachBeforePageChanged

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

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

Param Type DefaultValue Description
fnFunction function(sap.ui.base.Event) : void

The function to be called, when the event occurs

oListener object

Context object on which the given function had to be called

detachLoadPage

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.

Since 1.18.7 Since 1.18.7 pages are no longer loaded or unloaded
Param Type DefaultValue Description
fnFunction function(sap.ui.base.Event) : void

The function to be called, when the event occurs

oListener object

Context object on which the given function had to be called

detachPageChanged

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.

Param Type DefaultValue Description
fnFunction function(sap.ui.base.Event) : void

The function to be called, when the event occurs

oListener object

Context object on which the given function had to be called

detachUnloadPage

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.

Since 1.18.7 Since 1.18.7 pages are no longer loaded or unloaded
Param Type DefaultValue Description
fnFunction function(sap.ui.base.Event) : void

The function to be called, when the event occurs

oListener object

Context object on which the given function had to be called

sap.m.Carousel.extend

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.

Param Type DefaultValue Description
sClassName string

Name of the class being created

oClassInfo object

Object literal with information about the class

FNMetaImpl function

Constructor function for the metadata object; if not given, it defaults to the metadata implementation used by this class

fireBeforePageChanged

Fires event beforePageChanged to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

activePages array

Indexes of all active pages after the page change.

fireLoadPage

Fires event loadPage to attached listeners.

Since 1.18.7 Since 1.18.7 pages are no longer loaded or unloaded
Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

pageId string

Id of the page which will be loaded

firePageChanged

Fires event pageChanged to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

oldActivePageId string

ID of the page which was active before the page change.

newActivePageId string

ID of the page which will be active after the page change.

activePages array

Indexes of all active pages after the page change.

fireUnloadPage

Fires event unloadPage to attached listeners.

Since 1.18.7 Since 1.18.7 pages are no longer loaded or unloaded
Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

pageId string

Id of the page which will be unloaded

getActivePage

ID of the element which is the current target of the association activePage, or null.

getArrowsPlacement

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.

getCustomLayout

Gets content of aggregation customLayout.

Defines how many pages are displayed in the visible area of the Carousel control.

Note: When this property is used, the loop property is ignored.

getHeight

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%'.

getLoop

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.

sap.m.Carousel.getMetadata

Returns a metadata object for class sap.m.Carousel.

getPageIndicatorPlacement

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.

getPages

Gets content of aggregation pages.

The content which the carousel displays.

getShowBusyIndicator

Gets current value of property showBusyIndicator.

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

Default value is true.

Since 1.18.7 Since 1.18.7 pages are no longer loaded or unloaded. Therefore busy indicator is not necessary any longer.

getShowPageIndicator

Gets current value of property showPageIndicator.

Show or hide carousel's page indicator.

Default value is true.

getWidth

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%'.

indexOfPage

Checks for the provided sap.ui.core.Control in the aggregation pages. and returns its index if found or -1 otherwise.

Param Type DefaultValue Description
oPage sap.ui.core.Control

The page whose index is looked for

insertPage

Inserts a page into the aggregation pages.

Param Type DefaultValue Description
oPage sap.ui.core.Control

The page to insert; if empty, nothing is inserted

iIndex int

The 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

next

Call this method to display the next page (corresponds to a swipe right). Returns 'this' for method chaining.

previous

Call this method to display the previous page (corresponds to a swipe left). Returns 'this' for method chaining.

removeAllPages

Removes all the controls from the aggregation pages.

Additionally, it unregisters them from the hosting UIArea.

removePage

Removes a page from the aggregation pages.

Param Type DefaultValue Description
vPage int string sap.ui.core.Control

The page to remove or its index or id

setActivePage

Sets the associated activePage.

Param Type DefaultValue Description
oActivePage sap.ui.core.ID sap.ui.core.Control

ID of an element which becomes the new target of this activePage association; alternatively, an element instance may be given

setArrowsPlacement

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.

Param Type DefaultValue Description
sArrowsPlacement sap.m.CarouselArrowsPlacement Content

New value for property arrowsPlacement

setCustomLayout

Sets the aggregated customLayout.

Param Type DefaultValue Description
oCustomLayout sap.m.CarouselLayout

The customLayout to set

setHeight

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%'.

Param Type DefaultValue Description
sHeight sap.ui.core.CSSSize '100%'

New value for property height

setLoop

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.

Param Type DefaultValue Description
bLoop boolean false

New value for property loop

setPageIndicatorPlacement

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.

Param Type DefaultValue Description
sPageIndicatorPlacement sap.m.PlacementType Bottom

New value for property pageIndicatorPlacement

setShowBusyIndicator

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.

Since 1.18.7 Since 1.18.7 pages are no longer loaded or unloaded. Therefore busy indicator is not necessary any longer.
Param Type DefaultValue Description
bShowBusyIndicator boolean true

New value for property showBusyIndicator

setShowPageIndicator

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.

Param Type DefaultValue Description
bShowPageIndicator boolean true

New value for property showPageIndicator

setWidth

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%'.

Param Type DefaultValue Description
sWidth sap.ui.core.CSSSize '100%'

New value for property width