drgreen/android_frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

am b00f26a1: Merge "update web app docs to remove target-densitydpi, remove the overview page, remove a bunch of stuff from the doc about screens and refer to external docs instead, and add tips about debugging on 4.4 w/ dev tools." into klp-docs

Browse Source 
* commit 'b00f26a1722e3a31dca48bf47568ee54686dba30':
  update web app docs to remove target-densitydpi, remove the overview page, remove a bunch of stuff from the doc about screens and refer to external docs instead, and add tips about debugging on 4.4 w/ dev tools.
This commit is contained in:
Scott Main
2013-11-07 05:19:14 +00:00
committed by Android Git Automerger
parent fa85c91220 b00f26a172
commit 3a8228fc51
10 changed files with 159 additions and 429 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
docs/html/guide/guide_toc.cs
View File

@ -490,11 +490,8 @@
<span class="en">Web Apps</span>
</a></div>
<ul>
<li><a href="<?cs var:toroot ?>guide/webapps/overview.html">
<span class="en">Overview</span>
</a></li>
<li><a href="<?cs var:toroot ?>guide/webapps/targeting.html">
<span class="en">Targeting Screens from Web Apps</span>
<span class="en">Supporting Different Screens in Web Apps</span>
</a></li>
<li><a href="<?cs var:toroot ?>guide/webapps/webview.html">
<span class="en">Building Web Apps in WebView</span>

18
docs/html/guide/webapps/best-practices.jd
View File

