FileDocCategorySizeDatePackage
WebSettings.javaAPI DocAndroid 1.5 API35989Wed May 06 22:41:56 BST 2009android.webkit

WebSettings

public class WebSettings extends Object
Manages settings state for a WebView. When a WebView is first created, it obtains a set of default settings. These default settings will be returned from any getter call. A WebSettings object obtained from WebView.getSettings() is tied to the life of the WebView. If a WebView has been destroyed, any method call on WebSettings will throw an IllegalStateException.

Fields Summary
public static final int
LOAD_DEFAULT
Default cache usage pattern Use with {@link #setCacheMode}.
public static final int
LOAD_NORMAL
Normal cache usage pattern Use with {@link #setCacheMode}.
public static final int
LOAD_CACHE_ELSE_NETWORK
Use cache if content is there, even if expired (eg, history nav) If it is not in the cache, load from network. Use with {@link #setCacheMode}.
public static final int
LOAD_NO_CACHE
Don't use the cache, load from network Use with {@link #setCacheMode}.
public static final int
LOAD_CACHE_ONLY
Don't use the network, load from cache only. Use with {@link #setCacheMode}.
private BrowserFrame
mBrowserFrame
private boolean
mSyncPending
private final EventHandler
mEventHandler
private LayoutAlgorithm
mLayoutAlgorithm
private android.content.Context
mContext
private TextSize
mTextSize
private String
mStandardFontFamily
private String
mFixedFontFamily
private String
mSansSerifFontFamily
private String
mSerifFontFamily
private String
mCursiveFontFamily
private String
mFantasyFontFamily
private String
mDefaultTextEncoding
private String
mUserAgent
private boolean
mUseDefaultUserAgent
private String
mAcceptLanguage
private String
mPluginsPath
private int
mMinimumFontSize
private int
mMinimumLogicalFontSize
private int
mDefaultFontSize
private int
mDefaultFixedFontSize
private boolean
mLoadsImagesAutomatically
private boolean
mBlockNetworkImage
private boolean
mBlockNetworkLoads
private boolean
mJavaScriptEnabled
private boolean
mPluginsEnabled
private boolean
mJavaScriptCanOpenWindowsAutomatically
private boolean
mUseDoubleTree
private boolean
mUseWideViewport
private boolean
mSupportMultipleWindows
private boolean
mShrinksStandaloneImagesToFit
private RenderPriority
mRenderPriority
private int
mOverrideCacheMode
private boolean
mSaveFormData
private boolean
mSavePassword
private boolean
mLightTouchEnabled
private boolean
mNeedInitialFocus
private boolean
mNavDump
private boolean
mSupportZoom
private boolean
mBuiltInZoomControls
private boolean
mAllowFileAccess
private static final String
DESKTOP_USERAGENT
private static final String
IPHONE_USERAGENT
private static Locale
sLocale
private static Object
sLockForLocaleSettings
Constructors Summary
WebSettings(android.content.Context context)
Package constructor to prevent clients from creating a new settings instance.

    
                    
         
        mEventHandler = new EventHandler();
        mContext = context;

        if (sLockForLocaleSettings == null) {
            sLockForLocaleSettings = new Object();
            sLocale = Locale.getDefault();
        }
        mAcceptLanguage = getCurrentAcceptLanguage();
        mUserAgent = getCurrentUserAgent();
        mUseDefaultUserAgent = true;

        mBlockNetworkLoads = mContext.checkPermission(
                "android.permission.INTERNET", android.os.Process.myPid(),
                android.os.Process.myUid()) != PackageManager.PERMISSION_GRANTED;
Methods Summary
synchronized java.lang.StringgetAcceptLanguage()

        synchronized(sLockForLocaleSettings) {
            Locale currentLocale = Locale.getDefault();
            if (!sLocale.equals(currentLocale)) {
                sLocale = currentLocale;
                mAcceptLanguage = getCurrentAcceptLanguage();
            }
        }
        return mAcceptLanguage;
public booleangetAllowFileAccess()
Returns true if this WebView supports file access.

        return mAllowFileAccess;
public synchronized booleangetBlockNetworkImage()
Return true if the WebView will block network image.

return
True if the WebView blocks network image.

        return mBlockNetworkImage;
public synchronized booleangetBlockNetworkLoads()

hide
Return true if the WebView will block all network loads.
return
True if the WebView blocks all network loads.

        return mBlockNetworkLoads;
public booleangetBuiltInZoomControls()
Returns true if the zoom mechanism built into WebView is being used.

        return mBuiltInZoomControls;
public intgetCacheMode()
Return the current setting for overriding the cache mode. For a full description, see the {@link #setCacheMode(int)} function.

        return mOverrideCacheMode;
private java.lang.StringgetCurrentAcceptLanguage()
Looks at sLocale and returns current AcceptLanguage String.

return
Current AcceptLanguage String.

        Locale locale;
        synchronized(sLockForLocaleSettings) {
            locale = sLocale;
        }
        StringBuffer buffer = new StringBuffer();
        final String language = locale.getLanguage();
        if (language != null) {
            buffer.append(language);
            final String country = locale.getCountry();
            if (country != null) {
                buffer.append("-");
                buffer.append(country);
            }
        }
        if (!locale.equals(Locale.US)) {
            buffer.append(", ");
            java.util.Locale us = Locale.US;
            if (us.getLanguage() != null) {
                buffer.append(us.getLanguage());
                final String country = us.getCountry();
                if (country != null) {
                    buffer.append("-");
                    buffer.append(country);
                }
            }
        }

        return buffer.toString();
private synchronized java.lang.StringgetCurrentUserAgent()
Looks at sLocale and mContext and returns current UserAgent String.

return
Current UserAgent String.

        Locale locale;
        synchronized(sLockForLocaleSettings) {
            locale = sLocale;
        }
        StringBuffer buffer = new StringBuffer();
        // Add version
        final String version = Build.VERSION.RELEASE;
        if (version.length() > 0) {
            buffer.append(version);
        } else {
            // default to "1.0"
            buffer.append("1.0");
        }  
        buffer.append("; ");
        final String language = locale.getLanguage();
        if (language != null) {
            buffer.append(language.toLowerCase());
            final String country = locale.getCountry();
            if (country != null) {
                buffer.append("-");
                buffer.append(country.toLowerCase());
            }
        } else {
            // default to "en"
            buffer.append("en");
        }
        
        final String model = Build.MODEL;
        if (model.length() > 0) {
            buffer.append("; ");
            buffer.append(model);
        }
        final String id = Build.ID;
        if (id.length() > 0) {
            buffer.append(" Build/");
            buffer.append(id);
        }
        final String base = mContext.getResources().getText(
                com.android.internal.R.string.web_user_agent).toString();
        return String.format(base, buffer);
public synchronized java.lang.StringgetCursiveFontFamily()
Get the cursive font family name.

return
The cursive font family name as a string.

        return mCursiveFontFamily;
public synchronized intgetDefaultFixedFontSize()
Get the default fixed font size.

return
A non-negative integer between 1 and 72.

        return mDefaultFixedFontSize;
public synchronized intgetDefaultFontSize()
Get the default font size.

return
A non-negative integer between 1 and 72.

        return mDefaultFontSize;
public synchronized java.lang.StringgetDefaultTextEncodingName()
Get the default text encoding name.

return
The default text encoding name as a string.

        return mDefaultTextEncoding;
public synchronized java.lang.StringgetFantasyFontFamily()
Get the fantasy font family name.

return
The fantasy font family name as a string.

        return mFantasyFontFamily;
public synchronized java.lang.StringgetFixedFontFamily()
Get the fixed font family name.

return
The fixed font family name as a string.

        return mFixedFontFamily;
public synchronized booleangetJavaScriptCanOpenWindowsAutomatically()
Return true if javascript can open windows automatically.

return
True if javascript can open windows automatically during window.open().

        return mJavaScriptCanOpenWindowsAutomatically;
public synchronized booleangetJavaScriptEnabled()
Return true if javascript is enabled.

return
True if javascript is enabled.

        return mJavaScriptEnabled;
public synchronized android.webkit.WebSettings$LayoutAlgorithmgetLayoutAlgorithm()
Return the current layout algorithm.

return
LayoutAlgorithm enum value describing the layout algorithm being used.
see
WebSettings.LayoutAlgorithm

        return mLayoutAlgorithm;
public booleangetLightTouchEnabled()
Returns true if light touches are enabled.

        return mLightTouchEnabled;
public synchronized booleangetLoadsImagesAutomatically()
Return true if the WebView will load image resources automatically.

return
True if the WebView loads images automatically.

        return mLoadsImagesAutomatically;
public synchronized intgetMinimumFontSize()
Get the minimum font size.

return
A non-negative integer between 1 and 72.

        return mMinimumFontSize;
public synchronized intgetMinimumLogicalFontSize()
Get the minimum logical font size.

return
A non-negative integer between 1 and 72.

        return mMinimumLogicalFontSize;
public booleangetNavDump()
Returns true if dumping the navigation cache is enabled.

        return mNavDump;
booleangetNeedInitialFocus()

        return mNeedInitialFocus;
public synchronized booleangetPluginsEnabled()
Return true if plugins are enabled.

return
True if plugins are enabled.

        return mPluginsEnabled;
public synchronized java.lang.StringgetPluginsPath()
Return the current path used for plugins in the WebView.

return
The string path to the WebView plugins.

        return mPluginsPath;
public synchronized java.lang.StringgetSansSerifFontFamily()
Get the sans-serif font family name.

return
The sans-serif font family name as a string.

        return mSansSerifFontFamily;
public booleangetSaveFormData()
Return whether the WebView is saving form data.

        return mSaveFormData;
public booleangetSavePassword()
Return whether the WebView is saving password.

        return mSavePassword;
public synchronized java.lang.StringgetSerifFontFamily()
Get the serif font family name.

return
The serif font family name as a string.

        return mSerifFontFamily;
public synchronized java.lang.StringgetStandardFontFamily()
Get the standard font family name.

return
The standard font family name as a string.

        return mStandardFontFamily;
public synchronized android.webkit.WebSettings$TextSizegetTextSize()
Get the text size of the page.

return
A TextSize enum value describing the text size.
see
WebSettings.TextSize

        return mTextSize;
public synchronized booleangetUseDoubleTree()
Return true if the WebView is using the double tree rendering algorithm.

return
True if the WebView is using the double tree rendering algorithm.

        return mUseDoubleTree;
public synchronized booleangetUseWideViewPort()

return
True if the WebView is using a wide viewport

        return mUseWideViewport;
public synchronized intgetUserAgent()
Return user-agent as int

return
int 0 if the WebView is using an Android user-agent string. 1 if the WebView is using a desktop user-agent string. -1 if the WebView is using user defined user-agent string.
deprecated
Please use getUserAgentString instead.

        if (DESKTOP_USERAGENT.equals(mUserAgent)) {
            return 1;
        } else if (IPHONE_USERAGENT.equals(mUserAgent)) {
            return 2;
        } else if (mUseDefaultUserAgent) {
            return 0;
        }
        return -1;
public synchronized java.lang.StringgetUserAgentString()
Return the WebView's user-agent string.

        if (DESKTOP_USERAGENT.equals(mUserAgent) ||
                IPHONE_USERAGENT.equals(mUserAgent) ||
                !mUseDefaultUserAgent) {
            return mUserAgent;
        }

        boolean doPostSync = false;
        synchronized(sLockForLocaleSettings) {
            Locale currentLocale = Locale.getDefault();
            if (!sLocale.equals(currentLocale)) {
                sLocale = currentLocale;
                mUserAgent = getCurrentUserAgent();
                mAcceptLanguage = getCurrentAcceptLanguage();
                doPostSync = true;
            }
        }
        if (doPostSync) {
            postSync();
        }
        return mUserAgent;
private native voidnativeSync(int nativeFrame)

private intpin(int size)
        // FIXME: 72 is just an arbitrary max text size value.
        if (size < 1) {
            return 1;
        } else if (size > 72) {
            return 72;
        }
        return size;
    
private synchronized voidpostSync()
        // Only post if a sync is not pending
        if (!mSyncPending) {
            mSyncPending = mEventHandler.sendMessage(
                    Message.obtain(null, EventHandler.SYNC));
        }
    
public voidsetAllowFileAccess(boolean allow)
Enable or disable file access within WebView. File access is enabled by
default.
        mAllowFileAccess = allow;
    
public synchronized voidsetBlockNetworkImage(boolean flag)
Tell the WebView to block network image. This is only checked when
getLoadsImagesAutomatically() is true.
param
flag True if the WebView should block network image
        if (mBlockNetworkImage != flag) {
            mBlockNetworkImage = flag;
            postSync();
        }
    
public synchronized voidsetBlockNetworkLoads(boolean flag)
hide
Tell the WebView to block all network load requests.
param
flag True if the WebView should block all network loads
        if (mBlockNetworkLoads != flag) {
            mBlockNetworkLoads = flag;
            verifyNetworkAccess();
        }
    
public voidsetBuiltInZoomControls(boolean enabled)
Sets whether the zoom mechanism built into WebView is used.
        mBuiltInZoomControls = enabled;
    
public voidsetCacheMode(int mode)
Override the way the cache is used. The way the cache is used is based
on the navigation option. For a normal page load, the cache is checked
and content is re-validated as needed. When navigating back, content is
not revalidated, instead the content is just pulled from the cache.
This function allows the client to override this behavior.
param
mode One of the LOAD_ values.
        if (mode != mOverrideCacheMode) {
            mOverrideCacheMode = mode;
        }
    
public synchronized voidsetCursiveFontFamily(java.lang.String font)
Set the cursive font family name.
param
font A font family name.
        if (font != null && !font.equals(mCursiveFontFamily)) {
            mCursiveFontFamily = font;
            postSync();
        }
    
public synchronized voidsetDefaultFixedFontSize(int size)
Set the default fixed font size.
param
size A non-negative integer between 1 and 72.
Any number outside the specified range will be pinned.
        size = pin(size);
        if (mDefaultFixedFontSize != size) {
            mDefaultFixedFontSize = size;
            postSync();
        }
    
public synchronized voidsetDefaultFontSize(int size)
Set the default font size.
param
size A non-negative integer between 1 and 72.
Any number outside the specified range will be pinned.
        size = pin(size);
        if (mDefaultFontSize != size) {
            mDefaultFontSize = size;
            postSync();
        }
    
public synchronized voidsetDefaultTextEncodingName(java.lang.String encoding)
Set the default text encoding name to use when decoding html pages.
param
encoding The text encoding name.
        if (encoding != null && !encoding.equals(mDefaultTextEncoding)) {
            mDefaultTextEncoding = encoding;
            postSync();
        }
    
public synchronized voidsetFantasyFontFamily(java.lang.String font)
Set the fantasy font family name.
param
font A font family name.
        if (font != null && !font.equals(mFantasyFontFamily)) {
            mFantasyFontFamily = font;
            postSync();
        }
    
public synchronized voidsetFixedFontFamily(java.lang.String font)
Set the fixed font family name.
param
font A font family name.
        if (font != null && !font.equals(mFixedFontFamily)) {
            mFixedFontFamily = font;
            postSync();
        }
    
public synchronized voidsetJavaScriptCanOpenWindowsAutomatically(boolean flag)
Tell javascript to open windows automatically. This applies to the
javascript function window.open().
param
flag True if javascript can open windows automatically.
        if (mJavaScriptCanOpenWindowsAutomatically != flag) {
            mJavaScriptCanOpenWindowsAutomatically = flag;
            postSync();
        }
    
public synchronized voidsetJavaScriptEnabled(boolean flag)
Tell the WebView to enable javascript execution.
param
flag True if the WebView should execute javascript.
        if (mJavaScriptEnabled != flag) {
            mJavaScriptEnabled = flag;
            postSync();
        }
    
public synchronized voidsetLayoutAlgorithm(android.webkit.WebSettings$LayoutAlgorithm l)
Set the underlying layout algorithm. This will cause a relayout of the
WebView.
param
l A LayoutAlgorithm enum specifying the algorithm to use.
see
WebSettings.LayoutAlgorithm
        // XXX: This will only be affective if libwebcore was built with
        // ANDROID_LAYOUT defined.
        if (mLayoutAlgorithm != l) {
            mLayoutAlgorithm = l;
            postSync();
        }
    
public voidsetLightTouchEnabled(boolean enabled)
Enables using light touches to make a selection and activate mouseovers.
        mLightTouchEnabled = enabled;
    
public synchronized voidsetLoadsImagesAutomatically(boolean flag)
Tell the WebView to load image resources automatically.
param
flag True if the WebView should load images automatically.
        if (mLoadsImagesAutomatically != flag) {
            mLoadsImagesAutomatically = flag;
            postSync();
        }
    
public synchronized voidsetMinimumFontSize(int size)
Set the minimum font size.
param
size A non-negative integer between 1 and 72.
Any number outside the specified range will be pinned.
        size = pin(size);
        if (mMinimumFontSize != size) {
            mMinimumFontSize = size;
            postSync();
        }
    
public synchronized voidsetMinimumLogicalFontSize(int size)
Set the minimum logical font size.
param
size A non-negative integer between 1 and 72.
Any number outside the specified range will be pinned.
        size = pin(size);
        if (mMinimumLogicalFontSize != size) {
            mMinimumLogicalFontSize = size;
            postSync();
        }
    
public voidsetNavDump(boolean enabled)
Enables dumping the pages navigation cache to a text file.
        mNavDump = enabled;
    
public voidsetNeedInitialFocus(boolean flag)
Tell the WebView whether it needs to set a node to have focus when
{@link WebView#requestFocus(int, android.graphics.Rect)} is called.
param
flag
        if (mNeedInitialFocus != flag) {
            mNeedInitialFocus = flag;
        }
    
public synchronized voidsetPluginsEnabled(boolean flag)
Tell the WebView to enable plugins.
param
flag True if the WebView should load plugins.
        if (mPluginsEnabled != flag) {
            mPluginsEnabled = flag;
            postSync();
        }
    
public synchronized voidsetPluginsPath(java.lang.String pluginsPath)
Set a custom path to plugins used by the WebView. The client
must ensure it exists before this call.
param
pluginsPath String path to the directory containing plugins.
        if (pluginsPath != null && !pluginsPath.equals(mPluginsPath)) {
            mPluginsPath = pluginsPath;
            postSync();
        }
    
public synchronized voidsetRenderPriority(android.webkit.WebSettings$RenderPriority priority)
Set the priority of the Render thread. Unlike the other settings, this
one only needs to be called once per process.
param
priority RenderPriority, can be normal, high or low.
        if (mRenderPriority != priority) {
            mRenderPriority = priority;
            mEventHandler.sendMessage(Message.obtain(null,
                    EventHandler.PRIORITY));
        }
    
public synchronized voidsetSansSerifFontFamily(java.lang.String font)
Set the sans-serif font family name.
param
font A font family name.
        if (font != null && !font.equals(mSansSerifFontFamily)) {
            mSansSerifFontFamily = font;
            postSync();
        }
    
public voidsetSaveFormData(boolean save)
Store whether the WebView is saving form data.
        mSaveFormData = save;
    
public voidsetSavePassword(boolean save)
Store whether the WebView is saving password.
        mSavePassword = save;
    
public synchronized voidsetSerifFontFamily(java.lang.String font)
Set the serif font family name.
param
font A font family name.
        if (font != null && !font.equals(mSerifFontFamily)) {
            mSerifFontFamily = font;
            postSync();
        }
    
public voidsetShrinksStandaloneImagesToFit(boolean shrink)
If set, webkit alternately shrinks and expands images viewed outside
of an HTML page to fit the screen. This conflicts with attempts by
the UI to zoom in and out of an image, so it is set false by default.
param
shrink Set true to let webkit shrink the standalone image to fit.
{@hide}
        if (mShrinksStandaloneImagesToFit != shrink) {
            mShrinksStandaloneImagesToFit = shrink;
            postSync();
        }
     
public synchronized voidsetStandardFontFamily(java.lang.String font)
Set the standard font family name.
param
font A font family name.
        if (font != null && !font.equals(mStandardFontFamily)) {
            mStandardFontFamily = font;
            postSync();
        }
    
public synchronized voidsetSupportMultipleWindows(boolean support)
Tell the WebView whether it supports multiple windows. TRUE means
that {@link WebChromeClient#onCreateWindow(WebView, boolean,
boolean, Message)} is implemented by the host application.
        if (mSupportMultipleWindows != support) {
            mSupportMultipleWindows = support;
            postSync();
        }
    
public voidsetSupportZoom(boolean support)
Set whether the WebView supports zoom
        mSupportZoom = support;
    
public synchronized voidsetTextSize(android.webkit.WebSettings$TextSize t)
Set the text size of the page.
param
t A TextSize value for increasing or decreasing the text.
see
WebSettings.TextSize
        if (WebView.mLogEvent && mTextSize != t ) {
            Checkin.updateStats(mContext.getContentResolver(),
                    Checkin.Stats.Tag.BROWSER_TEXT_SIZE_CHANGE, 1, 0.0);
        }
        mTextSize = t;
        postSync();
    
public synchronized voidsetUseDoubleTree(boolean use)
Tell the WebView to use the double tree rendering algorithm.
param
use True if the WebView is to use double tree rendering, false
otherwise.
        if (mUseDoubleTree != use) {
            mUseDoubleTree = use;
            postSync();
        }
    
public synchronized voidsetUseWideViewPort(boolean use)
Tell the WebView to use the wide viewport
        if (mUseWideViewport != use) {
            mUseWideViewport = use;
            postSync();
        }
    
public synchronized voidsetUserAgent(int ua)
Tell the WebView about user-agent string.
param
ua 0 if the WebView should use an Android user-agent string,
1 if the WebView should use a desktop user-agent string.
deprecated
Please use setUserAgentString instead.
        String uaString = null;
        if (ua == 1) {
            if (DESKTOP_USERAGENT.equals(mUserAgent)) {
                return; // do nothing
            } else {
                uaString = DESKTOP_USERAGENT;
            }
        } else if (ua == 2) {
            if (IPHONE_USERAGENT.equals(mUserAgent)) {
                return; // do nothing
            } else {
                uaString = IPHONE_USERAGENT;
            }
        } else if (ua != 0) {
            return; // do nothing
        }
        setUserAgentString(uaString);
    
public synchronized voidsetUserAgentString(java.lang.String ua)
Set the WebView's user-agent string. If the string "ua" is null or empty,
it will use the system default user-agent string.
        if (ua == null || ua.length() == 0) {
            synchronized(sLockForLocaleSettings) {
                Locale currentLocale = Locale.getDefault(); 
                if (!sLocale.equals(currentLocale)) {
                    sLocale = currentLocale;
                    mAcceptLanguage = getCurrentAcceptLanguage();
                }
            }
            ua = getCurrentUserAgent();
            mUseDefaultUserAgent = true;
        } else  {
            mUseDefaultUserAgent = false;
        }

        if (!ua.equals(mUserAgent)) {
            mUserAgent = ua;
            postSync();
        }
    
public synchronized booleansupportMultipleWindows()
return
True if the WebView is supporting multiple windows. This means
that {@link WebChromeClient#onCreateWindow(WebView, boolean,
boolean, Message)} is implemented by the host application.
        return mSupportMultipleWindows;
    
public booleansupportZoom()
Returns whether the WebView supports zoom
        return mSupportZoom;
    
synchronized voidsyncSettingsAndCreateHandler(BrowserFrame frame)
Transfer messages from the queue to the new WebCoreThread. Called from
WebCore thread.
        mBrowserFrame = frame;
        if (android.util.Config.DEBUG) {
            junit.framework.Assert.assertTrue(frame.mNativeFrame != 0);
        }
        nativeSync(frame.mNativeFrame);
        mSyncPending = false;
        mEventHandler.createHandler();
    
private voidverifyNetworkAccess()
        if (!mBlockNetworkLoads) {
            if (mContext.checkPermission("android.permission.INTERNET", 
                    android.os.Process.myPid(), android.os.Process.myUid()) != 
                        PackageManager.PERMISSION_GRANTED) {
                throw new SecurityException
                        ("Permission denied - " +
                                "application missing INTERNET permission");
            }
        }