class sap.m.TabContainer

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

A container control for managing multiple tabs, allowing the user to open and edit different items simultaneously.

Overview

The control contains a TabStrip area where the user can choose which tab to view/edit. When the open tabs are more than what can be displayed on the screen, there is an overflow mechanism. To access the tabs hidden in the overflow area, the user has to either use the overflow button (left or right arrow) to scroll them horizontally or the overflow overview button (down arrow) and view all open items as a list.

Each tab has a title and a Close Tab button. The title is truncated, if it's longer than 25 characters. On desktop, the Close Tab button is displayed on the currently active tab and for the other tabs it appears on mouse hover. On mobile devices, the Close Tab buttons are always visible.

To show that the open items have unsaved changes, the corresponding tabs can display an asterisk (*) after the title as a visual indication that the item is not saved. This is managed by the app developer using TabContainerItem's modified property.

Usage

The TabContainer can have an Add New Tab button, which appears as a '+' icon on the top-right area of the control. When the user clicks or taps this button, the addNewButtonPress event is fired.

Responsive behavior

The TabContainer is a full-page container that takes 100% of its parent width and height. As the control is expected to occupy the whole parent, it should be the only child of its parent.

When using the sap.m.TabContainer in SAP Quartz theme, the breakpoints and layout paddings could be determined by the container's width. To enable this concept and add responsive padding to the TabContainer control, you may add the following class: sapUiResponsivePadding--header.

This control can be a drop target.

Constructor

