+ Figure 1. You can make your web content available to +users in two ways: in a traditional web browser and in an Android application, by +including a WebView in the layout.
+For more information about how to use viewport meta data for Android-powered devices, read Targetting Android Devices.
+href="{@docRoot}guide/webapps/targeting.html">Targeting Screens from Web Apps. diff --git a/docs/html/guide/webapps/debugging.jd b/docs/html/guide/webapps/debugging.jd index 098e17c0ebc09..ee4b723c246b1 100644 --- a/docs/html/guide/webapps/debugging.jd +++ b/docs/html/guide/webapps/debugging.jd @@ -86,7 +86,7 @@ expect from other web browsers.If you've implemented a custom {@link android.webkit.WebView} in your application, all the same console APIs are supported when debugging your web page in WebView. On Android 1.6 and lower, console messages are automatically sent to logcat with the -"WebCore" logging tag. If you're targetting Android 2.1 (API Level 7) or higher, then you must +"WebCore" logging tag. If you're targeting Android 2.1 (API Level 7) or higher, then you must provide a {@link android.webkit.WebChromeClient} that implements the {@link android.webkit.WebChromeClient#onConsoleMessage(String,int,String) onConsoleMessage()} callback method, in order for console messages to appear in logcat.
diff --git a/docs/html/guide/webapps/index.jd b/docs/html/guide/webapps/index.jd new file mode 100644 index 0000000000000..280380fe193ad --- /dev/null +++ b/docs/html/guide/webapps/index.jd @@ -0,0 +1,71 @@ +page.title=Web Apps Overview +@jd:body + +
+ Figure 1. You can make your web content available to +users in two ways: in a traditional web browser and in an Android application, by +including a WebView in the layout.
+There are essentially two ways to deliver an application on Android: as a +client-side application (developed using the Android SDK and installed on user devices as an {@code +.apk}) or as a web application (developed using web standards and accessed through a web +browser—there's nothing to install on user devices).
+ +The approach you choose for your application could depend on several factors, but Android makes +the decision to develop a web application easier by providing:
+Thus, your decision to develop a web application for Android can exclude consideration for +screen support, because it's already easy to make your web pages look good on all types of screens +powered by Android.
+ +Another great feature of Android is that you don't have to build your application purely on +the client or purely on the web. You can mix the two together by developing a client-side Android +application that embeds some web pages (using a {@link android.webkit.WebView} in your Android +application layout). Figure 1 visualizes how you can provide access to your web pages from either +a web browser or your Android application. However, you shouldn't develop an Android +application simply as a means to launch your web site. Rather, the web pages you embed in your +Android application should be designed especially for that environment. You can even define an +interface between your Android application and your web pages that allows JavaScript in the web +pages to call upon APIs in your Android application—providing Android APIs to your web-based +application.
+ +Since Android 1.0, {@link android.webkit.WebView} has been available for Android +applications to embed web content in their layout and bind JavaScript to Android APIs. After +Android added support for more screen densities (adding support for high and low-density +screens), Android 2.0 added features to the WebKit framework to allow web pages to specify +viewport properties and query the screen density in order to modify styles +and image assets, as mentioned above. Because these features are a part of Android's WebKit +framework, both the Android Browser (the default web browser provided with the platform) and +{@link android.webkit.WebView} support the same viewport and screen density features.
+ +To develop a web application for Android-powered devices, you should read the +following documents:
+ +If you're developing a web application for Android or redesigning one for mobile devices, you -should account for some factors that affect the way the Android Browser renders your web page by -default. There are two fundamental factors that you should account for:
+should carefully consider how your web pages appear on different kinds of screens. Because +Android is available on devices with different types of screens, you should account for some factors +that affect the way your web pages appear on Android devices. + +Note: The features described in this document are supported +by the Android Browser application (provided with the default Android platform) and {@link +android.webkit.WebView} (the framework view widget for displaying web pages), on Android 2.0 and +greater. Third-party web browsers running on Android might not support these features for +controlling the viewport size and screen densities.
+ +When targeting your web pages for Android devices, there are two fundamental factors that you +should account for:
However, the user can also disable overview mode in the -Browser settings, so you should not assume that your page will load in overview mode. You -should instead customize the viewport size and/or scale as appropriate for your page.
+page, if at all. The user can also disable overview mode in the +Browser settings, so you should never assume that your page will load in overview mode. You +should instead customize the viewport size and/or scale as appropriate for your page. +However, when your page is rendered in a {@link android.webkit.WebView}, the page loads at +full zoom (not in "overview mode"). That is, it appears at the default size for the page, +instead of zoomed out. (This is also how the page appears if the user disables overview +mode.)
To provide the best visual representation on all screen densities, you should control how scaling occurs by providing viewport metadata about your web page's target screen density and providing alternative graphics for different screen densities, which you can apply to different screens using CSS or JavaScript.
The rest of this document describes how you can account for these effects, and how to target -your web page for specific screen configurations.
- -Note: The features described in this document are supported -by the Android Browser application on Android 2.0 and greater. Third-party web browsers running on -Android might not support these techniques for controlling the viewport size and targetting -screen densities.
+The rest of this document describes how you can account for these effects and provide a good +design on multiple types of screens.
The viewport is the area in which the Android Browser -draws a web page. Although the viewport's visible area matches the size of the screen, +
The viewport is the area in which your web page is drawn. Although the viewport's visible area +matches the size of the screen, the viewport has its own dimensions that determine the number of pixels available to a web page. That is, the number of pixels available to a web page before it exceeds the screen area is defined by the dimensions of the viewport, @@ -116,34 +126,34 @@ accepted values are.
- Figure 1. A web page with no viewport metadata and an -image that's 320 pixels wide (the viewport is 800 pixels wide, by default).
+Figure 1. A web page with an image that's 320 pixels +wide, in the Android Browser when there is no viewport metadata set (with "overview mode" +enabled, the viewport is 800 pixels wide, by default).
- Figure 2. A web page with viewport {@code width=400} -(the image in the web page is 320 pixels wide).
+Figure 2. A web page with viewport {@code width=400} and +"overview mode" enabled (the image in the web page is 320 pixels wide).
Viewport's {@code height} and {@code width} properties allow you to specify the size of the -viewport (the number of pixels available to the web page before it goes off screen). By default, the -Android Browser's minimum viewport width is 800 pixels, so if your web -page specifies its size to be 320 pixels wide, then your page renders smaller than the visible -screen (even if the physical screen is 320 pixels wide, because the viewport simulates a -drawable area that's 800 pixels wide), as shown in figure 1. So, you should explicitly define the -viewport {@code width} to match the width for which you have designed your web page.
+viewport (the number of pixels available to the web page before it goes off screen). -Note: Width values that are greater than 10,000 are ignored and -values less than (or equal to) 320 result in a value equal to the device-width. Height values that -are greater then 10,000 or less than 200 are also ignored.
+As mentioned in the introduction above, the Android Browser loads pages in "overview mode" by +default (unless disable by the user), which sets the minimum viewport width to 800 pixels. So, if +your web page specifies its size to be 320 pixels wide, then your page appears smaller than the +visible screen (even if the physical screen is 320 pixels wide, because the viewport simulates a +drawable area that's 800 pixels wide), as shown in figure 1. To avoid this effect, you should +explicitly define the viewport {@code width} to match the width for which you have designed your web +page.
For example, if your web page is designed to be exactly 320 pixels wide, then you might -want to specify that for the viewport width:
+want to specify that size for the viewport width:<meta name="viewport" content="width=320" /> @@ -152,18 +162,22 @@ want to specify that for the viewport width:In this case, your web page exactly fits the screen width, because the web page width and viewport width are the same.
+Note: Width values that are greater than 10,000 are ignored and +values less than (or equal to) 320 result in a value equal to the device-width (discussed below). +Height values that are greater then 10,000 or less than 200 are also ignored.
+To demonstrate how this property affects the size of -your web page, figure 2 shows a web page that contains an image that's 320 pixels wide, but with the -viewport width set to 400.
+your web page, figure 2 shows a web page that contains an image that's 320 pixels +wide, but with the viewport width set to 400.Note: If you set the viewport width to match your web page width -and the device screen width does not match those dimensions, then the web page +and the device's screen width does not match those dimensions, then the web page still fits the screen even if the device has a high or low-density screen, because the -Android Browser scales web pages to match the perceived size on a medium-density -screen, by default (as you can see in figure 2, when comparing the hdpi device to the mdpi device). -Screen densities are discussed more in Defining the viewport target -density.
+Android Browser and {@link android.webkit.WebView} scale web pages to match the perceived size on a +medium-density screen, by default (as you can see in figure 2, when comparing the hdpi device to the +mdpi device). Screen densities are discussed more in Defining the +viewport target density.Automatic sizing
@@ -254,11 +268,12 @@ density.Defining the viewport target density
-The density of a device's screen is based on the screen resolution. There are three screen +
The density of a device's screen is based on the screen resolution, as defined by the number of +dots per inch (dpi). There are three screen density categories supported by Android: low (ldpi), medium (mdpi), and high (mdpi). A screen with low density has fewer available pixels per inch, whereas a screen with high density has more -pixels per inch (compared to a medium density screen). The Android Browser targets a medium density -screen by default.
+pixels per inch (compared to a medium density screen). The Android Browser and {@link +android.webkit.WebView} target a medium density screen by default.@@ -269,11 +284,12 @@ width=device-width} and {@code target-densitydpi=device-dpi}.Because the default target density is medium, when users have a device with a low or high density -screen, the Android Browser scales web pages (effectively zooms the pages) so they display at a -size that matches the perceived appearance on a medium density screen. Specifically, the Android -Browser applies approximately 1.5x scaling to web pages on a high density screen -(because its screen pixels are smaller) and approximately 0.75x scaling to pages on a low density -screen (because its screen pixels are bigger).
+screen, the Android Browser and {@link android.webkit.WebView} scale web pages (effectively zoom +the pages) so they display at a +size that matches the perceived appearance on a medium density screen. More specifically, the +Android Browser and {@link android.webkit.WebView} apply approximately 1.5x scaling to web pages +on a high density screen (because its screen pixels are smaller) and approximately 0.75x scaling to +pages on a low density screen (because its screen pixels are bigger).Due to this default scaling, figures 1, 2, and 3 show the example web page at the same physical size on both the high and medium density device (the high-density device shows the @@ -299,10 +315,10 @@ as appropriate. be within the range 70–400.
-For example, to prevent the Android Browser from scaling of your web page for different screen -densities, set -the {@code target-densitydpi} viewport property to {@code device-dpi}. When you do, the Android -Browser does not scale the page and, instead, displays your web page to match the current screen +
For example, to prevent the Android Browser and {@link android.webkit.WebView} from scaling +your web page for different screen densities, set +the {@code target-densitydpi} viewport property to {@code device-dpi}. When you do, the page is +not scaled. Instead, the page is displayed at a size that matches the current screen's density. In this case, you should also define the viewport width to match the device width, so your web page naturally fits the screen size. For example:
@@ -319,9 +335,10 @@ different densities, with CSS or with JavaScript.) -Targetting Device Density with CSS
+Targeting Device Density with CSS
-The Android Browser supports a CSS media feature that allows you to create styles for specific +
The Android Browser and {@link android.webkit.WebView} support a CSS media feature that allows +you to create styles for specific screen densities—the
<meta name="viewport" content="target-densitydpi=device-dpi, width=device-width" /> --webkit-device-pixel-ratioCSS media feature. The value you apply to this feature should be either "0.75", "1", or "1.5", to indicate that the styles are for devices with low density, medium density, @@ -378,8 +395,9 @@ density match the device. That is:This way, the Android Browser does not perform scaling on your web page and the viewport width -matches the screen width exactly. On its own, these viewport properties create results shown in +
This way, the Android Browser and {@link android.webkit.WebView} do not perform scaling on your +web page and the viewport width +matches the screen width exactly. On their own, these viewport properties create results shown in figure 4. However, by adding some custom CSS using the {@code -webkit-device-pixel-ratio} media feature, you can apply different styles. For example, figure 5 shows a web page with these viewport properties and also some CSS added that applies a high-resolution image for high-density @@ -387,16 +405,18 @@ screens.
-Targetting Device Density with JavaScript
+Targeting Device Density with JavaScript
-The Android Browser supports a DOM property that allows you to query the density of the current +
The Android Browser and {@link android.webkit.WebView} support a DOM property that allows you to +query the density of the current device—the
diff --git a/docs/html/images/webapps/compare-default.png b/docs/html/images/webapps/compare-default.png index 9495a0526f566..129cb3397dd1c 100644 Binary files a/docs/html/images/webapps/compare-default.png and b/docs/html/images/webapps/compare-default.png differ diff --git a/docs/html/images/webapps/compare-initialscale-devicedpi.png b/docs/html/images/webapps/compare-initialscale-devicedpi.png index 6bb758a63f795..3b0fb6a89bf2f 100644 Binary files a/docs/html/images/webapps/compare-initialscale-devicedpi.png and b/docs/html/images/webapps/compare-initialscale-devicedpi.png differ diff --git a/docs/html/images/webapps/compare-initialscale.png b/docs/html/images/webapps/compare-initialscale.png index 2232d5bcf3189..09314bbaac876 100644 Binary files a/docs/html/images/webapps/compare-initialscale.png and b/docs/html/images/webapps/compare-initialscale.png differ diff --git a/docs/html/images/webapps/compare-width-devicedpi-css.png b/docs/html/images/webapps/compare-width-devicedpi-css.png index bb4ab3102a4a9..3efa3860b78ed 100644 Binary files a/docs/html/images/webapps/compare-width-devicedpi-css.png and b/docs/html/images/webapps/compare-width-devicedpi-css.png differ diff --git a/docs/html/images/webapps/compare-width400.png b/docs/html/images/webapps/compare-width400.png index 669a2346b061c..d65438157d964 100644 Binary files a/docs/html/images/webapps/compare-width400.png and b/docs/html/images/webapps/compare-width400.png differ diff --git a/docs/html/images/webapps/webapps.png b/docs/html/images/webapps/webapps.png new file mode 100644 index 0000000000000..6ad6205303456 Binary files /dev/null and b/docs/html/images/webapps/webapps.png differwindow.devicePixelRatioDOM property. The value of this property specifies the scaling factor used for the current device. For example, if the value ofwindow.devicePixelRatiois "1.0", then the device is considered a medium density device and no scaling is applied by default; if the value is "1.5", then the device is considered a high density device and the page is scaled 1.5x by default; if the value is "0.75", then the device is considered a low density device and the page is scaled -0.75x by default. Of course, the scaling that the Android Browser applies is based on the web page's +0.75x by default. Of course, the scaling that the Android Browser and {@link android.webkit.WebView} +apply is based on the web page's target density—as described in the section about Defining the viewport target density, the default target is medium-density, but you can change the target to affect how your web page is scaled for different screen densities.