diff --git a/core/java/android/webkit/WebView.java b/core/java/android/webkit/WebView.java index 0c103e50ee457..3452b0cc3ddff 100644 --- a/core/java/android/webkit/WebView.java +++ b/core/java/android/webkit/WebView.java @@ -71,280 +71,25 @@ import java.util.List; import java.util.Map; /** - *

A View that displays web pages. This class is the basis upon which you - * can roll your own web browser or simply display some online content within your Activity. - * It uses the WebKit rendering engine to display - * web pages and includes methods to navigate forward and backward - * through a history, zoom in and out, perform text searches and more. - * - *

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

- * {@code }
- *
- * - *

This must be a child of the {@code } - * element. - * - *

For more information, read - * Building Web Apps in WebView. + * A View that displays web pages. * *

Basic usage

* - *

By default, a WebView provides no browser-like widgets, does not - * 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 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("https://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 } in your layout, - * or set the entire Activity window as a WebView during {@link - * android.app.Activity#onCreate(Bundle) onCreate()}: + *

In most cases, we recommend using a standard web browser, like Chrome, to deliver + * content to the user. To learn more about web browsers, read the guide on + * + * invoking a browser with an intent. * - * 

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

WebView objects allow you to display web content as part of your activity layout, but + * lack some of the features of fully-developed browsers. A WebView is useful when + * you need increased control over the UI and advanced configuration options that will allow + * you to embed web pages in a specially-designed environment for your app. * - *

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("https://example.com/");
- *
- * // OR, you can also load from an HTML string:
- * String summary = "<html><body>You scored <b>192</b> points.</body></html>";
- * webview.loadData(summary, "text/html", null);
- * // ... although note that there are restrictions on what this HTML can do.
- * // See {@link #loadData(String,String,String)} and {@link
- * #loadDataWithBaseURL(String,String,String,String,String)} for more info.
- * // Also see {@link #loadData(String,String,String)} for information on encoding special
- * // characters.
- *
- * - *

A WebView has several customization points where you can add your - * own behavior. These are: - * - *

- * - *

Here's a more complicated example, showing error handling, - * settings, and progress notification: - * - * 

- * // Let's display the progress in the activity title bar, like the
- * // browser app does.
- * getWindow().requestFeature(Window.FEATURE_PROGRESS);
- *
- * webview.getSettings().setJavaScriptEnabled(true);
- *
- * final Activity activity = this;
- * webview.setWebChromeClient(new WebChromeClient() {
- *   public void onProgressChanged(WebView view, int progress) {
- *     // Activities and WebViews measure progress with different scales.
- *     // The progress meter will automatically disappear when we reach 100%
- *     activity.setProgress(progress * 1000);
- *   }
- * });
- * webview.setWebViewClient(new WebViewClient() {
- *   public void onReceivedError(WebView view, int errorCode, String description, String failingUrl) {
- *     Toast.makeText(activity, "Oh no! " + description, Toast.LENGTH_SHORT).show();
- *   }
- * });
- *
- * webview.loadUrl("https://developer.android.com/");
- *
- * - *

Zoom

- * - *

To enable the built-in zoom, set - * {@link #getSettings() WebSettings}.{@link WebSettings#setBuiltInZoomControls(boolean)} - * (introduced in API level {@link android.os.Build.VERSION_CODES#CUPCAKE}). - * - *

Note: Using zoom if either the height or width is set to - * {@link android.view.ViewGroup.LayoutParams#WRAP_CONTENT} may lead to undefined behavior - * and should be avoided. - * - *

Cookie and window management

- * - *

For obvious security reasons, your application has its own - * cache, cookie store etc.—it does not share the Browser - * application's data. - * - *

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

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 {@code orientation} and {@code keyboardHidden} - * changes, and then just leave the WebView alone. It'll automatically - * 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 {@link android.os.Build.VERSION_CODES#ECLAIR}, 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: - *

- * - *

HTML5 Video support

- * - *

In order to support inline HTML5 video in your application you need to have hardware - * acceleration turned on. - * - *

Full screen support

- * - *

In order to support full screen — for video or other HTML content — you need to set a - * {@link android.webkit.WebChromeClient} and implement both - * {@link WebChromeClient#onShowCustomView(View, WebChromeClient.CustomViewCallback)} - * and {@link WebChromeClient#onHideCustomView()}. If the implementation of either of these two methods is - * missing then the web contents will not be allowed to enter full screen. Optionally you can implement - * {@link WebChromeClient#getVideoLoadingProgressView()} to customize the View displayed whilst a video - * is loading. - * - *

HTML5 Geolocation API support

- * - *

For applications targeting Android N and later releases - * (API level > {@link android.os.Build.VERSION_CODES#M}) the geolocation api is only supported on - * secure origins such as https. For such applications requests to geolocation api on non-secure - * origins are automatically denied without invoking the corresponding - * {@link WebChromeClient#onGeolocationPermissionsShowPrompt(String, GeolocationPermissions.Callback)} - * method. - * - *

Layout size

- *

- * It is recommended to set the WebView layout height to a fixed value or to - * {@link android.view.ViewGroup.LayoutParams#MATCH_PARENT} instead of using - * {@link android.view.ViewGroup.LayoutParams#WRAP_CONTENT}. - * When using {@link android.view.ViewGroup.LayoutParams#MATCH_PARENT} - * for the height none of the WebView's parents should use a - * {@link android.view.ViewGroup.LayoutParams#WRAP_CONTENT} layout height since that could result in - * incorrect sizing of the views. - * - *

Setting the WebView's height to {@link android.view.ViewGroup.LayoutParams#WRAP_CONTENT} - * enables the following behaviors: - *

- * - *

- * Using a layout width of {@link android.view.ViewGroup.LayoutParams#WRAP_CONTENT} is not - * supported. If such a width is used the WebView will attempt to use the width of the parent - * instead. - * - *

Metrics

- * - *

- * WebView may upload anonymous diagnostic data to Google when the user has consented. This data - * helps Google improve WebView. Data is collected on a per-app basis for each app which has - * instantiated a WebView. An individual app can opt out of this feature by putting the following - * tag in its manifest's {@code } element: - * 

- * <manifest>
- *     <application>
- *         ...
- *         <meta-data android:name="android.webkit.WebView.MetricsOptOut"
- *             android:value="true" />
- *     </application>
- * </manifest>
- *
- *

- * Data will only be uploaded for a given app if the user has consented AND the app has not opted - * out. - * - *

Safe Browsing

- * - *

- * With Safe Browsing, WebView will block malicious URLs and present a warning UI to the user to - * allow them to navigate back safely or proceed to the malicious page. - *

- * Safe Browsing is enabled by default on devices which support it. If your app needs to disable - * Safe Browsing for all WebViews, it can do so in the manifest's {@code } element: - *

- * 

- * <manifest>
- *     <application>
- *         ...
- *         <meta-data android:name="android.webkit.WebView.EnableSafeBrowsing"
- *             android:value="false" />
- *     </application>
- * </manifest>
- *
- * - *

- * Otherwise, see {@link WebSettings#setSafeBrowsingEnabled}. + *

To learn more about WebView and alternatives for serving web content, read the + * documentation on + * + * Web-based content. * */ // Implementation notes.