Constructor for a new TabContainer.

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.TabContainer(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
backgroundDesign sap.m.PageBackgroundDesign List

Determines the background color of the content in TabContainer.

Since: 1.71.

Visibility: public
showAddNewButton boolean false

Defines whether an Add New Tab button is displayed in the TabStrip.

Visibility: public

Aggregations

Default Aggregation:

Name Cardinality Type Description
_addNewButton 0..1 sap.m.Button

The Add New Tab button displayed in the TabStrip.

_tabStrip 0..1 sap.ui.core.Control

Internal aggregation for managing the tab elements.

items 0..n sap.m.TabContainerItem

The items displayed in the TabContainer.


Associations

Name Cardinality Type Description
selectedItem 0..1 sap.m.TabContainerItem

Sets or retrieves the selected item from the items aggregation.


Events Overview

Event Description
addNewButtonPress

Fired when the Add New Tab button is pressed.

itemClose

Fired when an item is closed.

Listeners may prevent the default action of this event by calling the preventDefault method on the event object.

itemSelect

Fired when an item is pressed.

Listeners may prevent the default action of this event by calling the preventDefault method on the event object.

addNewButtonPress

Fired when the Add New Tab button is pressed.

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

itemClose

Fired when an item is closed.

Listeners may prevent the default action of this event by calling the preventDefault method on the event object.

Param Type Description
oControlEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object
item sap.m.TabContainerItem

The item to be closed.

itemSelect

Fired when an item is pressed.

Listeners may prevent the default action of this event by calling the preventDefault method on the event object.

Param Type Description
oControlEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object
item sap.m.TabContainerItem

The selected item.


Methods Overview

Method Description
addItem

Adds some item to the aggregation items.

attachAddNewButtonPress

Attaches event handler fnFunction to the addNewButtonPress event of this sap.m.TabContainer.

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.TabContainer itself.

Fired when the Add New Tab button is pressed.

attachItemClose

Attaches event handler fnFunction to the itemClose event of this sap.m.TabContainer.

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.TabContainer itself.

Fired when an item is closed.

attachItemSelect

Attaches event handler fnFunction to the itemSelect event of this sap.m.TabContainer.

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.TabContainer itself.

Fired when an item is pressed.

bindItems

Binds aggregation items to model data.

See ManagedObject.bindAggregation for a detailed description of the possible properties of oBindingInfo.

destroyItems

Destroys all the items in the aggregation items.

detachAddNewButtonPress

Detaches event handler fnFunction from the addNewButtonPress event of this sap.m.TabContainer.

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

detachItemClose

Detaches event handler fnFunction from the itemClose event of this sap.m.TabContainer.

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

detachItemSelect

Detaches event handler fnFunction from the itemSelect event of this sap.m.TabContainer.

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

sap.m.TabContainer.extend

Creates a new subclass of class sap.m.TabContainer 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.

fireAddNewButtonPress

Fires event addNewButtonPress to attached listeners.

fireItemClose

Fires event itemClose to attached listeners.

Listeners may prevent the default action of this event by calling the preventDefault method on the event object. The return value of this method indicates whether the default action should be executed.

fireItemSelect

Fires event itemSelect to attached listeners.

Listeners may prevent the default action of this event by calling the preventDefault method on the event object. The return value of this method indicates whether the default action should be executed.

getBackgroundDesign

Gets current value of property backgroundDesign.

Determines the background color of the content in TabContainer.

Default value is List.

getItems

Gets content of aggregation items.

The items displayed in the TabContainer.

sap.m.TabContainer.getMetadata

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

getSelectedItem

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

getShowAddNewButton

Gets current value of property showAddNewButton.

Defines whether an Add New Tab button is displayed in the TabStrip.

Default value is false.

indexOfItem

Checks for the provided sap.m.TabContainerItem in the aggregation items. and returns its index if found or -1 otherwise.

insertItem

Inserts a item into the aggregation items.

removeAllItems

Removes all the controls from the aggregation items.

Additionally, it unregisters them from the hosting UIArea.

removeItem

Removes an item from the aggregation named items.

setBackgroundDesign

Sets a new value for property backgroundDesign.

Determines the background color of the content in TabContainer.

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

Default value is List.

setSelectedItem

Sets the associated selectedItem.

setShowAddNewButton

Sets a new value for property showAddNewButton.

Defines whether an Add New Tab button is displayed in the TabStrip.

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

Default value is false.

unbindItems

Unbinds aggregation items from model data.

addItem

Adds some item to the aggregation items.

Param Type DefaultValue Description
oItem sap.m.TabContainerItem

The item to add; if empty, nothing is inserted

attachAddNewButtonPress

Attaches event handler fnFunction to the addNewButtonPress event of this sap.m.TabContainer.

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.TabContainer itself.

Fired when the Add New Tab button is pressed.

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.TabContainer itself

attachItemClose

Attaches event handler fnFunction to the itemClose event of this sap.m.TabContainer.

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.TabContainer itself.

Fired when an item is closed.

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.TabContainer itself

attachItemSelect

Attaches event handler fnFunction to the itemSelect event of this sap.m.TabContainer.

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.TabContainer itself.

Fired when an item is pressed.

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.TabContainer itself

bindItems

Binds aggregation items to model data.

See ManagedObject.bindAggregation for a detailed description of the possible properties of oBindingInfo.

Param Type DefaultValue Description
oBindingInfo sap.ui.base.ManagedObject.AggregationBindingInfo

The binding information

destroyItems

Destroys all the items in the aggregation items.

detachAddNewButtonPress

Detaches event handler fnFunction from the addNewButtonPress event of this sap.m.TabContainer.

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

detachItemClose

Detaches event handler fnFunction from the itemClose event of this sap.m.TabContainer.

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

detachItemSelect

Detaches event handler fnFunction from the itemSelect event of this sap.m.TabContainer.

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

sap.m.TabContainer.extend

Creates a new subclass of class sap.m.TabContainer 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

fireAddNewButtonPress

Fires event addNewButtonPress to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

fireItemClose

Fires event itemClose to attached listeners.

Listeners may prevent the default action of this event by calling the preventDefault method on the event object. The return value of this method indicates whether the default action should be executed.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

item sap.m.TabContainerItem

The item to be closed.

fireItemSelect

Fires event itemSelect to attached listeners.

Listeners may prevent the default action of this event by calling the preventDefault method on the event object. The return value of this method indicates whether the default action should be executed.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

item sap.m.TabContainerItem

The selected item.

getBackgroundDesign

Gets current value of property backgroundDesign.

Determines the background color of the content in TabContainer.

Default value is List.

getItems

Gets content of aggregation items.

The items displayed in the TabContainer.

sap.m.TabContainer.getMetadata

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

getSelectedItem

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

getShowAddNewButton

Gets current value of property showAddNewButton.

Defines whether an Add New Tab button is displayed in the TabStrip.

Default value is false.

indexOfItem

Checks for the provided sap.m.TabContainerItem in the aggregation items. and returns its index if found or -1 otherwise.

Param Type DefaultValue Description
oItem sap.m.TabContainerItem

The item whose index is looked for

insertItem

Inserts a item into the aggregation items.

Param Type DefaultValue Description
oItem sap.m.TabContainerItem

The item to insert; if empty, nothing is inserted

iIndex int

The 0-based index the item should be inserted at; for a negative value of iIndex, the item is inserted at position 0; for a value greater than the current size of the aggregation, the item is inserted at the last position

removeAllItems

Removes all the controls from the aggregation items.

Additionally, it unregisters them from the hosting UIArea.

removeItem

Removes an item from the aggregation named items.

Param Type DefaultValue Description
vItem int string sap.m.TabContainerItem

The item to remove or its index or ID

setBackgroundDesign

Sets a new value for property backgroundDesign.

Determines the background color of the content in TabContainer.

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

Default value is List.

Param Type DefaultValue Description
sBackgroundDesign sap.m.PageBackgroundDesign List

New value for property backgroundDesign

setSelectedItem

Sets the associated selectedItem.

Param Type DefaultValue Description
oSelectedItem sap.ui.core.ID sap.m.TabContainerItem

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

setShowAddNewButton

Sets a new value for property showAddNewButton.

Defines whether an Add New Tab button is displayed in the TabStrip.

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
bShowAddNewButton boolean false

New value for property showAddNewButton

unbindItems

Unbinds aggregation items from model data.