class sap.m.App

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

The root element of a UI5 mobile app.

Overview

The App inherits from sap.m.NavContainer and thus provides its navigation capabilities. It adds certain header tags to the HTML page which are considered useful for mobile apps.

Usage

You can configure the home icon of the App. For more information, see the homeIcon property.

There are options for setting the background color and a background image with the use of the backgroundColor and backgroundImage properties.

Note: Keep in mind that by default (isTopLevel is set to true) sap.m.App traverses its parent elements and automatically sets their height to 100%.


Constructor

Constructor for a new App.

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.App(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
backgroundColor string

Background color of the App. If set, this color will override the default background defined by the theme. So this should only be set when really required. Any configured background image will be placed above this colored background. But any theme adaptation in the Theme Designer will override this setting. Use the "backgroundRepeat" property to define whether this image should be stretched to cover the complete App or whether it should be tiled.

Since: 1.11.2.

Visibility: public
backgroundImage sap.ui.core.URI

Background image of the App. If set, this image will override the default background defined by the theme. So this should only be set when really required. This background image will be placed above any color set for the background. But any theme adaptation in the Theme Designer will override this image setting. Use the "backgroundRepeat" property to define whether this image should be stretched to cover the complete App or whether it should be tiled.

Since: 1.11.2.

Visibility: public
backgroundOpacity float 1

Opacity of the background image. The opacity can be set between 0 (fully transparent) and 1 fully opaque). This can be used to make the application content better readable by making the background image partly transparent.

Since: 1.11.2.

Visibility: public
backgroundRepeat boolean false

Whether the background image (if configured) should be proportionally stretched to cover the whole App (false) or whether it should be tiled (true).

Since: 1.11.2.

Visibility: public
homeIcon any

The icon to be displayed on the home screen of iOS devices after the user does "add to home screen".

Note that only the first attempt to set the homeIcon will be executed, subsequent settings are ignored.

This icon must be in PNG format. The property can either hold the URL of one single icon which is used for all devices (and possibly scaled, which looks not perfect), or an object holding icon URLs for the different required sizes.

A desktop icon (used for bookmarks and overriding the favicon) can also be configured. This requires an object to be given and the "icon" property of this object then defines the desktop bookmark icon. The ICO format is supported by all browsers. ICO is also preferred for this desktop icon setting because the file can contain different images for different resolutions.

One example is:

app.setHomeIcon({ 'phone':'phone-icon.png', 'phone@2':'phone-retina.png', 'tablet':'tablet-icon.png', 'tablet@2':'tablet-retina.png', 'icon':'desktop.ico' });

The respective image sizes are 57/114 px for the phone and 72/144 px for the tablet. If an object is given but one of the sizes is not given, the largest given icon will be used for this size.

On Android these icons may or may not be used by the device. Apparently chances can be improved by adding glare effect and rounded corners, setting the file name so it ends with "-precomposed.png" and setting the "homeIconPrecomposed" property to "true".

Visibility: public
isTopLevel boolean true

Determines whether sap.m.App is used as a top level control.

Note: When the isTopLevel property set to true, sap.m.App traverses its parent DOM elements and sets their height to 100%.

Since: 1.91.

Visibility: public
mobileWebAppCapable boolean true

Determines whether the App is displayed without address bar when opened from an exported home screen icon on a mobile device.

Keep in mind that if enabled, there is no back button provided by the browser and the app must provide own navigation on all displayed pages to avoid dead ends.

Note The property can be toggled, but it doesn't take effect in real time. It takes the set value at the moment when the home screen icon is exported by the user. For example, if the icon is exported while the property is set to true, the App will have no address bar when opened from that same icon regardless of a changed property value to false at a later time.

Since: 1.58.0.

Visibility: public

Borrowed Properties

Name Type Default Value Description
autoFocus boolean true

Determines whether the initial focus is set automatically on first rendering and after navigating to a new page. This is useful when on touch devices the keyboard pops out due to the focus being automatically set on an input field. If necessary, the AfterShow event can be used to focus another element, only if autoFocus is set to false.

