Class sap.m.ShellModule: sap/m/Shell

extends Control

The Shell control can be used as root element of applications. It can contain an App or a SplitApp control. The Shell provides some overarching functionality for the overall application and takes care of visual adaptation, such as a frame around the App, on desktop browser platforms.
Since: 1.12.
Constructor Summary
new sap.m.Shell(sId?, mSettings?)Constructor for a new Shell.
Event Summary
logout(oControlEvent)Fires when the user presses the logout button/link.
Events borrowed from class sap.ui.core.Control
Method Summary
sap.m.Shell.extend(sClassName, oClassInfo?, FNMetaImpl?)Creates a new subclass of class sap.m.Shell with name sClassName and enriches it with the information contained in oClassInfo.
sap.m.Shell.getMetadata()Returns a metadata object for class sap.m.Shell.
attachLogout(oData?, fnFunction, oListener?)Attaches event handler fnFunction to the logout event of this sap.m.Shell.
destroyApp()Destroys the app in the aggregation app.
detachLogout(fnFunction, oListener)Detaches event handler fnFunction from the logout event of this sap.m.Shell.
fireLogout(mParameters?)Fires event logout to attached listeners.
getApp()Gets content of aggregation app.
getAppWidthLimited()Gets current value of property appWidthLimited.
getBackgroundColor()Gets current value of property backgroundColor.
getBackgroundImage()Gets current value of property backgroundImage.
getBackgroundOpacity()Gets current value of property backgroundOpacity.
getBackgroundRepeat()Gets current value of property backgroundRepeat.
getHeaderRightText()Gets current value of property headerRightText.
getHomeIcon()Gets current value of property homeIcon.
getLogo()Gets current value of property logo.
getShowLogout()Gets current value of property showLogout.
getTitle()Gets current value of property title.
getTitleLevel()Gets current value of property titleLevel.
setApp(oApp)Sets the aggregated app.
setAppWidthLimited(bAppWidthLimited)Sets a new value for property appWidthLimited.
setBackgroundColor(sBackgroundColor)Sets a new value for property backgroundColor.
setBackgroundImage(sBackgroundImage)Sets a new value for property backgroundImage.
setBackgroundOpacity(fBackgroundOpacity)Sets a new value for property backgroundOpacity.
setBackgroundRepeat(bBackgroundRepeat)Sets a new value for property backgroundRepeat.
setHeaderRightText(sHeaderRightText)Sets a new value for property headerRightText.
setHomeIcon(oHomeIcon)Sets a new value for property homeIcon.
setLogo(sLogo)Sets a new value for property logo.
setShowLogout(bShowLogout)Sets a new value for property showLogout.
setTitle(sTitle)Sets a new value for property title.
setTitleLevel(sTitleLevel)Sets a new value for property titleLevel.
Constructor Detail
new sap.m.Shell(sId?, mSettings?)

Constructor for a new Shell.

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:

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
logout(oControlEvent)
Fires when the user presses the logout button/link.
Parameters:
sap.ui.base.EventoControlEvent
sap.ui.base.EventProvideroControlEvent.getSource
objectoControlEvent.getParameters
Method Detail
sap.m.Shell.extend(sClassName, oClassInfo?, FNMetaImpl?): function

Creates a new subclass of class sap.m.Shell 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.Shell.getMetadata(): sap.ui.base.Metadata
Returns a metadata object for class sap.m.Shell.
Returns:
sap.ui.base.MetadataMetadata object describing this class
attachLogout(oData?, fnFunction, oListener?): sap.m.Shell

Attaches event handler fnFunction to the logout event of this sap.m.Shell.

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

Fires when the user presses the logout button/link.

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.Shell itself
Returns:
sap.m.ShellReference to this in order to allow method chaining
destroyApp(): sap.m.Shell
Destroys the app in the aggregation app.
Returns:
sap.m.ShellReference to this in order to allow method chaining
detachLogout(fnFunction, oListener): sap.m.Shell

Detaches event handler fnFunction from the logout event of this sap.m.Shell.

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.ShellReference to this in order to allow method chaining
fireLogout(mParameters?): sap.m.Shell
Fires event logout to attached listeners.
Parameters:
objectmParameters?Parameters to pass along with the event
Returns:
sap.m.ShellReference to this in order to allow method chaining

Gets content of aggregation app.

A Shell contains an App or a SplitApp (they may be wrapped in a View). Other control types are not allowed.

Returns:
sap.ui.core.Control
getAppWidthLimited(): boolean

