rim:loadingScreen element

Supported platforms

BlackBerry OS: 5.0 - 7.0
BlackBerry PlayBook OS: 2.0+
BlackBerry 10 OS: Supported through the <rim:splash> and <param> elements.

Syntax

<rim:loadingScreen backgroundColor="hex color value"
     backgroundImage="filename"
     foregroundImage="filename"
     onRemotePageLoad=["true" | "false"]
     onLocalPageLoad=["true" | "false"]
     onFirstLaunch=["true" | "false"] >
</rim:loadingScreen>

Description

The <rim:loadingScreen> element specifies the properties of the screen that appears when the BlackBerry WebWorks application is loading, before the start page appears and when you navigate between pages. You can determine when the loading screen displays by using the onRemotePageLoad, onLocalPageLoad, and onFirstLaunch attributes. This element is optional.

For BlackBerry smartphone applications running BlackBerry 7 or earlier, when you define an external URL for your application start page, the loading screen might not appear.

Parent elements

<widget>

Child elements

<rim:transitionEffect>

Occurrences

Zero or one

Attributes

You can use the following attributes in this element:

Attribute	Description
`backgroundColor`	The `backgroundColor` attribute specifies the hexadecimal color value to display as the background when the application starts and as the background displayed when you navigate between pages. By default, if you do not specify a color, the background is set to white. This attribute is optional.
`backgroundImage`	The `backgroundImage` attribute specifies the path for a local image to display as the background. You can specify .png or .jpg files. The image is scaled to fit the entire screen. This attribute is optional.
`foregroundImage`	The `foregroundImage` attribute specifies the path for a local image to display, centered on the screen, as the foreground. You can specify .bmp, .jpg, .gif, or .png files for both platforms. For BlackBerry smartphone applications, you can also specify animated .gif and transparent .png files. This attribute is optional.
`onRemotePageLoad`	The `onRemotePageLoad` attribute specifies whether to display the loading screen when the application transitions to a web page from a remote location, including web pages with URLs that begin with `http` or `https`. The value for this attribute is either `true` or `false`. This attribute is optional.
`onLocalPageLoad`	The `onLocalPageLoad` attribute specifies whether to display the loading screen when the application transitions to a local page, including pages with URLs that begin with `local:///` The value for this attribute is either `true` or `false`. This attribute is optional.
`onFirstLaunch`	The `onFirstLaunch` attribute specifies whether to display the loading screen each time you start the application. The value for this attribute is either `true` or `false`. This attribute is optional.

Example: Specifying the background color for the loading screen

<rim:loadingScreen backgroundColor="#FFFFFF" />

Example: Displaying a background image when the application starts

<rim:loadingScreen backgroundImage="background.png"
     onFirstLaunch="true" />

Example: Displaying a background image on transitions from remote pages

You can display a background image when the application starts, and display a background image with a transition effect when the application transitions from a remote page.

<rim:loadingScreen backgroundColor="#FFFFFF"
     backgroundImage="background.png"
     onFirstLaunch="true"
     onRemotePageLoad="true">
   <rim:transitionEffect type="fadeIn" direction="left" />
</rim:loadingScreen>