Note: The following scenarios are possible, depending on where the focus was before navigation to a new page:

  • If autoFocus is set to true and the focus was inside the current page, the focus will be moved automatically on the new page.
  • If autoFocus is set to false and the focus was inside the current page, the focus will disappear.
  • If the focus was outside the current page, after the navigation it will remain unchanged regardless of what is set to the autoFocus property.
  • If the autoFocus is set to false and at the same time another wrapping control has its own logic for focus restoring upon rerendering, the focus will still appear.


Since: 1.30.

Visibility: public
defaultTransitionName string slide

The type of the transition/animation to apply when "to()" is called without defining a transition type to use. The default is "slide". Other options are: "baseSlide", "fade", "flip" and "show" - and the names of any registered custom transitions.

Since: 1.7.1.

Visibility: public
height sap.ui.core.CSSSize 100%

The height of the NavContainer. Can be changed when the NavContainer should not cover the whole available area.

Visibility: public
visible boolean true

Whether the NavContainer is visible.

Visibility: public
width sap.ui.core.CSSSize 100%

The width of the NavContainer. Can be changed when the NavContainer should not cover the whole available area.

Visibility: public

Borrowed Aggregations

Name Cardinality Type Description
pages 0..n sap.ui.core.Control

The content entities between which this NavContainer navigates. These can be of type sap.m.Page, sap.ui.core.mvc.View, sap.m.Carousel or any other control with fullscreen/page semantics.

These aggregated controls will receive navigation events like BeforeShow, they are documented in the pseudo interface sap.m.NavContainerChild


Events Overview

Event Description
orientationChange

Fired when the orientation (portrait/landscape) of the device is changed.

orientationChange

Fired when the orientation (portrait/landscape) of the device is changed.

use {@link sap.ui.Device.orientation.attachHandler} instead.
Param Type Description
oControlEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object
landscape boolean

Whether the device is in landscape orientation.


Methods Overview

Method Description
attachOrientationChange

Attaches event handler fnFunction to the orientationChange event of this sap.m.App.

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

Fired when the orientation (portrait/landscape) of the device is changed.

Since 1.20.0 use {@link sap.ui.Device.orientation.attachHandler} instead.
detachOrientationChange

Detaches event handler fnFunction from the orientationChange event of this sap.m.App.

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

Since 1.20.0 use {@link sap.ui.Device.orientation.attachHandler} instead.
sap.m.App.extend

Creates a new subclass of class sap.m.App with name sClassName and enriches it with the information contained in oClassInfo.

oClassInfo might contain the same kind of information as described in sap.m.NavContainer.extend.

fireOrientationChange

Fires event orientationChange to attached listeners.

Since 1.20.0 use {@link sap.ui.Device.orientation.attachHandler} instead.
getBackgroundColor

Gets current value of property backgroundColor.

Background color of the App. If set, this color will override the default background defined by the theme. So this should only be set when really required. Any configured background image will be placed above this colored background. But any theme adaptation in the Theme Designer will override this setting. Use the "backgroundRepeat" property to define whether this image should be stretched to cover the complete App or whether it should be tiled.

getBackgroundImage

Gets current value of property backgroundImage.

Background image of the App. If set, this image will override the default background defined by the theme. So this should only be set when really required. This background image will be placed above any color set for the background. But any theme adaptation in the Theme Designer will override this image setting. Use the "backgroundRepeat" property to define whether this image should be stretched to cover the complete App or whether it should be tiled.

getBackgroundOpacity

Gets current value of property backgroundOpacity.

Opacity of the background image. The opacity can be set between 0 (fully transparent) and 1 fully opaque). This can be used to make the application content better readable by making the background image partly transparent.

Default value is 1.

getBackgroundRepeat

Gets current value of property backgroundRepeat.

Whether the background image (if configured) should be proportionally stretched to cover the whole App (false) or whether it should be tiled (true).

Default value is false.

getHomeIcon

Gets current value of property homeIcon.

The icon to be displayed on the home screen of iOS devices after the user does "add to home screen".

Note that only the first attempt to set the homeIcon will be executed, subsequent settings are ignored.

This icon must be in PNG format. The property can either hold the URL of one single icon which is used for all devices (and possibly scaled, which looks not perfect), or an object holding icon URLs for the different required sizes.