Gets current value of property appWidthLimited.

Determines whether the width of the content (the aggregated App) should be limited or extended to the full screen width.

Default value is true.

Returns:
booleanValue of property appWidthLimited
getBackgroundColor(): sap.ui.core.CSSColor

Gets current value of property backgroundColor.

Defines the background color of the Shell. If set, this color will override the default background defined by the theme. This should only be set when really required. Any configured background image will be placed above this colored background. Use the backgroundRepeat property to define whether this image should be stretched to cover the complete Shell or whether it should be tiled.

Returns:
sap.ui.core.CSSColorValue of property backgroundColor
Since:
1.11.2
getBackgroundImage(): sap.ui.core.URI

Gets current value of property backgroundImage.

Defines the background image of the Shell. If set, this image will override the default background defined by the theme. This should only be set when really required. This background image will be placed above any color set for the background. Use the backgroundRepeat property to define whether this image should be stretched to cover the complete Shell or whether it should be tiled.

Returns:
sap.ui.core.URIValue of property backgroundImage
Since:
1.11.2
getBackgroundOpacity(): float

Gets current value of property backgroundOpacity.

Defines the opacity of the background image. The opacity can be set between 0 (fully transparent) and 1 (fully opaque). This can be used to improve readability of the Shell content by making the background image partly transparent.

Default value is 1.

Returns:
floatValue of property backgroundOpacity
Since:
1.11.2
getBackgroundRepeat(): boolean

Gets current value of property backgroundRepeat.

Determines whether the background image (if configured) should be proportionally stretched to cover the whole Shell (false, default) or whether it should be tiled (true).

Default value is false.

Returns:
booleanValue of property backgroundRepeat
Since:
1.11.2
getHeaderRightText(): string

Gets current value of property headerRightText.

Defines texts, such as the name of the logged-in user, which should be displayed on the right side of the header (if there is enough space to display the header at all - this only happens on very tall screens (1568px height), otherwise, it is always hidden).

Returns:
stringValue of property headerRightText
getHomeIcon(): object

Gets current value of property homeIcon.

Sets the icon used for the mobile device home screen and the icon to be used for bookmarks by desktop browsers.

This property should be only set once, and as early as possible. Subsequent calls replace the previous icon settings and may lead to different behavior depending on the browser.

Different image sizes for device home screen need to be given as PNG images, an ICO file needs to be given as desktop browser bookmark icon (other file formats may not work in all browsers). The precomposed flag defines whether there is already a glow effect contained in the home screen images (or whether iOS should add such an effect). The given structure could look like this: { 'phone':'phone-icon_57x57.png', 'phone@2':'phone-retina_114x114.png', 'tablet':'tablet-icon_72x72.png', 'tablet@2':'tablet-retina_144x144.png', 'precomposed':true, 'favicon':'favicon.ico' }

See jQuery.sap.setIcons() for full documentation.

Returns:
objectValue of property homeIcon
getShowLogout(): boolean

Gets current value of property showLogout.

Determines whether the Logout button should be displayed. Currently, this only happens on very tall screens (1568px height), otherwise, it is always hidden.

Default value is true.

Returns:
booleanValue of property showLogout
getTitle(): string

Gets current value of property title.

Defines the application title, which may or may not be displayed outside the actual application, depending on the available screen size.

Returns:
stringValue of property title
getTitleLevel(): sap.ui.core.TitleLevel

Gets current value of property titleLevel.

Defines the semantic level of the title.

This information is used by assistive technologies, such as screen readers to create a hierarchical site map for faster navigation. Depending on this setting an HTML h1-h6 element is used.

Default value is H1.

Returns:
sap.ui.core.TitleLevelValue of property titleLevel
setApp(oApp): sap.m.Shell
Sets the aggregated app.
Parameters:
sap.ui.core.ControloAppThe app to set
Returns:
sap.m.ShellReference to this in order to allow method chaining
setAppWidthLimited(bAppWidthLimited): sap.m.Shell

Sets a new value for property appWidthLimited.

Determines whether the width of the content (the aggregated App) should be limited or extended to the full screen width.

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

Default value is true.

Parameters:
booleanbAppWidthLimitedNew value for property appWidthLimited
Returns:
sap.m.ShellReference to this in order to allow method chaining
setBackgroundColor(sBackgroundColor): sap.m.Shell

Sets a new value for property backgroundColor.

