The root element of a UI5 mobile app.
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.
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 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 |
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. |
|
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. |
|
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. |
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). |
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 Note: When the |
mobileWebAppCapable | boolean | true | Determines whether the 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 |
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 Note: The following scenarios are possible, depending on where the focus was before navigation to a new page:
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. |
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 |
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 |
Event | Description |
---|---|
orientationChange |
Fired when the orientation (portrait/landscape) of the device is changed. |
Fired when the orientation (portrait/landscape) of the device is changed.
Param | Type | Description |
---|---|---|
oControlEvent | sap.ui.base.Event | |
getSource | sap.ui.base.EventProvider | |
getParameters | object | |
landscape | boolean |
Whether the device is in landscape orientation. |
Method | Description |
---|---|
attachOrientationChange |
Attaches event handler When called, the context of the event handler (its 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 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
|
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 |
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 |
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 Note: When the Default value is |
sap.m.App.getMetadata |
Returns a metadata object for class sap.m.App. |
getMobileWebAppCapable |
Gets current value of property mobileWebAppCapable. Determines whether the 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 Default value is |
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 |
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 |
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 Default value is |
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 Default value is |
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 |
setIsTopLevel |
Sets a new value for property isTopLevel. Determines whether Note: When the When called with a value of Default value is |
setMobileWebAppCapable |
Sets a new value for property mobileWebAppCapable. Determines whether the 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 When called with a value of Default value is |
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.
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 |
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.
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 |
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 |
Fires event orientationChange to attached listeners.
Param | Type | DefaultValue | Description |
---|---|---|---|
mParameters | object |
Parameters to pass along with the event |
|
landscape | boolean |
Whether the device is in landscape orientation. |
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.
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.
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
.
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
.
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".
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
.
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
.
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 |
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 |
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 |
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 |
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 |
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 |
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 |