A desktop icon (used for bookmarks and overriding the favicon) can also be configured. This requires an object to be given and the "icon" property of this object then defines the desktop bookmark icon. The ICO format is supported by all browsers. ICO is also preferred for this desktop icon setting because the file can contain different images for different resolutions.

One example is:

app.setHomeIcon({ 'phone':'phone-icon.png', 'phone@2':'phone-retina.png', 'tablet':'tablet-icon.png', 'tablet@2':'tablet-retina.png', 'icon':'desktop.ico' });

The respective image sizes are 57/114 px for the phone and 72/144 px for the tablet. If an object is given but one of the sizes is not given, the largest given icon will be used for this size.

On Android these icons may or may not be used by the device. Apparently chances can be improved by adding glare effect and rounded corners, setting the file name so it ends with "-precomposed.png" and setting the "homeIconPrecomposed" property to "true".

getIsTopLevel

Gets current value of property isTopLevel.

Determines whether sap.m.App is used as a top level control.

Note: When the isTopLevel property set to true, sap.m.App traverses its parent DOM elements and sets their height to 100%.

Default value is true.

sap.m.App.getMetadata

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

getMobileWebAppCapable

Gets current value of property mobileWebAppCapable.

Determines whether the App is displayed without address bar when opened from an exported home screen icon on a mobile device.

Keep in mind that if enabled, there is no back button provided by the browser and the app must provide own navigation on all displayed pages to avoid dead ends.

Note The property can be toggled, but it doesn't take effect in real time. It takes the set value at the moment when the home screen icon is exported by the user. For example, if the icon is exported while the property is set to true, the App will have no address bar when opened from that same icon regardless of a changed property value to false at a later time.

Default value is true.

setBackgroundColor

Sets a new value for property backgroundColor.

Background color of the App. If set, this color will override the default background defined by the theme. So this should only be set when really required. Any configured background image will be placed above this colored background. But any theme adaptation in the Theme Designer will override this setting. Use the "backgroundRepeat" property to define whether this image should be stretched to cover the complete App or whether it should be tiled.

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

setBackgroundImage

Sets a new value for property backgroundImage.

Background image of the App. If set, this image will override the default background defined by the theme. So this should only be set when really required. This background image will be placed above any color set for the background. But any theme adaptation in the Theme Designer will override this image setting. Use the "backgroundRepeat" property to define whether this image should be stretched to cover the complete App or whether it should be tiled.

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

setBackgroundOpacity

Sets a new value for property backgroundOpacity.

Opacity of the background image. The opacity can be set between 0 (fully transparent) and 1 fully opaque). This can be used to make the application content better readable 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.

setBackgroundRepeat

Sets a new value for property backgroundRepeat.

Whether the background image (if configured) should be proportionally stretched to cover the whole App (false) 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.

setHomeIcon

Sets a new value for property homeIcon.

The icon to be displayed on the home screen of iOS devices after the user does "add to home screen".

Note that only the first attempt to set the homeIcon will be executed, subsequent settings are ignored.

This icon must be in PNG format. The property can either hold the URL of one single icon which is used for all devices (and possibly scaled, which looks not perfect), or an object holding icon URLs for the different required sizes.

A desktop icon (used for bookmarks and overriding the favicon) can also be configured. This requires an object to be given and the "icon" property of this object then defines the desktop bookmark icon. The ICO format is supported by all browsers. ICO is also preferred for this desktop icon setting because the file can contain different images for different resolutions.

One example is:

app.setHomeIcon({ 'phone':'phone-icon.png', 'phone@2':'phone-retina.png', 'tablet':'tablet-icon.png', 'tablet@2':'tablet-retina.png', 'icon':'desktop.ico' });

The respective image sizes are 57/114 px for the phone and 72/144 px for the tablet. If an object is given but one of the sizes is not given, the largest given icon will be used for this size.

On Android these icons may or may not be used by the device. Apparently chances can be improved by adding glare effect and rounded corners, setting the file name so it ends with "-precomposed.png" and setting the "homeIconPrecomposed" property to "true".

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

setIsTopLevel

Sets a new value for property isTopLevel.

Determines whether sap.m.App is used as a top level control.

Note: When the isTopLevel property set to true, sap.m.App traverses its parent DOM elements and sets their height to 100%.

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

Default value is true.

setMobileWebAppCapable

Sets a new value for property mobileWebAppCapable.

Determines whether the App is displayed without address bar when opened from an exported home screen icon on a mobile device.

Keep in mind that if enabled, there is no back button provided by the browser and the app must provide own navigation on all displayed pages to avoid dead ends.

Note The property can be toggled, but it doesn't take effect in real time. It takes the set value at the moment when the home screen icon is exported by the user. For example, if the icon is exported while the property is set to true, the App will have no address bar when opened from that same icon regardless of a changed property value to false at a later time.

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

Default value is true.

attachOrientationChange

Attaches event handler fnFunction to the orientationChange event of this sap.m.App.

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

Fired when the orientation (portrait/landscape) of the device is changed.

Since 1.20.0 use {@link sap.ui.Device.orientation.attachHandler} instead.
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.App itself

detachOrientationChange

Detaches event handler fnFunction from the orientationChange event of this sap.m.App.

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

Since 1.20.0 use {@link sap.ui.Device.orientation.attachHandler} instead.
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.App.extend

Creates a new subclass of class sap.m.App with name sClassName and enriches it with the information contained in oClassInfo.

oClassInfo might contain the same kind of information as described in sap.m.NavContainer.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

fireOrientationChange

Fires event orientationChange to attached listeners.

Since 1.20.0 use {@link sap.ui.Device.orientation.attachHandler} instead.
Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

landscape boolean

Whether the device is in landscape orientation.

getBackgroundColor

Gets current value of property backgroundColor.

Background color of the App. If set, this color will override the default background defined by the theme. So this should only be set when really required. Any configured background image will be placed above this colored background. But any theme adaptation in the Theme Designer will override this setting. Use the "backgroundRepeat" property to define whether this image should be stretched to cover the complete App or whether it should be tiled.

getBackgroundImage

Gets current value of property backgroundImage.

Background image of the App. If set, this image will override the default background defined by the theme. So this should only be set when really required. This background image will be placed above any color set for the background. But any theme adaptation in the Theme Designer will override this image setting. Use the "backgroundRepeat" property to define whether this image should be stretched to cover the complete App or whether it should be tiled.

getBackgroundOpacity

Gets current value of property backgroundOpacity.

Opacity of the background image. The opacity can be set between 0 (fully transparent) and 1 fully opaque). This can be used to make the application content better readable by making the background image partly transparent.

Default value is 1.

getBackgroundRepeat

Gets current value of property backgroundRepeat.

Whether the background image (if configured) should be proportionally stretched to cover the whole App (false) or whether it should be tiled (true).

Default value is false.

getHomeIcon

Gets current value of property homeIcon.

The icon to be displayed on the home screen of iOS devices after the user does "add to home screen".

Note that only the first attempt to set the homeIcon will be executed, subsequent settings are ignored.

This icon must be in PNG format. The property can either hold the URL of one single icon which is used for all devices (and possibly scaled, which looks not perfect), or an object holding icon URLs for the different required sizes.

A desktop icon (used for bookmarks and overriding the favicon) can also be configured. This requires an object to be given and the "icon" property of this object then defines the desktop bookmark icon. The ICO format is supported by all browsers. ICO is also preferred for this desktop icon setting because the file can contain different images for different resolutions.

One example is:

app.setHomeIcon({ 'phone':'phone-icon.png', 'phone@2':'phone-retina.png', 'tablet':'tablet-icon.png', 'tablet@2':'tablet-retina.png', 'icon':'desktop.ico' });

The respective image sizes are 57/114 px for the phone and 72/144 px for the tablet. If an object is given but one of the sizes is not given, the largest given icon will be used for this size.

On Android these icons may or may not be used by the device. Apparently chances can be improved by adding glare effect and rounded corners, setting the file name so it ends with "-precomposed.png" and setting the "homeIconPrecomposed" property to "true".

getIsTopLevel

Gets current value of property isTopLevel.

Determines whether sap.m.App is used as a top level control.

Note: When the isTopLevel property set to true, sap.m.App traverses its parent DOM elements and sets their height to 100%.

Default value is true.

sap.m.App.getMetadata

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

getMobileWebAppCapable

Gets current value of property mobileWebAppCapable.