Defines the background color of the Shell. If set, this color will override the default background defined by the theme. This should only be set when really required. Any configured background image will be placed above this colored background. Use the backgroundRepeat property to define whether this image should be stretched to cover the complete Shell or whether it should be tiled.

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

Parameters:
sap.ui.core.CSSColorsBackgroundColorNew value for property backgroundColor
Returns:
sap.m.ShellReference to this in order to allow method chaining
Since:
1.11.2
setBackgroundImage(sBackgroundImage): sap.m.Shell

Sets a new value for property backgroundImage.

Defines the background image of the Shell. If set, this image will override the default background defined by the theme. This should only be set when really required. This background image will be placed above any color set for the background. Use the backgroundRepeat property to define whether this image should be stretched to cover the complete Shell or whether it should be tiled.

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

Parameters:
sap.ui.core.URIsBackgroundImageNew value for property backgroundImage
Returns:
sap.m.ShellReference to this in order to allow method chaining
Since:
1.11.2
setBackgroundOpacity(fBackgroundOpacity): sap.m.Shell

Sets a new value for property backgroundOpacity.

Defines the opacity of the background image. The opacity can be set between 0 (fully transparent) and 1 (fully opaque). This can be used to improve readability of the Shell content by making the background image partly transparent.

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

Default value is 1.

Parameters:
floatfBackgroundOpacityNew value for property backgroundOpacity
Returns:
sap.m.ShellReference to this in order to allow method chaining
Since:
1.11.2
setBackgroundRepeat(bBackgroundRepeat): sap.m.Shell

Sets a new value for property backgroundRepeat.

Determines whether the background image (if configured) should be proportionally stretched to cover the whole Shell (false, default) or whether it should be tiled (true).

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

Default value is false.

Parameters:
booleanbBackgroundRepeatNew value for property backgroundRepeat
Returns:
sap.m.ShellReference to this in order to allow method chaining
Since:
1.11.2
setHeaderRightText(sHeaderRightText): sap.m.Shell

Sets a new value for property headerRightText.

Defines texts, such as the name of the logged-in user, which should be displayed on the right side of the header (if there is enough space to display the header at all - this only happens on very tall screens (1568px height), otherwise, it is always hidden).

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

Parameters:
stringsHeaderRightTextNew value for property headerRightText
Returns:
sap.m.ShellReference to this in order to allow method chaining
setHomeIcon(oHomeIcon): sap.m.Shell

Sets a new value for property homeIcon.

Sets the icon used for the mobile device home screen and the icon to be used for bookmarks by desktop browsers.

This property should be only set once, and as early as possible. Subsequent calls replace the previous icon settings and may lead to different behavior depending on the browser.

Different image sizes for device home screen need to be given as PNG images, an ICO file needs to be given as desktop browser bookmark icon (other file formats may not work in all browsers). The precomposed flag defines whether there is already a glow effect contained in the home screen images (or whether iOS should add such an effect). The given structure could look like this: { 'phone':'phone-icon_57x57.png', 'phone@2':'phone-retina_114x114.png', 'tablet':'tablet-icon_72x72.png', 'tablet@2':'tablet-retina_144x144.png', 'precomposed':true, 'favicon':'favicon.ico' }

See jQuery.sap.setIcons() for full documentation.

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

Parameters:
objectoHomeIconNew value for property homeIcon
Returns:
sap.m.ShellReference to this in order to allow method chaining
setShowLogout(bShowLogout): sap.m.Shell

Sets a new value for property showLogout.

Determines whether the Logout button should be displayed. Currently, this only happens on very tall screens (1568px height), otherwise, it is always hidden.

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

Default value is true.

Parameters:
booleanbShowLogoutNew value for property showLogout
Returns:
sap.m.ShellReference to this in order to allow method chaining
setTitle(sTitle): sap.m.Shell

Sets a new value for property title.

Defines the application title, which may or may not be displayed outside the actual application, depending on the available screen size.

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

Parameters:
stringsTitleNew value for property title
Returns:
sap.m.ShellReference to this in order to allow method chaining
setTitleLevel(sTitleLevel): sap.m.Shell

Sets a new value for property titleLevel.

Defines the semantic level of the title.

This information is used by assistive technologies, such as screen readers to create a hierarchical site map for faster navigation. Depending on this setting an HTML h1-h6 element is used.

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

Default value is H1.

Parameters:
sap.ui.core.TitleLevelsTitleLevelNew value for property titleLevel
Returns:
sap.m.ShellReference to this in order to allow method chaining