The carousel allows the user to browse through a set of items by swiping right or left.
The control is mostly used for showing a gallery of images, but can hold any sap.m control.
The carousel consists of a the following elements:
showPageIndicator
- determines if the indicator is displayed.pageIndicatorPlacement
- determines where the indicator is located. Default (sap.m.PlacementType.Bottom
) - below the content.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.
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 |
Name | Type | Default Value | Description |
---|---|---|---|
arrowsPlacement | sap.m.CarouselArrowsPlacement | Content | Defines where the carousel's arrows are placed. Default is |
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 |
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 Note: When this property is used, the |
pages (default) | 0..n | sap.ui.core.Control |
The content which the carousel displays. |
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 |
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. |
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. |
Carousel requires a new page to be loaded. This event may be used to fill the content of that page
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 |
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. |
Carousel does not display a page any longer and unloads it. This event may be used to clean up the content of that page.
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 |
Method | Description |
---|---|
addPage |
Adds some page to the aggregation pages. |
attachBeforePageChanged |
Attaches event handler When called, the context of the event handler (its 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 When called, the context of the event handler (its 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 When called, the context of the event handler (its 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 When called, the context of the event handler (its 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 The passed function and listener object must match the ones used for event registration. |
detachLoadPage |
Detaches event handler 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 The passed function and listener object must match the ones used for event registration. |
detachUnloadPage |
Detaches event handler 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
|
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 |
getArrowsPlacement |
Gets current value of property arrowsPlacement. Defines where the carousel's arrows are placed. Default is Default value is |
getCustomLayout |
Gets content of aggregation customLayout. Defines how many pages are displayed in the visible area of the Note: When this property is used, the |
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 |
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 |
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 |
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
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 |
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 |
indexOfPage |
Checks for the provided |
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 When called with a value of Default value is |
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 Default value is |
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 Default value is |
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 Default value is |
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 Default value is
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 Default value is |
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 Default value is |
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 |
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 |
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
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 |
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 |
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.
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 |
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 |
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.
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 |
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 |
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.
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 |
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 |
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. |
Fires event loadPage to attached listeners.
Param | Type | DefaultValue | Description |
---|---|---|---|
mParameters | object |
Parameters to pass along with the event |
|
pageId | string |
Id of the page which will be loaded |
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. |
Fires event unloadPage to attached listeners.
Param | Type | DefaultValue | Description |
---|---|---|---|
mParameters | object |
Parameters to pass along with the event |
|
pageId | string |
Id of the page which will be unloaded |
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
.
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.
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%'
.
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
.
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
.
Gets current value of property showBusyIndicator.
Show or hide busy indicator in the carousel when loading pages after swipe.
Default value is true
.
Gets current value of property showPageIndicator.
Show or hide carousel's page indicator.
Default value is true
.
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%'
.
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 |
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 |
Call this method to display the next page (corresponds to a swipe right). Returns 'this' for method chaining.
Call this method to display the previous page (corresponds to a swipe left). Returns 'this' for method chaining.
Removes all the controls from the aggregation pages.
Additionally, it unregisters them from the hosting UIArea.
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 |
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 |
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 |
Sets the aggregated customLayout.
Param | Type | DefaultValue | Description |
---|---|---|---|
oCustomLayout | sap.m.CarouselLayout |
The customLayout to set |
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 |
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 |
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 |
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
.
Param | Type | DefaultValue | Description |
---|---|---|---|
bShowBusyIndicator | boolean | true |
New value for property |
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 |
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 |