Determines whether the App is displayed without address bar when opened from an exported home screen icon on a mobile device.

Keep in mind that if enabled, there is no back button provided by the browser and the app must provide own navigation on all displayed pages to avoid dead ends.

Note The property can be toggled, but it doesn't take effect in real time. It takes the set value at the moment when the home screen icon is exported by the user. For example, if the icon is exported while the property is set to true, the App will have no address bar when opened from that same icon regardless of a changed property value to false at a later time.

Default value is true.

setBackgroundColor

Sets a new value for property backgroundColor.

Background color of the App. If set, this color will override the default background defined by the theme. So this should only be set when really required. Any configured background image will be placed above this colored background. But any theme adaptation in the Theme Designer will override this setting. Use the "backgroundRepeat" property to define whether this image should be stretched to cover the complete App or whether it should be tiled.

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

Param Type DefaultValue Description
sBackgroundColor string

New value for property backgroundColor

setBackgroundImage

Sets a new value for property backgroundImage.

Background image of the App. If set, this image will override the default background defined by the theme. So this should only be set when really required. This background image will be placed above any color set for the background. But any theme adaptation in the Theme Designer will override this image setting. Use the "backgroundRepeat" property to define whether this image should be stretched to cover the complete App or whether it should be tiled.

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

Param Type DefaultValue Description
sBackgroundImage sap.ui.core.URI

New value for property backgroundImage

setBackgroundOpacity

Sets a new value for property backgroundOpacity.

Opacity of the background image. The opacity can be set between 0 (fully transparent) and 1 fully opaque). This can be used to make the application content better readable 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.

Param Type DefaultValue Description
fBackgroundOpacity float 1

New value for property backgroundOpacity

setBackgroundRepeat

Sets a new value for property backgroundRepeat.

Whether the background image (if configured) should be proportionally stretched to cover the whole App (false) 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.

Param Type DefaultValue Description
bBackgroundRepeat boolean false

New value for property backgroundRepeat

setHomeIcon

Sets a new value for property homeIcon.

The icon to be displayed on the home screen of iOS devices after the user does "add to home screen".

Note that only the first attempt to set the homeIcon will be executed, subsequent settings are ignored.

This icon must be in PNG format. The property can either hold the URL of one single icon which is used for all devices (and possibly scaled, which looks not perfect), or an object holding icon URLs for the different required sizes.

A desktop icon (used for bookmarks and overriding the favicon) can also be configured. This requires an object to be given and the "icon" property of this object then defines the desktop bookmark icon. The ICO format is supported by all browsers. ICO is also preferred for this desktop icon setting because the file can contain different images for different resolutions.

One example is:

app.setHomeIcon({ 'phone':'phone-icon.png', 'phone@2':'phone-retina.png', 'tablet':'tablet-icon.png', 'tablet@2':'tablet-retina.png', 'icon':'desktop.ico' });

The respective image sizes are 57/114 px for the phone and 72/144 px for the tablet. If an object is given but one of the sizes is not given, the largest given icon will be used for this size.

On Android these icons may or may not be used by the device. Apparently chances can be improved by adding glare effect and rounded corners, setting the file name so it ends with "-precomposed.png" and setting the "homeIconPrecomposed" property to "true".

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

Param Type DefaultValue Description
oHomeIcon any

New value for property homeIcon

setIsTopLevel

Sets a new value for property isTopLevel.

Determines whether sap.m.App is used as a top level control.

Note: When the isTopLevel property set to true, sap.m.App traverses its parent DOM elements and sets their height to 100%.

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
bIsTopLevel boolean true

New value for property isTopLevel

setMobileWebAppCapable

Sets a new value for property mobileWebAppCapable.

Determines whether the App is displayed without address bar when opened from an exported home screen icon on a mobile device.

Keep in mind that if enabled, there is no back button provided by the browser and the app must provide own navigation on all displayed pages to avoid dead ends.

Note The property can be toggled, but it doesn't take effect in real time. It takes the set value at the moment when the home screen icon is exported by the user. For example, if the icon is exported while the property is set to true, the App will have no address bar when opened from that same icon regardless of a changed property value to false at a later time.

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
bMobileWebAppCapable boolean true

New value for property mobileWebAppCapable