The Carousel control can be used to navigate through a list of sap.m controls just like flipping through the pages of a book by swiping right or left. An indicator shows the current position within the control list. When displayed in a desktop browser, a left- and right-arrow button is displayed on the carousel's sides, which can be used to navigate through the carousel.
Note: when displa Internet Explorer 9, page changes are not animated.
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. 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. 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. getActivePage()ID of the element which is the current target of the association activePage, or null. getHeight()Gets current value of property height. getLoop()Gets current value of property loop. getPages()Gets content of aggregation pages. 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). removePage(vPage)Removes a page from the aggregation pages. setHeight(sHeight)Sets a new value for property height. setLoop(bLoop)Sets a new value for property loop. 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(mArguments?)Fires event loadPage to attached listeners. fireUnloadPage(mArguments?)Fires event unloadPage to attached listeners. addStyleClass,
allowTextSelection,
attachBrowserEvent,
attachValidateFieldGroup,
checkFieldGroupIds,
clone,
detachBrowserEvent,
detachValidateFieldGroup,
fireValidateFieldGroup,
getAccessibilityInfo,
getBusy,
getBusyIndicatorDelay,
getControlsByFieldGroupId,
getFieldGroupIds,
getIdForLabel,
getRenderer,
getVisible,
hasStyleClass,
invalidate,
isBusy,
placeAt,
removeStyleClass,
rerender,
setBusy,
setBusyIndicatorDelay,
setFieldGroupIds,
setVisible,
toggleStyleClass,
triggerValidateFieldGroup $,
addCustomData,
addDependent,
addEventDelegate,
applyFocusInfo,
bindElement,
data,
destroy,
destroyCustomData,
destroyDependents,
destroyLayoutData,
destroyTooltip,
enhanceAccessibilityState,
findElements,
fireEvent,
focus,
getCustomData,
getDependents,
getDomRef,
getElementBinding,
getFocusDomRef,
getFocusInfo,
getInterface,
getLayoutData,
getMetadata,
getTooltip,
getTooltip_AsString,
getTooltip_Text,
indexOfCustomData,
indexOfDependent,
insertCustomData,
insertDependent,
prop,
removeAllCustomData,
removeAllDependents,
removeCustomData,
removeDependent,
removeEventDelegate,
setLayoutData,
setTooltip,
toString,
unbindElement addAggregation,
addAssociation,
applySettings,
attachFormatError,
attachModelContextChange,
attachParseError,
attachValidationError,
attachValidationSuccess,
bindAggregation,
bindContext,
bindObject,
bindProperty,
destroyAggregation,
detachFormatError,
detachModelContextChange,
detachParseError,
detachValidationError,
detachValidationSuccess,
findAggregatedObjects,
fireFormatError,
fireModelContextChange,
fireParseError,
fireValidationError,
fireValidationSuccess,
getAggregation,
getAssociation,
getBinding,
getBindingContext,
getBindingInfo,
getBindingPath,
getEventingParent,
getId,
getModel,
getObjectBinding,
getOriginInfo,
getParent,
getProperty,
hasModel,
indexOfAggregation,
insertAggregation,
isBound,
isInvalidateSuppressed,
isTreeBinding,
propagateMessages,
removeAggregation,
removeAllAggregation,
removeAllAssociation,
removeAssociation,
setAggregation,
setAssociation,
setBindingContext,
setModel,
setProperty,
unbindAggregation,
unbindContext,
unbindObject,
unbindProperty,
validateAggregation,
validateProperty 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)
- 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:
| {string} | sId? | id for the new control, generated automatically if no id is given |
| {object} | mSettings? | 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.Event} | oControlEvent | |
| {sap.ui.base.EventProvider} | oControlEvent.getSource | |
| {object} | oControlEvent.getParameters | |
| {string} | oControlEvent.getParameters.oldActivePageId | Id of the page which was active before the page change. |
| {string} | oControlEvent.getParameters.newActivePageId | Id 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:
- Deprecated:
- 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:
- Deprecated:
- 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:
| {string} | sClassName | Name of the class being created |
| {object} | oClassInfo? | Object literal with information about the class |
| {function} | FNMetaImpl? | Constructor function for the metadata object; if not given, it defaults to sap.ui.core.ElementMetadata |
Returns:
| {function} | Created class / constructor function |
Returns a metadata object for class sap.m.Carousel.
Returns:
Adds some page to the aggregation pages.
Parameters:
Returns:
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:
| {object} | oData? | An application-specific payload object that will be passed to the event handler along with the event object when firing the event |
| {function} | fnFunction | The function to be called when the event occurs |
| {object} | oListener? | Context object to call the event handler with. Defaults to this sap.m.Carousel itself |
Returns:
Destroys all the pages in the aggregation pages.
Returns:
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:
| {function} | fnFunction | The function to be called, when the event occurs |
| {object} | oListener | Context object on which the given function had to be called |
Returns:
Fires event
pageChanged to attached listeners.
Expects the following event parameters:
oldActivePageId of type stringId of the page which was active before the page change.newActivePageId of type stringId of the page which is active after the page change.
Parameters:
| {Map} | mArguments? | The arguments to pass along with the event |
Returns:
ID of the element which is the current target of the association activePage, or null.
Returns:
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:
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:
| {boolean} | Value of property loop |
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:
Gets content of aggregation
pages.
The content which the carousel displays.
Returns:
getShowPageIndicator(): boolean
Gets current value of property
showPageIndicator.
Show or hide carousel's page indicator.
Default value is true.
Returns:
| {boolean} | Value of property showPageIndicator |
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:
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:
Returns:
| {int} | The index of the provided control in the aggregation if found, or -1 otherwise |
Inserts a page into the aggregation pages.
Parameters:
| {sap.ui.core.Control} | oPage | the page to insert; if empty, nothing is inserted |
| {int} | iIndex | 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 |
Returns:
Call this method to display the next page (corresponds to a swipe right). Returns 'this' for method chaining.
Returns:
Call this method to display the previous page (corresponds to a swipe left). Returns 'this' for method chaining.
Returns:
Removes all the controls from the aggregation
pages.
Additionally, it unregisters them from the hosting UIArea.
Returns:
Removes a page from the aggregation pages.
Parameters:
Returns:
Sets the associated activePage.
Parameters:
| {sap.ui.core.Control} | oActivePage | Id of an element which becomes the new target of this activePage association; alternatively, an element instance may be given |
Returns:
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:
Returns:
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:
| {boolean} | bLoop | New value for property loop |
Returns:
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:
Returns:
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:
| {boolean} | bShowPageIndicator | New value for property showPageIndicator |
Returns:
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:
Returns:
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:
| {object} | oData? | An application-specific payload object that will be passed to the event handler along with the event object when firing the event |
| {function} | fnFunction | The function to be called when the event occurs |
| {object} | oListener? | Context object to call the event handler with. Defaults to this sap.m.Carousel itself |
- Deprecated:
- Since version 1.18.7. Since 1.18.7 pages are no longer loaded or unloaded
Returns:
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:
| {object} | oData? | An application-specific payload object that will be passed to the event handler along with the event object when firing the event |
| {function} | fnFunction | The function to be called when the event occurs |
| {object} | oListener? | Context object to call the event handler with. Defaults to this sap.m.Carousel itself |
- Deprecated:
- Since version 1.18.7. Since 1.18.7 pages are no longer loaded or unloaded
Returns:
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:
| {function} | fnFunction | The function to be called, when the event occurs |
| {object} | oListener | Context object on which the given function had to be called |
- Deprecated:
- Since version 1.18.7. Since 1.18.7 pages are no longer loaded or unloaded
Returns:
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:
| {function} | fnFunction | The function to be called, when the event occurs |
| {object} | oListener | Context object on which the given function had to be called |
- Deprecated:
- Since version 1.18.7. Since 1.18.7 pages are no longer loaded or unloaded
Returns:
Fires event
loadPage to attached listeners.
Expects the following event parameters:
pageId of type stringId of the page which will be loaded
Parameters:
| {Map} | mArguments? | The arguments to pass along with the event |
- Deprecated:
- Since version 1.18.7. Since 1.18.7 pages are no longer loaded or unloaded
Returns:
Fires event
unloadPage to attached listeners.
Expects the following event parameters:
pageId of type stringId of the page which will be unloaded
Parameters:
| {Map} | mArguments? | The arguments to pass along with the event |
- Deprecated:
- Since version 1.18.7. Since 1.18.7 pages are no longer loaded or unloaded
Returns:
Gets current value of property
busyIndicatorSize.
Size of the busy indicators which can be displayed in the carousel.
Default value is 6em.
- Deprecated:
- Since version 1.18.7. Since 1.18.7 pages are no longer loaded or unloaded. Therefore busy indicator is not necessary any longer.
Returns:
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.
- Deprecated:
- Since version 1.18.7. Since 1.18.7 pages are no longer loaded or unloaded. Therefore busy indicator is not necessary any longer.
Returns:
| {boolean} | Value of property showBusyIndicator |
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:
- Deprecated:
- Since version 1.18.7. Since 1.18.7 pages are no longer loaded or unloaded. Therefore busy indicator is not necessary any longer.
Returns:
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:
| {boolean} | bShowBusyIndicator | New value for property showBusyIndicator |
- Deprecated:
- Since version 1.18.7. Since 1.18.7 pages are no longer loaded or unloaded. Therefore busy indicator is not necessary any longer.
Returns: