cordova-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject docs commit: CB-5432: Correct docs for splash screen
Date Mon, 18 Nov 2013 21:46:00 GMT
Updated Branches:
  refs/heads/master e821daa33 -> 02f9e24fb

CB-5432: Correct docs for splash screen

- The config.xml example was malformed. Fix it.
- Add more explanation about using splashscreen on Android.
- Explain that invoking is probably not desired.


Branch: refs/heads/master
Commit: 02f9e24fbfabc1db2645c2cb7fd296d1433ce3ab
Parents: e821daa
Author: Marcel Kinard <>
Authored: Mon Nov 18 16:02:33 2013 -0500
Committer: Marcel Kinard <>
Committed: Mon Nov 18 16:41:31 2013 -0500

 docs/en/edge/config_ref/               | 77 ++++++++++++++++----
 .../cordova/splashscreen/   | 12 +++
 2 files changed, 74 insertions(+), 15 deletions(-)
diff --git a/docs/en/edge/config_ref/ b/docs/en/edge/config_ref/
index 69db995..71d3817 100644
--- a/docs/en/edge/config_ref/
+++ b/docs/en/edge/config_ref/
@@ -105,29 +105,76 @@ The following sections detail how to set up splash screens when
 working with SDKs and related command-line tools described in Platform
-## Splash Screens for the Android Platform 
+Don't forget to install the SplashScreen plugin before trying to use the
+`navigator.splashscreen.hide()` or `` methods.
+## Splash Screens for the Android Platform
 Place [9-patch image](
-files in the Android project's `res/drawable` directory. The size for
-each should be:
+files in the Android project's `platforms/android/res/drawable*` directories.
+The size for each should be:
 - xlarge (xhdpi): at least 960 &times; 720
 - large (hdpi): at least 640 &times; 480
 - medium (mdpi): at least 470 &times; 320
 - small (ldpi): at least 426 &times; 320
-In `config.xml`, add the following preferences:
-    <preference name="splashscreen", "splash" />
-    <preference name="splashScreenDelay", 10000 />
-The first line sets the image to display as the splash screen. If you
+If you want to use
+the default splash screen images provided in Cordova, you'll need to copy the
+png files from `platforms/android/www/res/screen/android` to
+    cd platforms/android/res
+    mkdir drawable-port-ldpi
+    cp -p ../assets/www/res/screen/android/screen-ldpi-portrait.png drawable-port-ldpi/screen.png
+    mkdir drawable-land-ldpi
+    cp -p ../assets/www/res/screen/android/screen-ldpi-landscape.png drawable-land-ldpi/screen.png
+    mkdir drawable-port-mdpi
+    cp -p ../assets/www/res/screen/android/screen-mdpi-portrait.png drawable-port-mdpi/screen.png
+    mkdir drawable-land-mdpi
+    cp -p ../assets/www/res/screen/android/screen-mdpi-landscape.png drawable-land-mdpi/screen.png
+    mkdir drawable-port-hdpi
+    cp -p ../assets/www/res/screen/android/screen-hdpi-portrait.png drawable-port-hdpi/screen.png
+    mkdir drawable-land-hdpi
+    cp -p ../assets/www/res/screen/android/screen-hdpi-landscape.png drawable-land-hdpi/screen.png
+    mkdir drawable-port-xhdpi
+    cp -p ../assets/www/res/screen/android/screen-xhdpi-portrait.png drawable-port-xhdpi/screen.png
+    mkdir drawable-land-xhdpi
+    cp -p ../assets/www/res/screen/android/screen-xhdpi-landscape.png drawable-land-xhdpi/screen.png
+The `drawable` directory names must follow the Android conventions for
+[screen sizes]( and
+[alternate resources](
+In `config.xml` in the project's `www` directory, add the following preferences:
+    <preference name="SplashScreen" value="splash" />
+    <preference name="SplashScreenDelay" value="10000" />
+The first line sets the image to display as the splash screen. This is the
+file name of the png in the `drawable*` directories. If you
 name the image anything other than `splash.png`, you need to modify
-this line.
-The second line sets the delay of how long the splashscreen appears in milliseconds. To dismiss
the splash screen once the app receives the `deviceready` event, call the `navigator.splashscreen.hide()`
-## Splash Screens for the iOS Platform 
+this line. Do not include the filename extension (i.e., `.png`).
+If you want to use the default splash screens provided in
+Cordova as listed above, use the value `screen`.
+The second line sets the default delay of how long the splashscreen appears in
+milliseconds. This should be the maximum expected start time.
+The default value for SplashScreenDelay is 3000 ms.
+Finally, the splash screen should be present only as long as necessary. When
+your app has started and the webview has loaded, your app should hide the
+splash screen so that your main view is visible. Because the app start time
+will vary quite a bit due to a number of factors, it is recommended that your
+app explicitly invoke `navigator.splashscreen.hide()` in the Javascript
+method that responds to the `deviceready` event. Otherwise the splash screen
+will be visible for the SplashScreenDelay value that you configured above.
+This event-driven approach is highly recommended versus having the splash
+screen visible for always a fixed duration.
+## Splash Screens for the iOS Platform
 Copy splash screen images into the iOS project's `Resources/splash`
 directory. Only add those images for the devices you want to support,
@@ -141,7 +188,7 @@ such as iPad or iPhone. The size of each image should be:
 - Default@2x~iphone.png (640x960 pixels)
 - Default~iphone.png (320x480 pixels)
-## Splash Screens for the BlackBerry 10 Platform 
+## Splash Screens for the BlackBerry 10 Platform
 Copy splash screen images into the project's `res/screen/blackberry10`
 directory. The file names should be:
diff --git a/docs/en/edge/cordova/splashscreen/ b/docs/en/edge/cordova/splashscreen/
index b204f3e..c5d11e7 100644
--- a/docs/en/edge/cordova/splashscreen/
+++ b/docs/en/edge/cordova/splashscreen/
@@ -64,3 +64,15 @@ This method displays the application's splash screen.
+Your application can not call `` until
+the app has started and the `deviceready` event has fired. But since
+typically the
+splash screen is meant to be visible before your app has started, that would
+seem to defeat the purpose of the splash screen.
+Providing some configuration in `config.xml` will automatically `show` the
+splash screen immediately after your app launch and before it has fully
+started and received the `deviceready` event. See Icons and Splash Screens
+for more information on doing this configuration. For this reason, it is
+unlikely you need to call `` to make the
+splash screen visible for app startup.

View raw message