@ -1,6 +1,24 @@
page.title=Best Practices for Web Apps
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>See also</h2>
<ul>
<li><a href="https://developers.google.com/chrome/mobile/docs/webview/pixelperfect"
>Pixel-Perfect UI in the WebView</a></li>
<li><a href="http://www.html5rocks.com/en/mobile/responsivedesign/" class="external-link">Creating
a Mobile-First Responsive Web Design</a></li>
<li><a href="http://www.html5rocks.com/en/mobile/high-dpi/" class="external-link">High
DPI Images for Variable Pixel Densities</a></li>
</ul>
</div>
</div>
<style>
.bold li {
font-weight:bold;

49
docs/html/guide/webapps/debugging.jd
View File

@ -18,19 +18,29 @@ messages</li>
<h2>See also</h2>
<ol>
<li><a class="external-link"
href="https://developers.google.com/chrome-developer-tools/docs/remote-debugging">Remote
Debugging on Android</a></li>
<li><a href="{@docRoot}tools/debugging/index.html">Debugging</a></li>
</ol>
</div>
</div>
<p>If you're developing a web application for Android, you can debug your JavaScript
using the {@code console} JavaScript APIs, which output messages to logcat. If you're familiar with
<p>If you are testing your web app with a device running Android 4.4 or higher,
you can remotely debug your web pages in {@link android.webkit.WebView} with
Chrome Developer Tools, while continuing to support older versions of Android.
For more information, see <a class="external-link"
href="https://developers.google.com/chrome-developer-tools/docs/remote-debugging">Remote
Debugging on Android</a>.</p>
<p>If you don't have a device running Android 4.4 or higher, you can debug your JavaScript using the
{@code console} JavaScript APIs and view the output messages to logcat. If you're familiar with
debugging web pages with Firebug or Web Inspector, then you're probably familiar
with using {@code console} (such as {@code console.log()}). Android's WebKit framework supports most
of the same APIs, so you can receive logs from your web page when debugging in Android's Browser
or in your own {@link android.webkit.WebView}.</p>
or in your own {@link android.webkit.WebView}. This document describes how to use the
console APIs for debugging.</p>
<h2 id="Browser">Using Console APIs in the Android Browser</h2>
@ -83,28 +93,17 @@ expect from other web browsers.</p>
<h2 id="WebView">Using Console APIs in WebView</h2>
<p>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 targeting Android 2.1 (API Level 7) or higher, then you must
<p>All the console APIs shown above are also
supported when debugging in {@link android.webkit.WebView}.
If you're targeting Android 2.1 (API level 7) and higher, 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.</p>
<p>Additionally, the {@link
android.webkit.WebChromeClient#onConsoleMessage(String,int,String)} method introduced in API
Level 7 has been deprecated in favor of {@link
android.webkit.WebChromeClient#onConsoleMessage(ConsoleMessage)} in API Level 8.</p>
<p>Whether you're developing for Android 2.1 (API Level 7) or Android 2.2 (API Level 8 or
greater), you must implement {@link android.webkit.WebChromeClient} and override the appropriate
{@link
android.webkit.WebChromeClient#onConsoleMessage(String,int,String) onConsoleMessage()} callback
method. Then, apply the {@link android.webkit.WebChromeClient} to your {@link
onConsoleMessage()} method in order for console messages to appear in logcat.
Then, apply the {@link android.webkit.WebChromeClient} to your {@link
android.webkit.WebView} with {@link android.webkit.WebView#setWebChromeClient(WebChromeClient)
setWebChromeClient()}.
<p>Using API Level 7, this is how your code for {@link
<p>For example, to support API level 7, this is how your code for {@link
android.webkit.WebChromeClient#onConsoleMessage(String,int,String)} might look:</p>
<pre>
@ -118,8 +117,8 @@ myWebView.setWebChromeClient(new WebChromeClient() {
});
</pre>
<p>With API Level 8 or greater, your code for {@link
android.webkit.WebChromeClient#onConsoleMessage(ConsoleMessage)} might look like this:</p>
<p>However, if your lowest supported version is API level 8 or higher, you should instead
implement {@link android.webkit.WebChromeClient#onConsoleMessage(ConsoleMessage)}. For example:</p>
<pre>
WebView myWebView = (WebView) findViewById(R.id.webview);
@ -134,8 +133,8 @@ myWebView.setWebChromeClient(new WebChromeClient() {
</pre>
<p>The {@link android.webkit.ConsoleMessage} also includes a {@link
android.webkit.ConsoleMessage.MessageLevel MessageLevel} to indicate the type of console message
being delivered. You can query the message level with {@link
android.webkit.ConsoleMessage.MessageLevel MessageLevel} object to indicate the type of console
message being delivered. You can query the message level with {@link
android.webkit.ConsoleMessage#messageLevel()} to determine the severity of the message, then
use the appropriate {@link android.util.Log} method or take other appropriate actions.</p>

52
docs/html/guide/webapps/index.jd
View File

@ -1,16 +1,50 @@
page.title=Web Apps
page.landing=true
page.landing.intro=Android has always been about connectivity and providing a great web browsing experience, so building your app with web technologies can be a great opportunity. Not only can you build an app on the web and still optimize your designs for Android's various screen sizes and densities, but you can also embed web-based content into your Android app using WebView.
page.landing.image=
@jd:body
<div class="landing-docs">
<div class="figure" style="width:327px">
<img src="{@docRoot}images/webapps/webapps.png" alt="" />
<p class="img-caption"><strong>Figure 1.</strong> 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.</p>
</div>
<div class="col-6">
</div>
<p>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 in an APK)
or as a web application (developed using web standards and accessed through a web
browser&mdash;there's nothing to install on user devices).</p>
<div class="col-6">
</div>
<p>If you chose to provide a web-based app for Android-powered devices, you can rest
assured that major web browsers for Android (and the {@link android.webkit.WebView} framework)
allow you to specify viewport and style properties that make your web pages appear at the proper
size and scale on all screen configurations.</p>
</div>
<p>Figure 1 illustrates how you can provide access to your web pages from either
a web browser or your your own Android app. However, you shouldn't develop an Android
app simply as a means to view your web site. Rather, the web pages you embed in your
Android app 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&mdash;providing Android APIs to your web-based
application.</p>
<p>To start developing web pages for Android-powered devices, see the following documents:</p>
<dl>
<dt><a href="{@docRoot}guide/webapps/targeting.html"><strong>Supporting Different Screens from Web
Apps</strong></a></dt>
<dd>How to properly size your web app on Android-powered devices and support
multiple screen densities. The information in this document is important if you're building a web
application that you at least expect to be available on Android-powered devices (which you should
assume for anything you publish on the web), but especially if you're targeting mobile devices
or using {@link android.webkit.WebView}.</dd>
<dt><a href="{@docRoot}guide/webapps/webview.html"><strong>Building Web Apps in
WebView</strong></a></dt>
<dd>How to embed web pages into your Android application using {@link
android.webkit.WebView} and bind JavaScript to Android APIs.</dd>
<dt><a href="{@docRoot}guide/webapps/debugging.html"><strong>Debugging Web Apps</strong></a></dt>
<dd>How to debug web apps using JavaScript Console APIs.</dd>
<dt><a href="{@docRoot}guide/webapps/best-practices.html"><strong>Best Practices for Web
Apps</strong></a></dt>
<dd>A list of practices you should follow, in order to provide an effective web application on
Android-powered devices.</dd>
</dl>

71
docs/html/guide/webapps/overview.jd
View File

@ -1,71 +0,0 @@
page.title=Web Apps Overview
@jd:body
<div class="figure" style="width:327px">
<img src="{@docRoot}images/webapps/webapps.png" alt="" />
<p class="img-caption"><strong>Figure 1.</strong> 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.</p>
</div>
<p>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&mdash;there's nothing to install on user devices).</p>
<p>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:</p>
<ul>
<li>Support for viewport properties that allow you to properly size your web application
based on the screen size</li>
<li>CSS and JavaScript features that allow you to provide different styles and images
based on the screen's pixel density (screen resolution)</li>
</ul>
<p>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.</p>
<p>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&mdash;providing Android APIs to your web-based
application.</p>
<p>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.</p>
<p>To develop a web application for Android-powered devices, you should read the
following documents:</p>
<dl>
<dt><a href="{@docRoot}guide/webapps/targeting.html"><strong>Targeting Screens from Web
Apps</strong></a></dt>
<dd>How to properly size your web app on Android-powered devices and support
multiple screen densities. The information in this document is important if you're building a web
application that you at least expect to be available on Android-powered devices (which you should
assume for anything you publish on the web), but especially if you're targeting mobile devices
or using {@link android.webkit.WebView}.</dd>
<dt><a href="{@docRoot}guide/webapps/webview.html"><strong>Building Web Apps in
WebView</strong></a></dt>
<dd>How to embed web pages into your Android application using {@link android.webkit.WebView} and
bind JavaScript to Android APIs.</dd>
<dt><a href="{@docRoot}guide/webapps/debugging.html"><strong>Debugging Web Apps</strong></a></dt>
<dd>How to debug web apps using JavaScript Console APIs.</dd>
<dt><a href="{@docRoot}guide/webapps/best-practices.html"><strong>Best Practices for Web
Apps</strong></a></dt>
<dd>A list of practices you should follow, in order to provide an effective web application on
Android-powered devices.</dd>
</dl>

392
docs/html/guide/webapps/targeting.jd
View File

@ -1,16 +1,8 @@
page.title=Targeting Screens from Web Apps
page.title=Supporting Different Screens in Web Apps
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>Quickview</h2>
<ul>
<li>You can target your web page for different screens using viewport metadata, CSS, and
JavaScript</li>
<li>Techniques in this document work for Android 2.0 and greater, and for web pages rendered
in the default Android Browser and in a {@link android.webkit.WebView}</li>
</ul>
<h2>In this document</h2>
<ol>
<li><a href="#Metadata">Using Viewport Metadata</a>
@ -24,78 +16,88 @@ in the default Android Browser and in a {@link android.webkit.WebView}</li>
<li><a href="#DensityJS">targeting Device Density with JavaScript</a></li>
</ol>
<h2>See also</h2>
<ul>
<li><a href="https://developers.google.com/chrome/mobile/docs/webview/pixelperfect"
>Pixel-Perfect UI in the WebView</a></li>
<li><a href="http://www.html5rocks.com/en/mobile/responsivedesign/" class="external-link">Creating
a Mobile-First Responsive Web Design</a></li>
<li><a href="http://www.html5rocks.com/en/mobile/high-dpi/" class="external-link">High
DPI Images for Variable Pixel Densities</a></li>
</ul>
</div>
</div>
<p>If you're developing a web application for Android or redesigning one for mobile devices, you
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.</p>
<p>Because Android is available on devices with a variety of screen sizes and pixel densities, you
should account for these factors in your web design so your web pages always appear at the
appropriate size.</p>
<p class="note"><strong>Note:</strong> 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.</p>
<p>When targeting your web pages for Android devices, there are two fundamental factors that you
<p>When targeting your web pages for Android devices, there are two major factors that you
should account for:</p>
<dl>
<dt>The size of the viewport and scale of the web page</dt>
<dd>When the Android Browser loads a web page, the default behavior is to load the
page in "overview mode," which provides a zoomed-out perspective of the web page. You can override
this behavior for your web page by defining the default dimensions of the viewport or the initial
scale of the viewport. You can also control how much the user can zoom in and out of your web
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.</p>
<p>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.)</p></dd>
<dt><a href="#Viewport">The viewport</a></dt>
<dd>The viewport is the rectangular area that provides a drawable region for your web page.
You can specify several viewport properties, such as its size and initial scale. Most important
is the view port width, which defines the total number of horizontal pixels available from the web page's point of
view (the number of CSS pixels available).
</dd>
<dt><a href="#DensityCSS">The screen density</a></dt>
<dd>The {@link android.webkit.WebView} class and most web browsers on Android convert your CSS
pixel values to density-independent pixel values, so your web page appears at the same perceivable
size as a medium-density screen (about 160dpi). However, if graphics are an important element of
your web design, you should pay close attention to the scaling that occurs on different densities,
because a 300px-wide image on a 320dpi screen will be scaled up (using more physical pixels per CSS
pixel), which can produce artifacts (blurring and pixelation).</dd>
<dt>The device's screen density</dt>
<dd>The screen density (the number of pixels per inch) on an Android-powered device affects
the resolution and size at which a web page is displayed. (There are three screen density
categories: low, medium, and high.) The Android Browser and {@link android.webkit.WebView}
compensate for variations in the screen
density by scaling a web page so that all devices display the web page at the same perceivable size
as a medium-density screen. If graphics are an important element of your web design, you
should pay close attention to the scaling that occurs on different densities, because image scaling
can produce artifacts (blurring and pixelation).
<p>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.</p></dd>
</dl>
<p>The rest of this document describes how you can account for these effects and provide a good
design on multiple types of screens.</p>
<h2 id="Metadata">Using Viewport Metadata</h2>
<p>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,
not the dimensions of the device screen. For example, although a device screen might have a width of
480 pixels, the viewport can have a width of 800 pixels, so that a web page designed to be 800
pixels wide is completely visible on the screen.</p>
<h2 id="Viewport">Specifying Viewport Properties</h2>
<p>You can define properties of the viewport for your web page using the {@code "viewport"}
property in an HTML {@code &lt;meta&gt;} tag (which must
be placed in your document {@code &lt;head&gt;}). You can define multiple viewport properties in the
{@code &lt;meta&gt;} tag's {@code content} attribute. For example, you can define the height and
width of the viewport, the initial scale of the page, and the target screen density.
Each viewport property in the {@code content} attribute must be separated by a comma.</p>
<p>The viewport is the area in which your web page is drawn. Although the viewport's total visible
area matches the size of the screen when zoomed all the way out, the viewport has its own pixel
dimensions that it makes available to a web page. For example, although a device screen might
have physical a width
of 480 pixels, the viewport can have a width of 800 pixels. This allows a web page designed at 800
pixels wide to be completely visible on the screen when the viewport scale is 1.0. Most web browsers on
Android (including Chrome) set the viewport to a large size by default (known as "wide viewport
mode" at about 980px wide). Many browsers also zoom out as far as possible, by default, to
show the full viewport width (known as "overview mode").</p>
<p>For example, the following snippet from an HTML document specifies that the viewport width
should exactly match the device screen width and that the ability to zoom should be disabled:</p>
<p class="note"><strong>Note:</strong>
When your page is rendered in a {@link android.webkit.WebView}, it does not use wide viewport mode
(the page appears at full zoom) by default. You can enable wide viewport mode
with {@link android.webkit.WebSettings#setUseWideViewPort setUseWideViewPort()}.</p>
<p>You can define properties of the viewport for your web page, such as the width and initial zoom
level, using the {@code &lt;meta name="viewport" ...>} tag in your document
{@code &lt;head&gt;}.</p>
<p>The following syntax shows all of the
supported viewport properties and the types of values accepted by each one:</p>
<pre>
&lt;meta name="viewport"
content="
<b>height</b> = [<em>pixel_value</em> | "device-height"] ,
<b>width</b> = [<em>pixel_value</em> | "device-width"] ,
<b>initial-scale</b> = <em>float_value</em> ,
<b>minimum-scale</b> = <em>float_value</em> ,
<b>maximum-scale</b> = <em>float_value</em> ,
<b>user-scalable</b> = ["yes" | "no"]
" /&gt;
</pre>
<p>For example, the following {@code &lt;meta&gt;} tag specifies that the viewport width
should exactly match the device screen's width and that the ability to zoom should be disabled:</p>
<pre>
&lt;head&gt;
@ -104,235 +106,17 @@ should exactly match the device screen width and that the ability to zoom should
&lt;/head&gt;
</pre>
<p>That's an example of just two viewport properties. The following syntax shows all of the
supported viewport properties and the general types of values accepted by each one:</p>
<pre>
&lt;meta name="viewport"
content="
<b>height</b> = [<em>pixel_value</em> | device-height] ,
<b>width</b> = [<em>pixel_value</em> | device-width ] ,
<b>initial-scale</b> = <em>float_value</em> ,
<b>minimum-scale</b> = <em>float_value</em> ,
<b>maximum-scale</b> = <em>float_value</em> ,
<b>user-scalable</b> = [yes | no] ,
<b>target-densitydpi</b> = [<em>dpi_value</em> | device-dpi |
high-dpi | medium-dpi | low-dpi]
" /&gt;
</pre>
<p>When optimizing your site for mobile devices, you should usually set the width to
{@code "device-width"} so the size fits exactly on all devices, then use CSS media queries to
flexibly adapt layouts to suit different screen sizes.
<p>The following sections discuss how to use each of these viewport properties and exactly what the
accepted values are.</p>
<div class="figure" style="width:300px">
<img src="{@docRoot}images/webapps/compare-default.png" alt="" height="300" />
<p class="img-caption"><strong>Figure 1.</strong> 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).</p>
</div>
<div class="figure" style="width:300px">
<img src="{@docRoot}images/webapps/compare-width400.png" alt="" height="300" />
<p class="img-caption"><strong>Figure 2.</strong> A web page with viewport {@code width=400} and
"overview mode" enabled (the image in the web page is 320 pixels wide).</p>
</div>
<h3 id="ViewportSize">Defining the viewport size</h3>
<p>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).</p>
<p>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.</p>
<p>For example, if your web page is designed to be exactly 320 pixels wide, then you might
want to specify that size for the viewport width:</p>
<pre>
&lt;meta name="viewport" content="width=320" /&gt;
</pre>
<p>In this case, your web page exactly fits the screen width, because the web page width and
viewport width are the same.</p>
<p class="note"><strong>Note:</strong> 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.</p>
<p>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.</p>
<p class="note"><strong>Note:</strong> If you set the viewport width to match your web page width
and the device's screen width does <em>not</em> 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 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 <a href="#ViewportDensity">Defining the
viewport target density</a>.</p>
<h4>Automatic sizing</h4>
<p>As an alternative to specifying the viewport dimensions with exact pixels, you can set the
viewport size to always match the dimensions of the device screen, by defining the
viewport properties {@code height}
and {@code width} with the values {@code device-height} and {@code device-width}, respectively. This
is appropriate when you're developing a web application that has a fluid width (not fixed width),
but you want it to appear as if it's fixed (to perfectly fit every screen as
if the web page width is set to match each screen). For example:</p>
<pre>
&lt;meta name="viewport" content="width=device-width" /&gt;
</pre>
<p>This results in the viewport width matching whatever the current screen width is, as shown in
figure 3. It's important to notice that, this results in images being scaled to fit the screen
when the current device does not match the <a href="#ViewportDensity">target
density</a>, which is medium-density if you don't specify otherwise. As a result, the image
displayed on the high-density device in figure 3 is scaled up in order to match the width
of a screen with a medium-density screen.</p>
<div class="figure" style="width:300px">
<img src="{@docRoot}images/webapps/compare-initialscale.png" alt="" height="300" />
<p class="img-caption"><strong>Figure 3.</strong> A web page with viewport {@code
width=device-width} <em>or</em> {@code initial-scale=1.0}.</p>
</div>
<p class="note"><strong>Note:</strong> If you instead want {@code
device-width} and {@code device-height} to match the physical screen pixels for every device,
instead of scaling your web page to match the target density, then you must also include
the {@code target-densitydpi} property with a value of {@code device-dpi}. This is discussed more in
the section about <a href="#ViewportDensity">Defining the viewport density</a>. Otherwise, simply
using {@code device-height} and {@code device-width} to define the viewport size makes your web page
fit every device screen, but scaling occurs on your images in order to adjust for different screen
densities.</p>
<h3 id="ViewportScale">Defining the viewport scale</h3>
<p>The scale of the viewport defines the level of zoom applied to the web page. Viewport
properties allow you to specify the scale of your web page in the following ways:</p>
<dl>
<dt>{@code initial-scale}</dt>
<dd>The initial scale of the page. The value is a float that indicates a multiplier for your web
page size, relative to the screen size. For example, if you set the initial scale to "1.0" then the
web page is displayed to match the resolution of the <a href="#ViewportDensity">target
density</a> 1-to-1. If set to "2.0", then the page is enlarged (zoomed in) by a factor of 2.
<p>The default initial scale is calculated to fit the web page in the viewport size.
Because the default viewport width is 800 pixels, if the device screen resolution is less than
800 pixels wide, the initial scale is something less than 1.0, by default, in order to fit the
800-pixel-wide page on the screen.</p></dd>
<dt>{@code minimum-scale}</dt>
<dd>The minimum scale to allow. The value is a float that indicates the minimum multiplier for
your web page size, relative to the screen size. For example, if you set this to "1.0", then the
page can't zoom out because the minimum size is 1-to-1 with the <a href="#ViewportDensity">target
density</a>.</dd>
<dt>{@code maximum-scale}</dt>
<dd>The maximum scale to allow for the page. The value is a float that indicates the
maximum multiplier for your web page size,
relative to the screen size. For example, if you set this to "2.0", then the page can't
zoom in more than 2 times the target size.</dd>
<dt>{@code user-scalable}</dt>
<dd>Whether the user can change the scale of the page at all (zoom in and out). Set to {@code yes}
to allow scaling and {@code no} to disallow scaling. The default is {@code yes}. If you set
this to {@code no}, then the {@code minimum-scale} and {@code maximum-scale} are ignored,
because scaling is not possible.</dd>
</dl>
<p>All scale values must be within the range 0.01&ndash;10.</p>
<p>For example:</p>
<pre>
&lt;meta name="viewport" content="initial-scale=1.0" /&gt;
</pre>
<p>This metadata sets the initial scale to be full sized, relative to the viewport's target
density.</p>
<p class="note"><strong>Note:</strong> You should disable user scaling only when you're certain
that your web page layout is flexible and the content will fit the width of small screens.</p>
<h3 id="ViewportDensity">Defining the viewport target density</h3>
<p>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 (hdpi). 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 and {@link
android.webkit.WebView} target a medium density screen by default.</p>
<div class="figure" style="width:300px">
<img src="{@docRoot}images/webapps/compare-initialscale-devicedpi.png" alt="" height="300" />
<p class="img-caption"><strong>Figure 4.</strong> A web page with viewport {@code
width=device-width} and {@code target-densitydpi=device-dpi}.</p>
</div>
<p>Because the default target density is medium, when users have a device with a low or high density
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).</p>
<p>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
web page with a default scale factor that is 1.5 times larger than the actual pixel resolution, to
match the target density). This can introduce some undesirable artifacts in your images.
For example, although an image appears the same size on a medium and high-density device, the image
on the high-density device appears more blurry, because the image is designed to be 320 pixels
wide, but is drawn with 480 pixels.</p>
<p>You can change the target screen density for your web page using the {@code target-densitydpi}
viewport property. It accepts the following values:</p>
<ul>
<li><code>device-dpi</code> - Use the device's native dpi as the target dpi. Default scaling never
occurs.</li>
<li><code>high-dpi</code> - Use hdpi as the target dpi. Medium and low density screens scale down
as appropriate.</li>
<li><code>medium-dpi</code> - Use mdpi as the target dpi. High density screens scale up and low
density screens scale down. This is the default target density.</li>
<li><code>low-dpi</code> - Use ldpi as the target dpi. Medium and high density screens scale up
as appropriate.</li>
<li><em><code>&lt;value&gt;</code></em> - Specify a dpi value to use as the target dpi. Values must
be within the range 70&ndash;400.</li>
</ul></p>
<p>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:</p>
<pre>
&lt;meta name="viewport" content="target-densitydpi=device-dpi, width=device-width" /&gt;
</pre>
<p>Figure 4 shows a web page using these viewport settings&mdash;the high-density device
now displays the page smaller because its physical pixels are smaller than those on the
medium-density device, so no scaling occurs and the 320-pixel-wide image is drawn using exactly 320
pixels on both screens. (This is how you should define your viewport if
you want to customize your web page based on screen density and provide different image assets for
different densities, <a href="#DensityCSS">with CSS</a> or
<a href="#DensityJS">with JavaScript</a>.)</p>
<h2 id="DensityCSS">Targeting Device Density with CSS</h2>
@ -349,17 +133,9 @@ or high density screens, respectively.</p>
<pre>
&lt;link rel="stylesheet" media="screen and (-webkit-device-pixel-ratio: 1.5)" href="hdpi.css" /&gt;
&lt;link rel="stylesheet" media="screen and (-webkit-device-pixel-ratio: 1.0)" href="mdpi.css" /&gt;
&lt;link rel="stylesheet" media="screen and (-webkit-device-pixel-ratio: 0.75)" href="ldpi.css" /&gt;
</pre>
<div class="figure" style="width:300px">
<img src="{@docRoot}images/webapps/compare-width-devicedpi-css.png" alt="" height="300" />
<p class="img-caption"><strong>Figure 5.</strong> A web page with CSS that's targetted to
specific screen densities using the {@code -webkit-device-pixel-ratio} media feature. Notice
that the hdpi device shows a different image that's applied in CSS.</p>
</div>
<p>Or, specify the different styles in one stylesheet:</p>
<pre class="no-pretty-print">
@ -382,27 +158,10 @@ that the hdpi device shows a different image that's applied in CSS.</p>
}
</pre>
<p class="note"><strong>Note:</strong> The default style for {@code #header} applies the image
designed for medium-density devices in order to support devices running a version of Android less
than 2.0, which do not support the {@code -webkit-device-pixel-ratio} media feature.</p>
<p>The types of styles you might want to adjust based on the screen density depend on how you've
defined your viewport properties. To provide fully-customized styles that tailor your web page for
each of the supported densities, you should set your viewport properties so the viewport width and
density match the device. That is:</p>
<pre>
&lt;meta name="viewport" content="target-densitydpi=device-dpi, width=device-width" /&gt;
</pre>
<p>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
screens.</p>
<p>For more information about handling different screen densities, especially images, see
<a href="http://www.html5rocks.com/en/mobile/high-dpi/" class="external-link">High
DPI Images for Variable Pixel Densities</a>.</li>
<h2 id="DensityJS">Targeting Device Density with JavaScript</h2>
@ -432,8 +191,3 @@ if (window.devicePixelRatio == 1.5) {
</pre>

1
docs/html/guide/webapps/webview.jd
View File

@ -136,7 +136,6 @@ custom user agent string with {@link android.webkit.WebSettings#setUserAgentStri
setUserAgentString()}, then query the custom user agent in your web page to verify that the
client requesting your web page is actually your Android application.</p>
from your Android SDK {@code tools/} directory
<h3 id="BindingJavaScript">Binding JavaScript code to Android code</h3>
<p>When developing a web application that's designed specifically for the {@link

BIN
docs/html/images/webapps/web-viewport-320@2x.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 293 KiB

BIN
docs/html/images/webapps/web-viewport-default@2x.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 259 KiB

BIN
docs/html/images/webapps/web-viewport-devicewidth@2x.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 311 KiB