Class sap.m.ShellModule: sap/m/Shell
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.
sClassName and enriches it with the information contained in oClassInfo.fnFunction to the logout event of this sap.m.Shell.fnFunction from the logout event of this sap.m.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:
- Properties
- title : string
- logo : sap.ui.core.URI
- showLogout : boolean (default: true)
- headerRightText : string
- appWidthLimited : boolean (default: true)
- backgroundColor : sap.ui.core.CSSColor
- backgroundImage : sap.ui.core.URI
- backgroundRepeat : boolean (default: false)
- backgroundOpacity : float (default: 1)
- homeIcon : object
- Aggregations
- app : sap.ui.core.Control (default)
- Events
- logout : 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.
| {string} | sId? | ID for the new control, generated automatically if no ID is given |
| {object} | mSettings? | Initial settings for the new control |
| {sap.ui.base.Event} | oControlEvent | |
| {sap.ui.base.EventProvider} | oControlEvent.getSource | |
| {object} | oControlEvent.getParameters |
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.
| {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 |
| {function} | Created class / constructor function |
| {sap.ui.base.Metadata} | Metadata object describing this class |
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.
| {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.Shell itself |
| {sap.m.Shell} | Reference to this in order to allow method chaining |
app. | {sap.m.Shell} | Reference to this in order to allow method chaining |
fnFunction from the logout event of this sap.m.Shell. The passed function and listener object must match the ones used for event registration.
| {function} | fnFunction | The function to be called, when the event occurs |
| {object} | oListener | Context object on which the given function had to be called |
| {sap.m.Shell} | Reference to this in order to allow method chaining |
logout to attached listeners. | {Map} | mArguments? | The arguments to pass along with the event |
| {sap.m.Shell} | Reference to this in order to allow method chaining |
app. A Shell contains an App or a SplitApp (they may be wrapped in a View). Other control types are not allowed.
| {sap.ui.core.Control} |
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.
| {boolean} | Value of property appWidthLimited |
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.
- Since:
- 1.11.2
| {sap.ui.core.CSSColor} | Value of property backgroundColor |
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.
- Since:
- 1.11.2
| {sap.ui.core.URI} | Value of property backgroundImage |
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.
- Since:
- 1.11.2
| {float} | Value of property backgroundOpacity |
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.
- Since:
- 1.11.2
| {boolean} | Value of property backgroundRepeat |
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).
| {string} | Value of property headerRightText |
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.
| {object} | Value of property homeIcon |
logo. Defines the logo to be displayed next to the App when the screen is sufficiently large.
Note: If property value isn't set, then the logo address is taken from the theme parameters. For reference please see: sap.ui.core.theming.Parameters
| {sap.ui.core.URI} | Value of property logo |
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.
| {boolean} | Value of property showLogout |
title. Defines the application title, which may or may not be displayed outside the actual application, depending on the available screen size.
| {string} | Value of property title |
app. | {sap.ui.core.Control} | oApp | The app to set |
| {sap.m.Shell} | Reference to this in order to allow method chaining |
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.
| {boolean} | bAppWidthLimited | New value for property appWidthLimited |
| {sap.m.Shell} | Reference to this in order to allow method chaining |
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.
| {sap.ui.core.CSSColor} | sBackgroundColor | New value for property backgroundColor |
- Since:
- 1.11.2
| {sap.m.Shell} | Reference to this in order to allow method chaining |
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.
| {sap.ui.core.URI} | sBackgroundImage | New value for property backgroundImage |
- Since:
- 1.11.2
| {sap.m.Shell} | Reference to this in order to allow method chaining |
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.
| {float} | fBackgroundOpacity | New value for property backgroundOpacity |
- Since:
- 1.11.2
| {sap.m.Shell} | Reference to this in order to allow method chaining |
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.
| {boolean} | bBackgroundRepeat | New value for property backgroundRepeat |
- Since:
- 1.11.2
| {sap.m.Shell} | Reference to this in order to allow method chaining |
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.
| {string} | sHeaderRightText | New value for property headerRightText |
| {sap.m.Shell} | Reference to this in order to allow method chaining |
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.
| {object} | oHomeIcon | New value for property homeIcon |
| {sap.m.Shell} | Reference to this in order to allow method chaining |
logo. Defines the logo to be displayed next to the App when the screen is sufficiently large.
Note: If property value isn't set, then the logo address is taken from the theme parameters. For reference please see: sap.ui.core.theming.Parameters
When called with a value of null or undefined, the default value of the property will be restored.
| {sap.ui.core.URI} | sLogo | New value for property logo |
| {sap.m.Shell} | Reference to this in order to allow method chaining |
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.
| {boolean} | bShowLogout | New value for property showLogout |
| {sap.m.Shell} | Reference to this in order to allow method chaining |
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.
| {string} | sTitle | New value for property title |
| {sap.m.Shell} | Reference to this in order to allow method chaining |