Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add some documentation to WebView, WebSettings and CookieSyncManager.

Browse Source 
Double-tree rendering is deprecated.
This commit is contained in:
Mike Hearn
2009-01-21 16:44:36 +01:00
committed by Jean-Baptiste Queru
parent 55f6b8e910
commit adcd2ed8d2
4 changed files with 180 additions and 66 deletions
Download Patch File Download Diff File Expand all files Collapse all files

43
core/java/android/webkit/CookieSyncManager.java
View File

@@ -25,30 +25,39 @@ import java.util.ArrayList;
import java.util.Iterator;
/**
* The class CookieSyncManager is used to synchronize the browser cookies
* between RAM and FLASH. To get the best performance, browser cookie is saved
* in RAM. We use a separate thread to sync the cookies between RAM and FLASH on
* a timer base.
* The CookieSyncManager is used to synchronize the browser cookie store
* between RAM and permanent storage. To get the best performance, browser cookies are
* saved in RAM. A separate thread saves the cookies between, driven by a timer.
* <p>
*
* To use the CookieSyncManager, the host application has to call the following
* when the application starts.
* when the application starts:
* <p>
* CookieSyncManager.createInstance(context)
* <p>
* To set up for sync, the host application has to call
* <p>
* CookieSyncManager.getInstance().startSync()
* <p>
* in its Activity.onResume(), and call
*
* <pre class="prettyprint">CookieSyncManager.createInstance(context)</pre><p>
*
* To set up for sync, the host application has to call<p>
* <pre class="prettyprint">CookieSyncManager.getInstance().startSync()</pre><p>
*
* in Activity.onResume(), and call
* <p>
*
* <pre class="prettyprint">
* CookieSyncManager.getInstance().stopSync()
* <p>
* in its Activity.onStop().
* <p>
* </pre><p>
*
* in Activity.onPause().<p>
*
* To get instant sync instead of waiting for the timer to trigger, the host can
* call
* <p>
* CookieSyncManager.getInstance().sync()
* <pre class="prettyprint">CookieSyncManager.getInstance().sync()</pre><p>
*
* The sync interval is 5 minutes, so you will want to force syncs
* manually anyway, for instance in {@link
* WebViewClient#onPageFinished}. Note that even sync() happens
* asynchronously, so don't do it just as your activity is shutting
* down.
*/
public final class CookieSyncManager extends WebSyncManager {
@@ -91,7 +100,7 @@ public final class CookieSyncManager extends WebSyncManager {
}
/**
* Package level api, called from CookieManager Get all the cookies which
* Package level api, called from CookieManager. Get all the cookies which
* matches a given base domain.
* @param domain
* @return A list of Cookie

70
core/java/android/webkit/WebSettings.java
View File

@@ -109,9 +109,13 @@ public class WebSettings {
private boolean mSyncPending = false;
// Custom handler that queues messages until the WebCore thread is active.
private final EventHandler mEventHandler;
// Private settings so we don't have to go into native code to
// retrieve the values. After setXXX, postSync() needs to be called.
// XXX: The default values need to match those in WebSettings.cpp
//
// The default values need to match those in WebSettings.cpp
// If the defaults change, please also update the JavaDocs so developers
// know what they are.
private LayoutAlgorithm mLayoutAlgorithm = LayoutAlgorithm.NARROW_COLUMNS;
private Context mContext;
private TextSize mTextSize = TextSize.NORMAL;
@@ -431,24 +435,21 @@ public class WebSettings {
}
/**
* Tell the WebView to use the double tree rendering algorithm.
* @param use True if the WebView is to use double tree rendering, false
* otherwise.
* @deprecated This setting controlled a rendering optimization
* that is no longer present. Setting it now has no effect.
*/
@Deprecated
public synchronized void setUseDoubleTree(boolean use) {
if (mUseDoubleTree != use) {
mUseDoubleTree = use;
postSync();
}
return;
}
/**
* Return true if the WebView is using the double tree rendering algorithm.
* @return True if the WebView is using the double tree rendering
* algorithm.
* @deprecated This setting controlled a rendering optimization
* that is no longer present. Setting it now has no effect.
*/
@Deprecated
public synchronized boolean getUseDoubleTree() {
return mUseDoubleTree;
return false;
}
/**
@@ -553,7 +554,7 @@ public class WebSettings {
}
/**
* Return the current layout algorithm.
* Return the current layout algorithm. The default is NARROW_COLUMNS.
* @return LayoutAlgorithm enum value describing the layout algorithm
* being used.
* @see WebSettings.LayoutAlgorithm
@@ -574,7 +575,7 @@ public class WebSettings {
}
/**
* Get the standard font family name.
* Get the standard font family name. The default is "sans-serif".
* @return The standard font family name as a string.
*/
public synchronized String getStandardFontFamily() {
@@ -593,7 +594,7 @@ public class WebSettings {
}
/**
* Get the fixed font family name.
* Get the fixed font family name. The default is "monospace".
* @return The fixed font family name as a string.
*/
public synchronized String getFixedFontFamily() {
@@ -620,7 +621,7 @@ public class WebSettings {
}
/**
* Set the serif font family name.
* Set the serif font family name. The default is "sans-serif".
* @param font A font family name.
*/
public synchronized void setSerifFontFamily(String font) {
@@ -631,7 +632,7 @@ public class WebSettings {
}
/**
* Get the serif font family name.
* Get the serif font family name. The default is "serif".
* @return The serif font family name as a string.
*/
public synchronized String getSerifFontFamily() {
@@ -650,7 +651,7 @@ public class WebSettings {
}
/**
* Get the cursive font family name.
* Get the cursive font family name. The default is "cursive".
* @return The cursive font family name as a string.
*/
public synchronized String getCursiveFontFamily() {
@@ -669,7 +670,7 @@ public class WebSettings {
}
/**
* Get the fantasy font family name.
* Get the fantasy font family name. The default is "fantasy".
* @return The fantasy font family name as a string.
*/
public synchronized String getFantasyFontFamily() {
@@ -690,7 +691,7 @@ public class WebSettings {
}
/**
* Get the minimum font size.
* Get the minimum font size. The default is 8.
* @return A non-negative integer between 1 and 72.
*/
public synchronized int getMinimumFontSize() {
@@ -711,7 +712,7 @@ public class WebSettings {
}
/**
* Get the minimum logical font size.
* Get the minimum logical font size. The default is 8.
* @return A non-negative integer between 1 and 72.
*/
public synchronized int getMinimumLogicalFontSize() {
@@ -732,7 +733,7 @@ public class WebSettings {
}
/**
* Get the default font size.
* Get the default font size. The default is 16.
* @return A non-negative integer between 1 and 72.
*/
public synchronized int getDefaultFontSize() {
@@ -753,7 +754,7 @@ public class WebSettings {
}
/**
* Get the default fixed font size.
* Get the default fixed font size. The default is 16.
* @return A non-negative integer between 1 and 72.
*/
public synchronized int getDefaultFixedFontSize() {
@@ -773,6 +774,7 @@ public class WebSettings {
/**
* Return true if the WebView will load image resources automatically.
* The default is true.
* @return True if the WebView loads images automatically.
*/
public synchronized boolean getLoadsImagesAutomatically() {
@@ -792,16 +794,16 @@ public class WebSettings {
}
/**
* Return true if the WebView will block network image.
* Return true if the WebView will block network image. The default is false.
* @return True if the WebView blocks network image.
*/
public synchronized boolean getBlockNetworkImage() {
return mBlockNetworkImage;
}
/**
* @hide
* Tell the WebView to block all network load requests.
* Tell the WebView to block all network load requests.
* @param flag True if the WebView should block all network loads
*/
public synchronized void setBlockNetworkLoads(boolean flag) {
@@ -814,13 +816,14 @@ public class WebSettings {
/**
* @hide
* Return true if the WebView will block all network loads.
* The default is false.
* @return True if the WebView blocks all network loads.
*/
public synchronized boolean getBlockNetworkLoads() {
return mBlockNetworkLoads;
}
private void verifyNetworkAccess() {
if (!mBlockNetworkLoads) {
if (mContext.checkPermission("android.permission.INTERNET",
@@ -868,7 +871,7 @@ public class WebSettings {
}
/**
* Return true if javascript is enabled.
* Return true if javascript is enabled. <b>Note: The default is false.</b>
* @return True if javascript is enabled.
*/
public synchronized boolean getJavaScriptEnabled() {
@@ -905,7 +908,8 @@ public class WebSettings {
}
/**
* Return true if javascript can open windows automatically.
* Return true if javascript can open windows automatically. The default
* is false.
* @return True if javascript can open windows automatically during
* window.open().
*/
@@ -925,7 +929,7 @@ public class WebSettings {
}
/**
* Get the default text encoding name.
* Get the default text encoding name. The default is "Latin-1".
* @return The default text encoding name as a string.
*/
public synchronized String getDefaultTextEncodingName() {
@@ -1014,8 +1018,8 @@ public class WebSettings {
/**
* Set the priority of the Render thread. Unlike the other settings, this
* one only needs to be called once per process.
*
* one only needs to be called once per process. The default is NORMAL.
*
* @param priority RenderPriority, can be normal, high or low.
*/
public synchronized void setRenderPriority(RenderPriority priority) {

129
core/java/android/webkit/WebView.java
View File

@@ -81,16 +81,116 @@ import java.util.HashMap;
import java.util.List;
/**
* <p>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.</p>
* <p>Note that, in order for your Activity to access the Internet and load web pages
* in a WebView, you must add the <var>INTERNET</var> permissions to your
* Android Manifest file:</p>
* <p>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.</p>
*
* <p>Note that, in order for your Activity to access the Internet and
* load web pages in a WebView, you must add the <var>INTERNET</var>
* permissions to your Android Manifest file:</p>
*
* <pre>&lt;uses-permission android:name="android.permission.INTERNET" /></pre>
*
* <p>This must be a child of the <code>&lt;manifest></code> element.</p>
*
* <h3>Basic usage</h3>
*
* <p>By default, a WebView provides no browser-like widgets, does not
* enable JavaScript and errors will be 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.</p>
*
* <pre class="prettyprint">
* WebView webview = new WebView(this);
* setContentView(webview);
*
* // 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:
* String summary = "&lt;html>&lt;body>You scored &lt;b>192</b> points.&lt;/body>&lt;/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.
* </pre>
*
* <p>A WebView has several customization points where you can add your
* own behavior. These are:</p>
*
* <ul>
* <li>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.
* </li>
* <li>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.</li>
* <li>Via the {@link android.webkit.WebSettings} class, which contains
* miscellaneous configuration. </li>
* <li>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.</li>
* </ul>
*
* <p>Here's a more complicated example, showing error handling,
* settings, and progress notification:</p>
*
* <pre class="prettyprint">
* // 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("http://slashdot.org/");
* </pre>
*
* <h3>Cookie and window management</h3>
*
* <p>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
* 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.
* </p>
*
* <p>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,
* and render them in whatever manner you want.</p>
*
* <p>Standard behavior for an Activity is to be destroyed and
* recreated when the devices orientation is changed. 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
* changes, and then just leave the WebView alone. It'll automatically
* re-orient itself as appropriate.</p>
*/
public class WebView extends AbsoluteLayout
implements ViewTreeObserver.OnGlobalFocusChangeListener,
@@ -1698,14 +1798,15 @@ public class WebView extends AbsoluteLayout
}
/**
* Clear the resource cache. This will cause resources to be re-downloaded
* if accessed again.
* <p>
* Note: this really needs to be a static method as it clears cache for all
* WebView. But we need mWebViewCore to send message to WebCore thread, so
* we can't make this static.
* Clear the resource cache. Note that the cache is per-application, so
* this will clear the cache for all WebViews used.
*
* @param includeDiskFiles If false, only the RAM cache is cleared.
*/
public void clearCache(boolean includeDiskFiles) {
// Note: this really needs to be a static method as it clears cache for all
// WebView. But we need mWebViewCore to send message to WebCore thread, so
// we can't make this static.
mWebViewCore.sendMessage(EventHub.CLEAR_CACHE,
includeDiskFiles ? 1 : 0, 0);
}