1/* 2 * Copyright (C) 2007 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17package android.webkit; 18 19import android.annotation.SystemApi; 20import android.content.Context; 21 22/** 23 * Manages settings state for a WebView. When a WebView is first created, it 24 * obtains a set of default settings. These default settings will be returned 25 * from any getter call. A WebSettings object obtained from 26 * WebView.getSettings() is tied to the life of the WebView. If a WebView has 27 * been destroyed, any method call on WebSettings will throw an 28 * IllegalStateException. 29 */ 30// This is an abstract base class: concrete WebViewProviders must 31// create a class derived from this, and return an instance of it in the 32// WebViewProvider.getWebSettingsProvider() method implementation. 33public abstract class WebSettings { 34 /** 35 * Enum for controlling the layout of html. 36 * <ul> 37 * <li>NORMAL means no rendering changes. This is the recommended choice for maximum 38 * compatibility across different platforms and Android versions.</li> 39 * <li>SINGLE_COLUMN moves all content into one column that is the width of the 40 * view.</li> 41 * <li>NARROW_COLUMNS makes all columns no wider than the screen if possible. Only use 42 * this for API levels prior to {@link android.os.Build.VERSION_CODES#KITKAT}.</li> 43 * <li>TEXT_AUTOSIZING boosts font size of paragraphs based on heuristics to make 44 * the text readable when viewing a wide-viewport layout in the overview mode. 45 * It is recommended to enable zoom support {@link #setSupportZoom} when 46 * using this mode. Supported from API level 47 * {@link android.os.Build.VERSION_CODES#KITKAT}</li> 48 * </ul> 49 */ 50 // XXX: These must match LayoutAlgorithm in Settings.h in WebCore. 51 public enum LayoutAlgorithm { 52 NORMAL, 53 /** 54 * @deprecated This algorithm is now obsolete. 55 */ 56 @Deprecated 57 SINGLE_COLUMN, 58 /** 59 * @deprecated This algorithm is now obsolete. 60 */ 61 @Deprecated 62 NARROW_COLUMNS, 63 TEXT_AUTOSIZING 64 } 65 66 /** 67 * Enum for specifying the text size. 68 * <ul> 69 * <li>SMALLEST is 50%</li> 70 * <li>SMALLER is 75%</li> 71 * <li>NORMAL is 100%</li> 72 * <li>LARGER is 150%</li> 73 * <li>LARGEST is 200%</li> 74 * </ul> 75 * 76 * @deprecated Use {@link WebSettings#setTextZoom(int)} and {@link WebSettings#getTextZoom()} instead. 77 */ 78 public enum TextSize { 79 SMALLEST(50), 80 SMALLER(75), 81 NORMAL(100), 82 LARGER(150), 83 LARGEST(200); 84 TextSize(int size) { 85 value = size; 86 } 87 int value; 88 } 89 90 /** 91 * Enum for specifying the WebView's desired density. 92 * <ul> 93 * <li>FAR makes 100% looking like in 240dpi</li> 94 * <li>MEDIUM makes 100% looking like in 160dpi</li> 95 * <li>CLOSE makes 100% looking like in 120dpi</li> 96 * </ul> 97 */ 98 public enum ZoomDensity { 99 FAR(150), // 240dpi 100 MEDIUM(100), // 160dpi 101 CLOSE(75); // 120dpi 102 ZoomDensity(int size) { 103 value = size; 104 } 105 106 /** 107 * @hide Only for use by WebViewProvider implementations 108 */ 109 public int getValue() { 110 return value; 111 } 112 113 int value; 114 } 115 116 /** 117 * Default cache usage mode. If the navigation type doesn't impose any 118 * specific behavior, use cached resources when they are available 119 * and not expired, otherwise load resources from the network. 120 * Use with {@link #setCacheMode}. 121 */ 122 public static final int LOAD_DEFAULT = -1; 123 124 /** 125 * Normal cache usage mode. Use with {@link #setCacheMode}. 126 * 127 * @deprecated This value is obsolete, as from API level 128 * {@link android.os.Build.VERSION_CODES#HONEYCOMB} and onwards it has the 129 * same effect as {@link #LOAD_DEFAULT}. 130 */ 131 @Deprecated 132 public static final int LOAD_NORMAL = 0; 133 134 /** 135 * Use cached resources when they are available, even if they have expired. 136 * Otherwise load resources from the network. 137 * Use with {@link #setCacheMode}. 138 */ 139 public static final int LOAD_CACHE_ELSE_NETWORK = 1; 140 141 /** 142 * Don't use the cache, load from the network. 143 * Use with {@link #setCacheMode}. 144 */ 145 public static final int LOAD_NO_CACHE = 2; 146 147 /** 148 * Don't use the network, load from the cache. 149 * Use with {@link #setCacheMode}. 150 */ 151 public static final int LOAD_CACHE_ONLY = 3; 152 153 public enum RenderPriority { 154 NORMAL, 155 HIGH, 156 LOW 157 } 158 159 /** 160 * The plugin state effects how plugins are treated on a page. ON means 161 * that any object will be loaded even if a plugin does not exist to handle 162 * the content. ON_DEMAND means that if there is a plugin installed that 163 * can handle the content, a placeholder is shown until the user clicks on 164 * the placeholder. Once clicked, the plugin will be enabled on the page. 165 * OFF means that all plugins will be turned off and any fallback content 166 * will be used. 167 */ 168 public enum PluginState { 169 ON, 170 ON_DEMAND, 171 OFF 172 } 173 174 /** 175 * Used with {@link #setMixedContentMode} 176 * 177 * In this mode, the WebView will allow a secure origin to load content from any other origin, 178 * even if that origin is insecure. This is the least secure mode of operation for the WebView, 179 * and where possible apps should not set this mode. 180 */ 181 public static final int MIXED_CONTENT_ALWAYS_ALLOW = 0; 182 183 /** 184 * Used with {@link #setMixedContentMode} 185 * 186 * In this mode, the WebView will not allow a secure origin to load content from an insecure 187 * origin. This is the preferred and most secure mode of operation for the WebView and apps are 188 * strongly advised to use this mode. 189 */ 190 public static final int MIXED_CONTENT_NEVER_ALLOW = 1; 191 192 /** 193 * Used with {@link #setMixedContentMode} 194 * 195 * In this mode, the WebView will attempt to be compatible with the approach of a modern web 196 * browser with regard to mixed content. Some insecure content may be allowed to be loaded by 197 * a secure origin and other types of content will be blocked. The types of content are allowed 198 * or blocked may change release to release and are not explicitly defined. 199 * 200 * This mode is intended to be used by apps that are not in control of the content that they 201 * render but desire to operate in a reasonably secure environment. For highest security, apps 202 * are recommended to use {@link #MIXED_CONTENT_NEVER_ALLOW}. 203 */ 204 public static final int MIXED_CONTENT_COMPATIBILITY_MODE = 2; 205 206 /** 207 * Enables dumping the pages navigation cache to a text file. The default 208 * is false. 209 * 210 * @deprecated This method is now obsolete. 211 * @hide Since API level {@link android.os.Build.VERSION_CODES#JELLY_BEAN_MR1} 212 */ 213 @SystemApi 214 @Deprecated 215 public abstract void setNavDump(boolean enabled); 216 217 /** 218 * Gets whether dumping the navigation cache is enabled. 219 * 220 * @return whether dumping the navigation cache is enabled 221 * @see #setNavDump 222 * @deprecated This method is now obsolete. 223 * @hide Since API level {@link android.os.Build.VERSION_CODES#JELLY_BEAN_MR1} 224 */ 225 @SystemApi 226 @Deprecated 227 public abstract boolean getNavDump(); 228 229 /** 230 * Sets whether the WebView should support zooming using its on-screen zoom 231 * controls and gestures. The particular zoom mechanisms that should be used 232 * can be set with {@link #setBuiltInZoomControls}. This setting does not 233 * affect zooming performed using the {@link WebView#zoomIn()} and 234 * {@link WebView#zoomOut()} methods. The default is true. 235 * 236 * @param support whether the WebView should support zoom 237 */ 238 public abstract void setSupportZoom(boolean support); 239 240 /** 241 * Gets whether the WebView supports zoom. 242 * 243 * @return true if the WebView supports zoom 244 * @see #setSupportZoom 245 */ 246 public abstract boolean supportZoom(); 247 248 /** 249 * Sets whether the WebView requires a user gesture to play media. 250 * The default is true. 251 * 252 * @param require whether the WebView requires a user gesture to play media 253 */ 254 public abstract void setMediaPlaybackRequiresUserGesture(boolean require); 255 256 /** 257 * Gets whether the WebView requires a user gesture to play media. 258 * 259 * @return true if the WebView requires a user gesture to play media 260 * @see #setMediaPlaybackRequiresUserGesture 261 */ 262 public abstract boolean getMediaPlaybackRequiresUserGesture(); 263 264 /** 265 * Sets whether the WebView should use its built-in zoom mechanisms. The 266 * built-in zoom mechanisms comprise on-screen zoom controls, which are 267 * displayed over the WebView's content, and the use of a pinch gesture to 268 * control zooming. Whether or not these on-screen controls are displayed 269 * can be set with {@link #setDisplayZoomControls}. The default is false. 270 * <p> 271 * The built-in mechanisms are the only currently supported zoom 272 * mechanisms, so it is recommended that this setting is always enabled. 273 * 274 * @param enabled whether the WebView should use its built-in zoom mechanisms 275 */ 276 // This method was intended to select between the built-in zoom mechanisms 277 // and the separate zoom controls. The latter were obtained using 278 // {@link WebView#getZoomControls}, which is now hidden. 279 public abstract void setBuiltInZoomControls(boolean enabled); 280 281 /** 282 * Gets whether the zoom mechanisms built into WebView are being used. 283 * 284 * @return true if the zoom mechanisms built into WebView are being used 285 * @see #setBuiltInZoomControls 286 */ 287 public abstract boolean getBuiltInZoomControls(); 288 289 /** 290 * Sets whether the WebView should display on-screen zoom controls when 291 * using the built-in zoom mechanisms. See {@link #setBuiltInZoomControls}. 292 * The default is true. 293 * 294 * @param enabled whether the WebView should display on-screen zoom controls 295 */ 296 public abstract void setDisplayZoomControls(boolean enabled); 297 298 /** 299 * Gets whether the WebView displays on-screen zoom controls when using 300 * the built-in zoom mechanisms. 301 * 302 * @return true if the WebView displays on-screen zoom controls when using 303 * the built-in zoom mechanisms 304 * @see #setDisplayZoomControls 305 */ 306 public abstract boolean getDisplayZoomControls(); 307 308 /** 309 * Enables or disables file access within WebView. File access is enabled by 310 * default. Note that this enables or disables file system access only. 311 * Assets and resources are still accessible using file:///android_asset and 312 * file:///android_res. 313 */ 314 public abstract void setAllowFileAccess(boolean allow); 315 316 /** 317 * Gets whether this WebView supports file access. 318 * 319 * @see #setAllowFileAccess 320 */ 321 public abstract boolean getAllowFileAccess(); 322 323 /** 324 * Enables or disables content URL access within WebView. Content URL 325 * access allows WebView to load content from a content provider installed 326 * in the system. The default is enabled. 327 */ 328 public abstract void setAllowContentAccess(boolean allow); 329 330 /** 331 * Gets whether this WebView supports content URL access. 332 * 333 * @see #setAllowContentAccess 334 */ 335 public abstract boolean getAllowContentAccess(); 336 337 /** 338 * Sets whether the WebView loads pages in overview mode, that is, 339 * zooms out the content to fit on screen by width. This setting is 340 * taken into account when the content width is greater than the width 341 * of the WebView control, for example, when {@link #getUseWideViewPort} 342 * is enabled. The default is false. 343 */ 344 public abstract void setLoadWithOverviewMode(boolean overview); 345 346 /** 347 * Gets whether this WebView loads pages in overview mode. 348 * 349 * @return whether this WebView loads pages in overview mode 350 * @see #setLoadWithOverviewMode 351 */ 352 public abstract boolean getLoadWithOverviewMode(); 353 354 /** 355 * Sets whether the WebView will enable smooth transition while panning or 356 * zooming or while the window hosting the WebView does not have focus. 357 * If it is true, WebView will choose a solution to maximize the performance. 358 * e.g. the WebView's content may not be updated during the transition. 359 * If it is false, WebView will keep its fidelity. The default value is false. 360 * 361 * @deprecated This method is now obsolete, and will become a no-op in future. 362 */ 363 @Deprecated 364 public abstract void setEnableSmoothTransition(boolean enable); 365 366 /** 367 * Gets whether the WebView enables smooth transition while panning or 368 * zooming. 369 * 370 * @see #setEnableSmoothTransition 371 * 372 * @deprecated This method is now obsolete, and will become a no-op in future. 373 */ 374 @Deprecated 375 public abstract boolean enableSmoothTransition(); 376 377 /** 378 * Sets whether the WebView uses its background for over scroll background. 379 * If true, it will use the WebView's background. If false, it will use an 380 * internal pattern. Default is true. 381 * 382 * @deprecated This method is now obsolete. 383 * @hide Since API level {@link android.os.Build.VERSION_CODES#JELLY_BEAN_MR1} 384 */ 385 @SystemApi 386 @Deprecated 387 public abstract void setUseWebViewBackgroundForOverscrollBackground(boolean view); 388 389 /** 390 * Gets whether this WebView uses WebView's background instead of 391 * internal pattern for over scroll background. 392 * 393 * @see #setUseWebViewBackgroundForOverscrollBackground 394 * @deprecated This method is now obsolete. 395 * @hide Since API level {@link android.os.Build.VERSION_CODES#JELLY_BEAN_MR1} 396 */ 397 @SystemApi 398 @Deprecated 399 public abstract boolean getUseWebViewBackgroundForOverscrollBackground(); 400 401 /** 402 * Sets whether the WebView should save form data. The default is true. 403 */ 404 public abstract void setSaveFormData(boolean save); 405 406 /** 407 * Gets whether the WebView saves form data. 408 * 409 * @return whether the WebView saves form data 410 * @see #setSaveFormData 411 */ 412 public abstract boolean getSaveFormData(); 413 414 /** 415 * Sets whether the WebView should save passwords. The default is true. 416 * @deprecated Saving passwords in WebView will not be supported in future versions. 417 */ 418 @Deprecated 419 public abstract void setSavePassword(boolean save); 420 421 /** 422 * Gets whether the WebView saves passwords. 423 * 424 * @return whether the WebView saves passwords 425 * @see #setSavePassword 426 * @deprecated Saving passwords in WebView will not be supported in future versions. 427 */ 428 @Deprecated 429 public abstract boolean getSavePassword(); 430 431 /** 432 * Sets the text zoom of the page in percent. The default is 100. 433 * 434 * @param textZoom the text zoom in percent 435 */ 436 public abstract void setTextZoom(int textZoom); 437 438 /** 439 * Gets the text zoom of the page in percent. 440 * 441 * @return the text zoom of the page in percent 442 * @see #setTextZoom 443 */ 444 public abstract int getTextZoom(); 445 446 /** 447 * Sets policy for third party cookies. 448 * Developers should access this via {@link CookieManager#setShouldAcceptThirdPartyCookies}. 449 * @hide Internal API. 450 */ 451 @SystemApi 452 public abstract void setAcceptThirdPartyCookies(boolean accept); 453 454 /** 455 * Gets policy for third party cookies. 456 * Developers should access this via {@link CookieManager#getShouldAcceptThirdPartyCookies}. 457 * @hide Internal API 458 */ 459 @SystemApi 460 public abstract boolean getAcceptThirdPartyCookies(); 461 462 /** 463 * Sets the text size of the page. The default is {@link TextSize#NORMAL}. 464 * 465 * @param t the text size as a {@link TextSize} value 466 * @deprecated Use {@link #setTextZoom} instead. 467 */ 468 public synchronized void setTextSize(TextSize t) { 469 setTextZoom(t.value); 470 } 471 472 /** 473 * Gets the text size of the page. If the text size was previously specified 474 * in percent using {@link #setTextZoom}, this will return the closest 475 * matching {@link TextSize}. 476 * 477 * @return the text size as a {@link TextSize} value 478 * @see #setTextSize 479 * @deprecated Use {@link #getTextZoom} instead. 480 */ 481 public synchronized TextSize getTextSize() { 482 TextSize closestSize = null; 483 int smallestDelta = Integer.MAX_VALUE; 484 int textSize = getTextZoom(); 485 for (TextSize size : TextSize.values()) { 486 int delta = Math.abs(textSize - size.value); 487 if (delta == 0) { 488 return size; 489 } 490 if (delta < smallestDelta) { 491 smallestDelta = delta; 492 closestSize = size; 493 } 494 } 495 return closestSize != null ? closestSize : TextSize.NORMAL; 496 } 497 498 /** 499 * Sets the default zoom density of the page. This must be called from the UI 500 * thread. The default is {@link ZoomDensity#MEDIUM}. 501 * 502 * This setting is not recommended for use in new applications. If the WebView 503 * is utilized to display mobile-oriented pages, the desired effect can be achieved by 504 * adjusting 'width' and 'initial-scale' attributes of page's 'meta viewport' 505 * tag. For pages lacking the tag, {@link android.webkit.WebView#setInitialScale} 506 * and {@link #setUseWideViewPort} can be used. 507 * 508 * @param zoom the zoom density 509 * @deprecated This method is no longer supported, see the function documentation for 510 * recommended alternatives. 511 */ 512 @Deprecated 513 public abstract void setDefaultZoom(ZoomDensity zoom); 514 515 /** 516 * Gets the default zoom density of the page. This should be called from 517 * the UI thread. 518 * 519 * This setting is not recommended for use in new applications. 520 * 521 * @return the zoom density 522 * @see #setDefaultZoom 523 * @deprecated Will only return the default value. 524 */ 525 public abstract ZoomDensity getDefaultZoom(); 526 527 /** 528 * Enables using light touches to make a selection and activate mouseovers. 529 * @deprecated From {@link android.os.Build.VERSION_CODES#JELLY_BEAN} this 530 * setting is obsolete and has no effect. 531 */ 532 @Deprecated 533 public abstract void setLightTouchEnabled(boolean enabled); 534 535 /** 536 * Gets whether light touches are enabled. 537 * @see #setLightTouchEnabled 538 * @deprecated This setting is obsolete. 539 */ 540 @Deprecated 541 public abstract boolean getLightTouchEnabled(); 542 543 /** 544 * Controlled a rendering optimization that is no longer present. Setting 545 * it now has no effect. 546 * 547 * @deprecated This setting now has no effect. 548 * @hide Since API level {@link android.os.Build.VERSION_CODES#JELLY_BEAN_MR1} 549 */ 550 @Deprecated 551 public void setUseDoubleTree(boolean use) { 552 // Specified to do nothing, so no need for derived classes to override. 553 } 554 555 /** 556 * Controlled a rendering optimization that is no longer present. Setting 557 * it now has no effect. 558 * 559 * @deprecated This setting now has no effect. 560 * @hide Since API level {@link android.os.Build.VERSION_CODES#JELLY_BEAN_MR1} 561 */ 562 @Deprecated 563 public boolean getUseDoubleTree() { 564 // Returns false unconditionally, so no need for derived classes to override. 565 return false; 566 } 567 568 /** 569 * Sets the user-agent string using an integer code. 570 * <ul> 571 * <li>0 means the WebView should use an Android user-agent string</li> 572 * <li>1 means the WebView should use a desktop user-agent string</li> 573 * </ul> 574 * Other values are ignored. The default is an Android user-agent string, 575 * i.e. code value 0. 576 * 577 * @param ua the integer code for the user-agent string 578 * @deprecated Please use {@link #setUserAgentString} instead. 579 * @hide Since API level {@link android.os.Build.VERSION_CODES#JELLY_BEAN_MR1} 580 */ 581 @SystemApi 582 @Deprecated 583 public abstract void setUserAgent(int ua); 584 585 /** 586 * Gets the user-agent as an integer code. 587 * <ul> 588 * <li>-1 means the WebView is using a custom user-agent string set with 589 * {@link #setUserAgentString}</li> 590 * <li>0 means the WebView should use an Android user-agent string</li> 591 * <li>1 means the WebView should use a desktop user-agent string</li> 592 * </ul> 593 * 594 * @return the integer code for the user-agent string 595 * @see #setUserAgent 596 * @deprecated Please use {@link #getUserAgentString} instead. 597 * @hide Since API level {@link android.os.Build.VERSION_CODES#JELLY_BEAN_MR1} 598 */ 599 @SystemApi 600 @Deprecated 601 public abstract int getUserAgent(); 602 603 /** 604 * Sets whether the WebView should enable support for the "viewport" 605 * HTML meta tag or should use a wide viewport. 606 * When the value of the setting is false, the layout width is always set to the 607 * width of the WebView control in device-independent (CSS) pixels. 608 * When the value is true and the page contains the viewport meta tag, the value 609 * of the width specified in the tag is used. If the page does not contain the tag or 610 * does not provide a width, then a wide viewport will be used. 611 * 612 * @param use whether to enable support for the viewport meta tag 613 */ 614 public abstract void setUseWideViewPort(boolean use); 615 616 /** 617 * Gets whether the WebView supports the "viewport" 618 * HTML meta tag or will use a wide viewport. 619 * 620 * @return true if the WebView supports the viewport meta tag 621 * @see #setUseWideViewPort 622 */ 623 public abstract boolean getUseWideViewPort(); 624 625 /** 626 * Sets whether the WebView whether supports multiple windows. If set to 627 * true, {@link WebChromeClient#onCreateWindow} must be implemented by the 628 * host application. The default is false. 629 * 630 * @param support whether to suport multiple windows 631 */ 632 public abstract void setSupportMultipleWindows(boolean support); 633 634 /** 635 * Gets whether the WebView supports multiple windows. 636 * 637 * @return true if the WebView supports multiple windows 638 * @see #setSupportMultipleWindows 639 */ 640 public abstract boolean supportMultipleWindows(); 641 642 /** 643 * Sets the underlying layout algorithm. This will cause a relayout of the 644 * WebView. The default is {@link LayoutAlgorithm#NARROW_COLUMNS}. 645 * 646 * @param l the layout algorithm to use, as a {@link LayoutAlgorithm} value 647 */ 648 public abstract void setLayoutAlgorithm(LayoutAlgorithm l); 649 650 /** 651 * Gets the current layout algorithm. 652 * 653 * @return the layout algorithm in use, as a {@link LayoutAlgorithm} value 654 * @see #setLayoutAlgorithm 655 */ 656 public abstract LayoutAlgorithm getLayoutAlgorithm(); 657 658 /** 659 * Sets the standard font family name. The default is "sans-serif". 660 * 661 * @param font a font family name 662 */ 663 public abstract void setStandardFontFamily(String font); 664 665 /** 666 * Gets the standard font family name. 667 * 668 * @return the standard font family name as a string 669 * @see #setStandardFontFamily 670 */ 671 public abstract String getStandardFontFamily(); 672 673 /** 674 * Sets the fixed font family name. The default is "monospace". 675 * 676 * @param font a font family name 677 */ 678 public abstract void setFixedFontFamily(String font); 679 680 /** 681 * Gets the fixed font family name. 682 * 683 * @return the fixed font family name as a string 684 * @see #setFixedFontFamily 685 */ 686 public abstract String getFixedFontFamily(); 687 688 /** 689 * Sets the sans-serif font family name. The default is "sans-serif". 690 * 691 * @param font a font family name 692 */ 693 public abstract void setSansSerifFontFamily(String font); 694 695 /** 696 * Gets the sans-serif font family name. 697 * 698 * @return the sans-serif font family name as a string 699 * @see #setSansSerifFontFamily 700 */ 701 public abstract String getSansSerifFontFamily(); 702 703 /** 704 * Sets the serif font family name. The default is "sans-serif". 705 * 706 * @param font a font family name 707 */ 708 public abstract void setSerifFontFamily(String font); 709 710 /** 711 * Gets the serif font family name. The default is "serif". 712 * 713 * @return the serif font family name as a string 714 * @see #setSerifFontFamily 715 */ 716 public abstract String getSerifFontFamily(); 717 718 /** 719 * Sets the cursive font family name. The default is "cursive". 720 * 721 * @param font a font family name 722 */ 723 public abstract void setCursiveFontFamily(String font); 724 725 /** 726 * Gets the cursive font family name. 727 * 728 * @return the cursive font family name as a string 729 * @see #setCursiveFontFamily 730 */ 731 public abstract String getCursiveFontFamily(); 732 733 /** 734 * Sets the fantasy font family name. The default is "fantasy". 735 * 736 * @param font a font family name 737 */ 738 public abstract void setFantasyFontFamily(String font); 739 740 /** 741 * Gets the fantasy font family name. 742 * 743 * @return the fantasy font family name as a string 744 * @see #setFantasyFontFamily 745 */ 746 public abstract String getFantasyFontFamily(); 747 748 /** 749 * Sets the minimum font size. The default is 8. 750 * 751 * @param size a non-negative integer between 1 and 72. Any number outside 752 * the specified range will be pinned. 753 */ 754 public abstract void setMinimumFontSize(int size); 755 756 /** 757 * Gets the minimum font size. 758 * 759 * @return a non-negative integer between 1 and 72 760 * @see #setMinimumFontSize 761 */ 762 public abstract int getMinimumFontSize(); 763 764 /** 765 * Sets the minimum logical font size. The default is 8. 766 * 767 * @param size a non-negative integer between 1 and 72. Any number outside 768 * the specified range will be pinned. 769 */ 770 public abstract void setMinimumLogicalFontSize(int size); 771 772 /** 773 * Gets the minimum logical font size. 774 * 775 * @return a non-negative integer between 1 and 72 776 * @see #setMinimumLogicalFontSize 777 */ 778 public abstract int getMinimumLogicalFontSize(); 779 780 /** 781 * Sets the default font size. The default is 16. 782 * 783 * @param size a non-negative integer between 1 and 72. Any number outside 784 * the specified range will be pinned. 785 */ 786 public abstract void setDefaultFontSize(int size); 787 788 /** 789 * Gets the default font size. 790 * 791 * @return a non-negative integer between 1 and 72 792 * @see #setDefaultFontSize 793 */ 794 public abstract int getDefaultFontSize(); 795 796 /** 797 * Sets the default fixed font size. The default is 16. 798 * 799 * @param size a non-negative integer between 1 and 72. Any number outside 800 * the specified range will be pinned. 801 */ 802 public abstract void setDefaultFixedFontSize(int size); 803 804 /** 805 * Gets the default fixed font size. 806 * 807 * @return a non-negative integer between 1 and 72 808 * @see #setDefaultFixedFontSize 809 */ 810 public abstract int getDefaultFixedFontSize(); 811 812 /** 813 * Sets whether the WebView should load image resources. Note that this method 814 * controls loading of all images, including those embedded using the data 815 * URI scheme. Use {@link #setBlockNetworkImage} to control loading only 816 * of images specified using network URI schemes. Note that if the value of this 817 * setting is changed from false to true, all images resources referenced 818 * by content currently displayed by the WebView are loaded automatically. 819 * The default is true. 820 * 821 * @param flag whether the WebView should load image resources 822 */ 823 public abstract void setLoadsImagesAutomatically(boolean flag); 824 825 /** 826 * Gets whether the WebView loads image resources. This includes 827 * images embedded using the data URI scheme. 828 * 829 * @return true if the WebView loads image resources 830 * @see #setLoadsImagesAutomatically 831 */ 832 public abstract boolean getLoadsImagesAutomatically(); 833 834 /** 835 * Sets whether the WebView should not load image resources from the 836 * network (resources accessed via http and https URI schemes). Note 837 * that this method has no effect unless 838 * {@link #getLoadsImagesAutomatically} returns true. Also note that 839 * disabling all network loads using {@link #setBlockNetworkLoads} 840 * will also prevent network images from loading, even if this flag is set 841 * to false. When the value of this setting is changed from true to false, 842 * network images resources referenced by content currently displayed by 843 * the WebView are fetched automatically. The default is false. 844 * 845 * @param flag whether the WebView should not load image resources from the 846 * network 847 * @see #setBlockNetworkLoads 848 */ 849 public abstract void setBlockNetworkImage(boolean flag); 850 851 /** 852 * Gets whether the WebView does not load image resources from the network. 853 * 854 * @return true if the WebView does not load image resources from the network 855 * @see #setBlockNetworkImage 856 */ 857 public abstract boolean getBlockNetworkImage(); 858 859 /** 860 * Sets whether the WebView should not load resources from the network. 861 * Use {@link #setBlockNetworkImage} to only avoid loading 862 * image resources. Note that if the value of this setting is 863 * changed from true to false, network resources referenced by content 864 * currently displayed by the WebView are not fetched until 865 * {@link android.webkit.WebView#reload} is called. 866 * If the application does not have the 867 * {@link android.Manifest.permission#INTERNET} permission, attempts to set 868 * a value of false will cause a {@link java.lang.SecurityException} 869 * to be thrown. The default value is false if the application has the 870 * {@link android.Manifest.permission#INTERNET} permission, otherwise it is 871 * true. 872 * 873 * @param flag whether the WebView should not load any resources from the 874 * network 875 * @see android.webkit.WebView#reload 876 */ 877 public abstract void setBlockNetworkLoads(boolean flag); 878 879 /** 880 * Gets whether the WebView does not load any resources from the network. 881 * 882 * @return true if the WebView does not load any resources from the network 883 * @see #setBlockNetworkLoads 884 */ 885 public abstract boolean getBlockNetworkLoads(); 886 887 /** 888 * Tells the WebView to enable JavaScript execution. 889 * <b>The default is false.</b> 890 * 891 * @param flag true if the WebView should execute JavaScript 892 */ 893 public abstract void setJavaScriptEnabled(boolean flag); 894 895 /** 896 * Sets whether JavaScript running in the context of a file scheme URL 897 * should be allowed to access content from any origin. This includes 898 * access to content from other file scheme URLs. See 899 * {@link #setAllowFileAccessFromFileURLs}. To enable the most restrictive, 900 * and therefore secure policy, this setting should be disabled. 901 * Note that this setting affects only JavaScript access to file scheme 902 * resources. Other access to such resources, for example, from image HTML 903 * elements, is unaffected. To prevent possible violation of same domain policy 904 * on {@link android.os.Build.VERSION_CODES#ICE_CREAM_SANDWICH} and earlier 905 * devices, you should explicitly set this value to {@code false}. 906 * <p> 907 * The default value is true for API level 908 * {@link android.os.Build.VERSION_CODES#ICE_CREAM_SANDWICH_MR1} and below, 909 * and false for API level {@link android.os.Build.VERSION_CODES#JELLY_BEAN} 910 * and above. 911 * 912 * @param flag whether JavaScript running in the context of a file scheme 913 * URL should be allowed to access content from any origin 914 */ 915 public abstract void setAllowUniversalAccessFromFileURLs(boolean flag); 916 917 /** 918 * Sets whether JavaScript running in the context of a file scheme URL 919 * should be allowed to access content from other file scheme URLs. To 920 * enable the most restrictive, and therefore secure policy, this setting 921 * should be disabled. Note that the value of this setting is ignored if 922 * the value of {@link #getAllowUniversalAccessFromFileURLs} is true. 923 * Note too, that this setting affects only JavaScript access to file scheme 924 * resources. Other access to such resources, for example, from image HTML 925 * elements, is unaffected. To prevent possible violation of same domain policy 926 * on {@link android.os.Build.VERSION_CODES#ICE_CREAM_SANDWICH} and earlier 927 * devices, you should explicitly set this value to {@code false}. 928 * <p> 929 * The default value is true for API level 930 * {@link android.os.Build.VERSION_CODES#ICE_CREAM_SANDWICH_MR1} and below, 931 * and false for API level {@link android.os.Build.VERSION_CODES#JELLY_BEAN} 932 * and above. 933 * 934 * @param flag whether JavaScript running in the context of a file scheme 935 * URL should be allowed to access content from other file 936 * scheme URLs 937 */ 938 public abstract void setAllowFileAccessFromFileURLs(boolean flag); 939 940 /** 941 * Sets whether the WebView should enable plugins. The default is false. 942 * 943 * @param flag true if plugins should be enabled 944 * @deprecated This method has been deprecated in favor of 945 * {@link #setPluginState} 946 * @hide Since API level {@link android.os.Build.VERSION_CODES#JELLY_BEAN_MR2} 947 */ 948 @SystemApi 949 @Deprecated 950 public abstract void setPluginsEnabled(boolean flag); 951 952 /** 953 * Tells the WebView to enable, disable, or have plugins on demand. On 954 * demand mode means that if a plugin exists that can handle the embedded 955 * content, a placeholder icon will be shown instead of the plugin. When 956 * the placeholder is clicked, the plugin will be enabled. The default is 957 * {@link PluginState#OFF}. 958 * 959 * @param state a PluginState value 960 * @deprecated Plugins will not be supported in future, and should not be used. 961 */ 962 @Deprecated 963 public abstract void setPluginState(PluginState state); 964 965 /** 966 * Sets a custom path to plugins used by the WebView. This method is 967 * obsolete since each plugin is now loaded from its own package. 968 * 969 * @param pluginsPath a String path to the directory containing plugins 970 * @deprecated This method is no longer used as plugins are loaded from 971 * their own APK via the system's package manager. 972 * @hide Since API level {@link android.os.Build.VERSION_CODES#JELLY_BEAN_MR2} 973 */ 974 @Deprecated 975 public void setPluginsPath(String pluginsPath) { 976 // Specified to do nothing, so no need for derived classes to override. 977 } 978 979 /** 980 * Sets the path to where database storage API databases should be saved. 981 * In order for the database storage API to function correctly, this method 982 * must be called with a path to which the application can write. This 983 * method should only be called once: repeated calls are ignored. 984 * 985 * @param databasePath a path to the directory where databases should be 986 * saved. 987 * @deprecated Database paths are managed by the implementation and calling this method 988 * will have no effect. 989 */ 990 // This will update WebCore when the Sync runs in the C++ side. 991 // Note that the WebCore Database Tracker only allows the path to be set 992 // once. 993 @Deprecated 994 public abstract void setDatabasePath(String databasePath); 995 996 /** 997 * Sets the path where the Geolocation databases should be saved. In order 998 * for Geolocation permissions and cached positions to be persisted, this 999 * method must be called with a path to which the application can write. 1000 * 1001 * @param databasePath a path to the directory where databases should be 1002 * saved. 1003 */ 1004 // This will update WebCore when the Sync runs in the C++ side. 1005 public abstract void setGeolocationDatabasePath(String databasePath); 1006 1007 /** 1008 * Sets whether the Application Caches API should be enabled. The default 1009 * is false. Note that in order for the Application Caches API to be 1010 * enabled, a valid database path must also be supplied to 1011 * {@link #setAppCachePath}. 1012 * 1013 * @param flag true if the WebView should enable Application Caches 1014 */ 1015 public abstract void setAppCacheEnabled(boolean flag); 1016 1017 /** 1018 * Sets the path to the Application Caches files. In order for the 1019 * Application Caches API to be enabled, this method must be called with a 1020 * path to which the application can write. This method should only be 1021 * called once: repeated calls are ignored. 1022 * 1023 * @param appCachePath a String path to the directory containing 1024 * Application Caches files. 1025 * @see #setAppCacheEnabled 1026 */ 1027 public abstract void setAppCachePath(String appCachePath); 1028 1029 /** 1030 * Sets the maximum size for the Application Cache content. The passed size 1031 * will be rounded to the nearest value that the database can support, so 1032 * this should be viewed as a guide, not a hard limit. Setting the 1033 * size to a value less than current database size does not cause the 1034 * database to be trimmed. The default size is {@link Long#MAX_VALUE}. 1035 * It is recommended to leave the maximum size set to the default value. 1036 * 1037 * @param appCacheMaxSize the maximum size in bytes 1038 * @deprecated In future quota will be managed automatically. 1039 */ 1040 @Deprecated 1041 public abstract void setAppCacheMaxSize(long appCacheMaxSize); 1042 1043 /** 1044 * Sets whether the database storage API is enabled. The default value is 1045 * false. See also {@link #setDatabasePath} for how to correctly set up the 1046 * database storage API. 1047 * 1048 * This setting is global in effect, across all WebView instances in a process. 1049 * Note you should only modify this setting prior to making <b>any</b> WebView 1050 * page load within a given process, as the WebView implementation may ignore 1051 * changes to this setting after that point. 1052 * 1053 * @param flag true if the WebView should use the database storage API 1054 */ 1055 public abstract void setDatabaseEnabled(boolean flag); 1056 1057 /** 1058 * Sets whether the DOM storage API is enabled. The default value is false. 1059 * 1060 * @param flag true if the WebView should use the DOM storage API 1061 */ 1062 public abstract void setDomStorageEnabled(boolean flag); 1063 1064 /** 1065 * Gets whether the DOM Storage APIs are enabled. 1066 * 1067 * @return true if the DOM Storage APIs are enabled 1068 * @see #setDomStorageEnabled 1069 */ 1070 public abstract boolean getDomStorageEnabled(); 1071 1072 /** 1073 * Gets the path to where database storage API databases are saved. 1074 * 1075 * @return the String path to the database storage API databases 1076 * @see #setDatabasePath 1077 * @deprecated Database paths are managed by the implementation this method is obsolete. 1078 */ 1079 @Deprecated 1080 public abstract String getDatabasePath(); 1081 1082 /** 1083 * Gets whether the database storage API is enabled. 1084 * 1085 * @return true if the database storage API is enabled 1086 * @see #setDatabaseEnabled 1087 */ 1088 public abstract boolean getDatabaseEnabled(); 1089 1090 /** 1091 * Sets whether Geolocation is enabled. The default is true. 1092 * <p> 1093 * Please note that in order for the Geolocation API to be usable 1094 * by a page in the WebView, the following requirements must be met: 1095 * <ul> 1096 * <li>an application must have permission to access the device location, 1097 * see {@link android.Manifest.permission#ACCESS_COARSE_LOCATION}, 1098 * {@link android.Manifest.permission#ACCESS_FINE_LOCATION}; 1099 * <li>an application must provide an implementation of the 1100 * {@link WebChromeClient#onGeolocationPermissionsShowPrompt} callback 1101 * to receive notifications that a page is requesting access to location 1102 * via the JavaScript Geolocation API. 1103 * </ul> 1104 * <p> 1105 * As an option, it is possible to store previous locations and web origin 1106 * permissions in a database. See {@link #setGeolocationDatabasePath}. 1107 * 1108 * @param flag whether Geolocation should be enabled 1109 */ 1110 public abstract void setGeolocationEnabled(boolean flag); 1111 1112 /** 1113 * Gets whether JavaScript is enabled. 1114 * 1115 * @return true if JavaScript is enabled 1116 * @see #setJavaScriptEnabled 1117 */ 1118 public abstract boolean getJavaScriptEnabled(); 1119 1120 /** 1121 * Gets whether JavaScript running in the context of a file scheme URL can 1122 * access content from any origin. This includes access to content from 1123 * other file scheme URLs. 1124 * 1125 * @return whether JavaScript running in the context of a file scheme URL 1126 * can access content from any origin 1127 * @see #setAllowUniversalAccessFromFileURLs 1128 */ 1129 public abstract boolean getAllowUniversalAccessFromFileURLs(); 1130 1131 /** 1132 * Gets whether JavaScript running in the context of a file scheme URL can 1133 * access content from other file scheme URLs. 1134 * 1135 * @return whether JavaScript running in the context of a file scheme URL 1136 * can access content from other file scheme URLs 1137 * @see #setAllowFileAccessFromFileURLs 1138 */ 1139 public abstract boolean getAllowFileAccessFromFileURLs(); 1140 1141 /** 1142 * Gets whether plugins are enabled. 1143 * 1144 * @return true if plugins are enabled 1145 * @see #setPluginsEnabled 1146 * @deprecated This method has been replaced by {@link #getPluginState} 1147 * @hide Since API level {@link android.os.Build.VERSION_CODES#JELLY_BEAN_MR2} 1148 */ 1149 @SystemApi 1150 @Deprecated 1151 public abstract boolean getPluginsEnabled(); 1152 1153 /** 1154 * Gets the current state regarding whether plugins are enabled. 1155 * 1156 * @return the plugin state as a {@link PluginState} value 1157 * @see #setPluginState 1158 * @deprecated Plugins will not be supported in future, and should not be used. 1159 */ 1160 @Deprecated 1161 public abstract PluginState getPluginState(); 1162 1163 /** 1164 * Gets the directory that contains the plugin libraries. This method is 1165 * obsolete since each plugin is now loaded from its own package. 1166 * 1167 * @return an empty string 1168 * @deprecated This method is no longer used as plugins are loaded from 1169 * their own APK via the system's package manager. 1170 * @hide Since API level {@link android.os.Build.VERSION_CODES#JELLY_BEAN_MR2} 1171 */ 1172 @Deprecated 1173 public String getPluginsPath() { 1174 // Unconditionally returns empty string, so no need for derived classes to override. 1175 return ""; 1176 } 1177 1178 /** 1179 * Tells JavaScript to open windows automatically. This applies to the 1180 * JavaScript function window.open(). The default is false. 1181 * 1182 * @param flag true if JavaScript can open windows automatically 1183 */ 1184 public abstract void setJavaScriptCanOpenWindowsAutomatically(boolean flag); 1185 1186 /** 1187 * Gets whether JavaScript can open windows automatically. 1188 * 1189 * @return true if JavaScript can open windows automatically during 1190 * window.open() 1191 * @see #setJavaScriptCanOpenWindowsAutomatically 1192 */ 1193 public abstract boolean getJavaScriptCanOpenWindowsAutomatically(); 1194 1195 /** 1196 * Sets the default text encoding name to use when decoding html pages. 1197 * The default is "UTF-8". 1198 * 1199 * @param encoding the text encoding name 1200 */ 1201 public abstract void setDefaultTextEncodingName(String encoding); 1202 1203 /** 1204 * Gets the default text encoding name. 1205 * 1206 * @return the default text encoding name as a string 1207 * @see #setDefaultTextEncodingName 1208 */ 1209 public abstract String getDefaultTextEncodingName(); 1210 1211 /** 1212 * Sets the WebView's user-agent string. If the string is null or empty, 1213 * the system default value will be used. 1214 * 1215 * Note that starting from {@link android.os.Build.VERSION_CODES#KITKAT} Android 1216 * version, changing the user-agent while loading a web page causes WebView 1217 * to initiate loading once again. 1218 * 1219 * @param ua new user-agent string 1220 */ 1221 public abstract void setUserAgentString(String ua); 1222 1223 /** 1224 * Gets the WebView's user-agent string. 1225 * 1226 * @return the WebView's user-agent string 1227 * @see #setUserAgentString 1228 */ 1229 public abstract String getUserAgentString(); 1230 1231 /** 1232 * Returns the default User-Agent used by a WebView. 1233 * An instance of WebView could use a different User-Agent if a call 1234 * is made to {@link WebSettings#setUserAgentString(String)}. 1235 * 1236 * @param context a Context object used to access application assets 1237 */ 1238 public static String getDefaultUserAgent(Context context) { 1239 return WebViewFactory.getProvider().getStatics().getDefaultUserAgent(context); 1240 } 1241 1242 /** 1243 * Tells the WebView whether it needs to set a node to have focus when 1244 * {@link WebView#requestFocus(int, android.graphics.Rect)} is called. The 1245 * default value is true. 1246 * 1247 * @param flag whether the WebView needs to set a node 1248 */ 1249 public abstract void setNeedInitialFocus(boolean flag); 1250 1251 /** 1252 * Sets the priority of the Render thread. Unlike the other settings, this 1253 * one only needs to be called once per process. The default value is 1254 * {@link RenderPriority#NORMAL}. 1255 * 1256 * @param priority the priority 1257 * @deprecated It is not recommended to adjust thread priorities, and this will 1258 * not be supported in future versions. 1259 */ 1260 @Deprecated 1261 public abstract void setRenderPriority(RenderPriority priority); 1262 1263 /** 1264 * Overrides the way the cache is used. The way the cache is used is based 1265 * on the navigation type. For a normal page load, the cache is checked 1266 * and content is re-validated as needed. When navigating back, content is 1267 * not revalidated, instead the content is just retrieved from the cache. 1268 * This method allows the client to override this behavior by specifying 1269 * one of {@link #LOAD_DEFAULT}, 1270 * {@link #LOAD_CACHE_ELSE_NETWORK}, {@link #LOAD_NO_CACHE} or 1271 * {@link #LOAD_CACHE_ONLY}. The default value is {@link #LOAD_DEFAULT}. 1272 * 1273 * @param mode the mode to use 1274 */ 1275 public abstract void setCacheMode(int mode); 1276 1277 /** 1278 * Gets the current setting for overriding the cache mode. 1279 * 1280 * @return the current setting for overriding the cache mode 1281 * @see #setCacheMode 1282 */ 1283 public abstract int getCacheMode(); 1284 1285 /** 1286 * Configures the WebView's behavior when a secure origin attempts to load a resource from an 1287 * insecure origin. 1288 * 1289 * By default, apps that target {@link android.os.Build.VERSION_CODES#KITKAT} or below default 1290 * to {@link #MIXED_CONTENT_ALWAYS_ALLOW}. Apps targeting 1291 * {@link android.os.Build.VERSION_CODES#LOLLIPOP} default to {@link #MIXED_CONTENT_NEVER_ALLOW}. 1292 * 1293 * The preferred and most secure mode of operation for the WebView is 1294 * {@link #MIXED_CONTENT_NEVER_ALLOW} and use of {@link #MIXED_CONTENT_ALWAYS_ALLOW} is 1295 * strongly discouraged. 1296 * 1297 * @param mode The mixed content mode to use. One of {@link #MIXED_CONTENT_NEVER_ALLOW}, 1298 * {@link #MIXED_CONTENT_ALWAYS_ALLOW} or {@link #MIXED_CONTENT_COMPATIBILITY_MODE}. 1299 */ 1300 public abstract void setMixedContentMode(int mode); 1301 1302 /** 1303 * Gets the current behavior of the WebView with regard to loading insecure content from a 1304 * secure origin. 1305 * @return The current setting, one of {@link #MIXED_CONTENT_NEVER_ALLOW}, 1306 * {@link #MIXED_CONTENT_ALWAYS_ALLOW} or {@link #MIXED_CONTENT_COMPATIBILITY_MODE}. 1307 */ 1308 public abstract int getMixedContentMode(); 1309 1310 /** 1311 * Sets whether to use a video overlay for embedded encrypted video. 1312 * In API levels prior to {@link android.os.Build.VERSION_CODES#LOLLIPOP}, encrypted video can 1313 * only be rendered directly on a secure video surface, so it had been a hard problem to play 1314 * encrypted video in HTML. When this flag is on, WebView can play encrypted video (MSE/EME) 1315 * by using a video overlay (aka hole-punching) for videos embedded using HTML <video> 1316 * tag.<br> 1317 * Caution: This setting is intended for use only in a narrow set of circumstances and apps 1318 * should only enable it if they require playback of encrypted video content. It will impose 1319 * the following limitations on the WebView: 1320 * <ul> 1321 * <li> Only one video overlay can be played at a time. 1322 * <li> Changes made to position or dimensions of a video element may be propagated to the 1323 * corresponding video overlay with a noticeable delay. 1324 * <li> The video overlay is not visible to web APIs and as such may not interact with 1325 * script or styling. For example, CSS styles applied to the <video> tag may be ignored. 1326 * </ul> 1327 * This is not an exhaustive set of constraints and it may vary with new versions of the 1328 * WebView. 1329 * @hide 1330 */ 1331 @SystemApi 1332 public abstract void setVideoOverlayForEmbeddedEncryptedVideoEnabled(boolean flag); 1333 1334 /** 1335 * Gets whether a video overlay will be used for embedded encrypted video. 1336 * 1337 * @return true if WebView uses a video overlay for embedded encrypted video. 1338 * @see #setVideoOverlayForEmbeddedEncryptedVideoEnabled 1339 * @hide 1340 */ 1341 @SystemApi 1342 public abstract boolean getVideoOverlayForEmbeddedEncryptedVideoEnabled(); 1343 1344 /** 1345 * Sets whether this WebView should raster tiles when it is 1346 * offscreen but attached to a window. Turning this on can avoid 1347 * rendering artifacts when animating an offscreen WebView on-screen. 1348 * Offscreen WebViews in this mode use more memory. The default value is 1349 * false.<br> 1350 * Please follow these guidelines to limit memory usage: 1351 * <ul> 1352 * <li> WebView size should be not be larger than the device screen size. 1353 * <li> Limit use of this mode to a small number of WebViews. Use it for 1354 * visible WebViews and WebViews about to be animated to visible. 1355 * </ul> 1356 */ 1357 public abstract void setOffscreenPreRaster(boolean enabled); 1358 1359 /** 1360 * Gets whether this WebView should raster tiles when it is 1361 * offscreen but attached to a window. 1362 * @return true if this WebView will raster tiles when it is 1363 * offscreen but attached to a window. 1364 */ 1365 public abstract boolean getOffscreenPreRaster(); 1366} 1367