rim:loadingScreen element

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 app 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.

When you define an external URL for your app start page, the loading screen might not appear.

Comptibility note

If you port your app to BlackBerry 10, you will need to use the <rim:splash> and <param> elements instead.

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 app 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.

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 app 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 app 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 app. 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 app 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 app starts, and display a background image with a transition effect when the app transitions from a remote page.

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

Last modified: 2013-10-02