From 8b3cea01bffa440c17c5381f887fb6b02f6c2230 Mon Sep 17 00:00:00 2001 From: Scott Main Date: Fri, 14 May 2010 14:12:43 -0700 Subject: docs: revise webview description and add info for targeting screen densities Change-Id: Ib0293b497adef23330ee3f5f71904ad78a55a3a3 --- core/java/android/webkit/WebView.java | 123 ++++++++++++++++++++++++++++------ 1 file changed, 103 insertions(+), 20 deletions(-) (limited to 'core') diff --git a/core/java/android/webkit/WebView.java b/core/java/android/webkit/WebView.java index f921caa..863a6cd 100644 --- a/core/java/android/webkit/WebView.java +++ b/core/java/android/webkit/WebView.java @@ -109,36 +109,50 @@ import junit.framework.Assert; * {@link #getSettings() WebSettings}.{@link WebSettings#setBuiltInZoomControls(boolean)} * (introduced in API version 3). *

Note that, in order for your Activity to access the Internet and load web pages - * in a WebView, you must add the INTERNET permissions to your + * in a WebView, you must add the {@code INTERNET} permissions to your * Android Manifest file:

* 
<uses-permission android:name="android.permission.INTERNET" />
* - *

This must be a child of the <manifest> element.

+ *

This must be a child of the {@code <manifest>} + * element.

* *

Basic usage

* *

By default, a WebView provides no browser-like widgets, does not - * enable JavaScript and errors will be ignored. If your goal is only + * enable JavaScript and web page errors are ignored. If your goal is only * to display some HTML as a part of your UI, this is probably fine; * the user won't need to interact with the web page beyond reading * it, and the web page won't need to interact with the user. If you - * actually want a fully blown web browser, then you probably want to - * invoke the Browser application with your URL rather than show it - * with a WebView. See {@link android.content.Intent} for more information.

+ * actually want a full-blown web browser, then you probably want to + * invoke the Browser application with a URL Intent rather than show it + * with a WebView. For example: + * 
+ * Uri uri = Uri.parse("http://www.example.com");
+ * Intent intent = new Intent(Intent.ACTION_VIEW, uri);
+ * startActivity(intent);
+ *
+ *

See {@link android.content.Intent} for more information.

* + *

To provide a WebView in your own Activity, include a {@code <WebView>} in your layout, + * or set the entire Activity window as a WebView during {@link + * android.app.Activity#onCreate(Bundle) onCreate()}:

* 
  * WebView webview = new WebView(this);
  * setContentView(webview);
+ *
* + *

Then load the desired web page:

* // Simplest usage: note that an exception will NOT be thrown * // if there is an error loading this page (see below). * webview.loadUrl("http://slashdot.org/"); * - * // Of course you can also load from any string: + * // OR, you can also load from an HTML string: * String summary = "<html><body>You scored <b>192 points.</body></html>"; * webview.loadData(summary, "text/html", "utf-8"); * // ... although note that there are restrictions on what this HTML can do. - * // See the JavaDocs for loadData and loadDataWithBaseUrl for more info. + * // See the JavaDocs for {@link #loadData(String,String,String) loadData()} and {@link + * #loadDataWithBaseURL(String,String,String,String,String) loadDataWithBaseURL()} for more info. * * *

A WebView has several customization points where you can add your @@ -148,15 +162,20 @@ import junit.framework.Assert; *

  • Creating and setting a {@link android.webkit.WebChromeClient} subclass. * This class is called when something that might impact a * browser UI happens, for instance, progress updates and - * JavaScript alerts are sent here. + * JavaScript alerts are sent here (see Debugging Tasks). *
    • *
  • Creating and setting a {@link android.webkit.WebViewClient} subclass. * It will be called when things happen that impact the * rendering of the content, eg, errors or form submissions. You - * can also intercept URL loading here.
    • - *
  • Via the {@link android.webkit.WebSettings} class, which contains - * miscellaneous configuration.
    • - *
  • With the {@link android.webkit.WebView#addJavascriptInterface} method. + * can also intercept URL loading here (via {@link + * android.webkit.WebViewClient#shouldOverrideUrlLoading(WebView,String) + * shouldOverrideUrlLoading()}).
    • + *
  • Modifying the {@link android.webkit.WebSettings}, such as + * enabling JavaScript with {@link android.webkit.WebSettings#setJavaScriptEnabled(boolean) + * setJavaScriptEnabled()}.
    • + *
  • Adding JavaScript-to-Java interfaces with the {@link + * android.webkit.WebView#addJavascriptInterface} method. * This lets you bind Java objects into the WebView so they can be * controlled from the web pages JavaScript.
    • * @@ -191,8 +210,8 @@ import junit.framework.Assert; *

    Cookie and window management

    * *

    For obvious security reasons, your application has its own - * cache, cookie store etc - it does not share the Browser - * applications data. Cookies are managed on a separate thread, so + * cache, cookie store etc.—it does not share the Browser + * application's data. Cookies are managed on a separate thread, so * operations like index building don't block the UI * thread. Follow the instructions in {@link android.webkit.CookieSyncManager} * if you want to use cookies in your application. @@ -201,15 +220,79 @@ import junit.framework.Assert; *

    By default, requests by the HTML to open new windows are * ignored. This is true whether they be opened by JavaScript or by * the target attribute on a link. You can customize your - * WebChromeClient to provide your own behaviour for opening multiple windows, + * {@link WebChromeClient} to provide your own behaviour for opening multiple windows, * and render them in whatever manner you want.

    * - *

    Standard behavior for an Activity is to be destroyed and - * recreated when the devices orientation is changed. This will cause + *

    The standard behavior for an Activity is to be destroyed and + * recreated when the device orientation or any other configuration changes. This will cause * the WebView to reload the current page. If you don't want that, you - * can set your Activity to handle the orientation and keyboardHidden + * can set your Activity to handle the {@code orientation} and {@code keyboardHidden} * changes, and then just leave the WebView alone. It'll automatically - * re-orient itself as appropriate.

    + * re-orient itself as appropriate. Read Handling Runtime Changes for + * more information about how to handle configuration changes during runtime.

    + * + * + *

    Building web pages to support different screen densities

    + * + *

    The screen density of a device is based on the screen resolution. A screen with low density + * has fewer available pixels per inch, where a screen with high density + * has more — sometimes significantly more — pixels per inch. The density of a + * screen is important because, other things being equal, a UI element (such as a button) whose + * height and width are defined in terms of screen pixels will appear larger on the lower density + * screen and smaller on the higher density screen. + * For simplicity, Android collapses all actual screen densities into three generalized densities: + * high, medium, and low.

    + *

    By default, WebView scales a web page so that it is drawn at a size that matches the default + * appearance on a medium density screen. So, it applies 1.5x scaling on a high density screen + * (because its pixels are smaller) and 0.75x scaling on a low density screen (because its pixels + * are bigger). + * Starting with API Level 5 (Android 2.0), WebView supports DOM, CSS, and meta tag features to help + * you (as a web developer) target screens with different screen densities.

    + *

    Here's a summary of the features you can use to handle different screen densities:

    + * + *

    If you want to modify your web page for different densities, by using the {@code + * -webkit-device-pixel-ratio} CSS media query and/or the {@code + * window.devicePixelRatio} DOM property, then you should set the {@code target-densitydpi} meta + * property to {@code device-dpi}. This stops Android from performing scaling in your web page and + * allows you to make the necessary adjustments for each density via CSS and JavaScript.

    + * + * */ @Widget public class WebView extends AbsoluteLayout -- cgit v1.1