cordova-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From marc...@apache.org
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 splashscreen.show() is probably not desired.


Project: http://git-wip-us.apache.org/repos/asf/cordova-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/cordova-docs/commit/02f9e24f
Tree: http://git-wip-us.apache.org/repos/asf/cordova-docs/tree/02f9e24f
Diff: http://git-wip-us.apache.org/repos/asf/cordova-docs/diff/02f9e24f

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

----------------------------------------------------------------------
 docs/en/edge/config_ref/images.md               | 77 ++++++++++++++++----
 .../cordova/splashscreen/splashscreen.show.md   | 12 +++
 2 files changed, 74 insertions(+), 15 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/02f9e24f/docs/en/edge/config_ref/images.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/config_ref/images.md b/docs/en/edge/config_ref/images.md
index 69db995..71d3817 100644
--- a/docs/en/edge/config_ref/images.md
+++ b/docs/en/edge/config_ref/images.md
@@ -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
 Guides.
 
-## Splash Screens for the Android Platform 
+Don't forget to install the SplashScreen plugin before trying to use the
+`navigator.splashscreen.hide()` or `navigator.splashscreen.show()` methods.
+
+## Splash Screens for the Android Platform
 
 Place [9-patch image](https://developer.android.com/tools/help/draw9patch.html)
-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
+`platforms/android/res/drawable*/`:
+
+    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
+supporting
+[screen sizes](http://developer.android.com/guide/practices/screens_support.html) and
+[alternate resources](http://developer.android.com/guide/topics/resources/providing-resources.html#AlternativeResources).
+
+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()`
method.
-
-## 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:

http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/02f9e24f/docs/en/edge/cordova/splashscreen/splashscreen.show.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/cordova/splashscreen/splashscreen.show.md b/docs/en/edge/cordova/splashscreen/splashscreen.show.md
index b204f3e..c5d11e7 100644
--- a/docs/en/edge/cordova/splashscreen/splashscreen.show.md
+++ b/docs/en/edge/cordova/splashscreen/splashscreen.show.md
@@ -64,3 +64,15 @@ This method displays the application's splash screen.
         <h1>Example</h1>
       </body>
     </html>
+
+Your application can not call `navigator.splashscreen.show()` 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 `navigator.splashscreen.show()` to make the
+splash screen visible for app startup.


Mime
View raw message