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 17 package android.webkit; 18 19 import android.annotation.SystemApi; 20 import 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. 33 public 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. 904 * <p> 905 * The default value is true for API level 906 * {@link android.os.Build.VERSION_CODES#ICE_CREAM_SANDWICH_MR1} and below, 907 * and false for API level {@link android.os.Build.VERSION_CODES#JELLY_BEAN} 908 * and above. 909 * 910 * @param flag whether JavaScript running in the context of a file scheme 911 * URL should be allowed to access content from any origin 912 */ 913 public abstract void setAllowUniversalAccessFromFileURLs(boolean flag); 914 915 /** 916 * Sets whether JavaScript running in the context of a file scheme URL 917 * should be allowed to access content from other file scheme URLs. To 918 * enable the most restrictive, and therefore secure policy, this setting 919 * should be disabled. Note that the value of this setting is ignored if 920 * the value of {@link #getAllowUniversalAccessFromFileURLs} is true. 921 * Note too, that this setting affects only JavaScript access to file scheme 922 * resources. Other access to such resources, for example, from image HTML 923 * elements, is unaffected. 924 * <p> 925 * The default value is true for API level 926 * {@link android.os.Build.VERSION_CODES#ICE_CREAM_SANDWICH_MR1} and below, 927 * and false for API level {@link android.os.Build.VERSION_CODES#JELLY_BEAN} 928 * and above. 929 * 930 * @param flag whether JavaScript running in the context of a file scheme 931 * URL should be allowed to access content from other file 932 * scheme URLs 933 */ 934 public abstract void setAllowFileAccessFromFileURLs(boolean flag); 935 936 /** 937 * Sets whether the WebView should enable plugins. The default is false. 938 * 939 * @param flag true if plugins should be enabled 940 * @deprecated This method has been deprecated in favor of 941 * {@link #setPluginState} 942 * @hide Since API level {@link android.os.Build.VERSION_CODES#JELLY_BEAN_MR2} 943 */ 944 @SystemApi 945 @Deprecated 946 public abstract void setPluginsEnabled(boolean flag); 947 948 /** 949 * Tells the WebView to enable, disable, or have plugins on demand. On 950 * demand mode means that if a plugin exists that can handle the embedded 951 * content, a placeholder icon will be shown instead of the plugin. When 952 * the placeholder is clicked, the plugin will be enabled. The default is 953 * {@link PluginState#OFF}. 954 * 955 * @param state a PluginState value 956 * @deprecated Plugins will not be supported in future, and should not be used. 957 */ 958 @Deprecated 959 public abstract void setPluginState(PluginState state); 960 961 /** 962 * Sets a custom path to plugins used by the WebView. This method is 963 * obsolete since each plugin is now loaded from its own package. 964 * 965 * @param pluginsPath a String path to the directory containing plugins 966 * @deprecated This method is no longer used as plugins are loaded from 967 * their own APK via the system's package manager. 968 * @hide Since API level {@link android.os.Build.VERSION_CODES#JELLY_BEAN_MR2} 969 */ 970 @Deprecated 971 public void setPluginsPath(String pluginsPath) { 972 // Specified to do nothing, so no need for derived classes to override. 973 } 974 975 /** 976 * Sets the path to where database storage API databases should be saved. 977 * In order for the database storage API to function correctly, this method 978 * must be called with a path to which the application can write. This 979 * method should only be called once: repeated calls are ignored. 980 * 981 * @param databasePath a path to the directory where databases should be 982 * saved. 983 * @deprecated Database paths are managed by the implementation and calling this method 984 * will have no effect. 985 */ 986 // This will update WebCore when the Sync runs in the C++ side. 987 // Note that the WebCore Database Tracker only allows the path to be set 988 // once. 989 @Deprecated 990 public abstract void setDatabasePath(String databasePath); 991 992 /** 993 * Sets the path where the Geolocation databases should be saved. In order 994 * for Geolocation permissions and cached positions to be persisted, this 995 * method must be called with a path to which the application can write. 996 * 997 * @param databasePath a path to the directory where databases should be 998 * saved. 999 */ 1000 // This will update WebCore when the Sync runs in the C++ side. 1001 public abstract void setGeolocationDatabasePath(String databasePath); 1002 1003 /** 1004 * Sets whether the Application Caches API should be enabled. The default 1005 * is false. Note that in order for the Application Caches API to be 1006 * enabled, a valid database path must also be supplied to 1007 * {@link #setAppCachePath}. 1008 * 1009 * @param flag true if the WebView should enable Application Caches 1010 */ 1011 public abstract void setAppCacheEnabled(boolean flag); 1012 1013 /** 1014 * Sets the path to the Application Caches files. In order for the 1015 * Application Caches API to be enabled, this method must be called with a 1016 * path to which the application can write. This method should only be 1017 * called once: repeated calls are ignored. 1018 * 1019 * @param appCachePath a String path to the directory containing 1020 * Application Caches files. 1021 * @see #setAppCacheEnabled 1022 */ 1023 public abstract void setAppCachePath(String appCachePath); 1024 1025 /** 1026 * Sets the maximum size for the Application Cache content. The passed size 1027 * will be rounded to the nearest value that the database can support, so 1028 * this should be viewed as a guide, not a hard limit. Setting the 1029 * size to a value less than current database size does not cause the 1030 * database to be trimmed. The default size is {@link Long#MAX_VALUE}. 1031 * It is recommended to leave the maximum size set to the default value. 1032 * 1033 * @param appCacheMaxSize the maximum size in bytes 1034 * @deprecated In future quota will be managed automatically. 1035 */ 1036 @Deprecated 1037 public abstract void setAppCacheMaxSize(long appCacheMaxSize); 1038 1039 /** 1040 * Sets whether the database storage API is enabled. The default value is 1041 * false. See also {@link #setDatabasePath} for how to correctly set up the 1042 * database storage API. 1043 * 1044 * This setting is global in effect, across all WebView instances in a process. 1045 * Note you should only modify this setting prior to making <b>any</b> WebView 1046 * page load within a given process, as the WebView implementation may ignore 1047 * changes to this setting after that point. 1048 * 1049 * @param flag true if the WebView should use the database storage API 1050 */ 1051 public abstract void setDatabaseEnabled(boolean flag); 1052 1053 /** 1054 * Sets whether the DOM storage API is enabled. The default value is false. 1055 * 1056 * @param flag true if the WebView should use the DOM storage API 1057 */ 1058 public abstract void setDomStorageEnabled(boolean flag); 1059 1060 /** 1061 * Gets whether the DOM Storage APIs are enabled. 1062 * 1063 * @return true if the DOM Storage APIs are enabled 1064 * @see #setDomStorageEnabled 1065 */ 1066 public abstract boolean getDomStorageEnabled(); 1067 1068 /** 1069 * Gets the path to where database storage API databases are saved. 1070 * 1071 * @return the String path to the database storage API databases 1072 * @see #setDatabasePath 1073 * @deprecated Database paths are managed by the implementation this method is obsolete. 1074 */ 1075 @Deprecated 1076 public abstract String getDatabasePath(); 1077 1078 /** 1079 * Gets whether the database storage API is enabled. 1080 * 1081 * @return true if the database storage API is enabled 1082 * @see #setDatabaseEnabled 1083 */ 1084 public abstract boolean getDatabaseEnabled(); 1085 1086 /** 1087 * Sets whether Geolocation is enabled. The default is true. 1088 * <p> 1089 * Please note that in order for the Geolocation API to be usable 1090 * by a page in the WebView, the following requirements must be met: 1091 * <ul> 1092 * <li>an application must have permission to access the device location, 1093 * see {@link android.Manifest.permission#ACCESS_COARSE_LOCATION}, 1094 * {@link android.Manifest.permission#ACCESS_FINE_LOCATION}; 1095 * <li>an application must provide an implementation of the 1096 * {@link WebChromeClient#onGeolocationPermissionsShowPrompt} callback 1097 * to receive notifications that a page is requesting access to location 1098 * via the JavaScript Geolocation API. 1099 * </ul> 1100 * <p> 1101 * As an option, it is possible to store previous locations and web origin 1102 * permissions in a database. See {@link #setGeolocationDatabasePath}. 1103 * 1104 * @param flag whether Geolocation should be enabled 1105 */ 1106 public abstract void setGeolocationEnabled(boolean flag); 1107 1108 /** 1109 * Gets whether JavaScript is enabled. 1110 * 1111 * @return true if JavaScript is enabled 1112 * @see #setJavaScriptEnabled 1113 */ 1114 public abstract boolean getJavaScriptEnabled(); 1115 1116 /** 1117 * Gets whether JavaScript running in the context of a file scheme URL can 1118 * access content from any origin. This includes access to content from 1119 * other file scheme URLs. 1120 * 1121 * @return whether JavaScript running in the context of a file scheme URL 1122 * can access content from any origin 1123 * @see #setAllowUniversalAccessFromFileURLs 1124 */ 1125 public abstract boolean getAllowUniversalAccessFromFileURLs(); 1126 1127 /** 1128 * Gets whether JavaScript running in the context of a file scheme URL can 1129 * access content from other file scheme URLs. 1130 * 1131 * @return whether JavaScript running in the context of a file scheme URL 1132 * can access content from other file scheme URLs 1133 * @see #setAllowFileAccessFromFileURLs 1134 */ 1135 public abstract boolean getAllowFileAccessFromFileURLs(); 1136 1137 /** 1138 * Gets whether plugins are enabled. 1139 * 1140 * @return true if plugins are enabled 1141 * @see #setPluginsEnabled 1142 * @deprecated This method has been replaced by {@link #getPluginState} 1143 * @hide Since API level {@link android.os.Build.VERSION_CODES#JELLY_BEAN_MR2} 1144 */ 1145 @SystemApi 1146 @Deprecated 1147 public abstract boolean getPluginsEnabled(); 1148 1149 /** 1150 * Gets the current state regarding whether plugins are enabled. 1151 * 1152 * @return the plugin state as a {@link PluginState} value 1153 * @see #setPluginState 1154 * @deprecated Plugins will not be supported in future, and should not be used. 1155 */ 1156 @Deprecated 1157 public abstract PluginState getPluginState(); 1158 1159 /** 1160 * Gets the directory that contains the plugin libraries. This method is 1161 * obsolete since each plugin is now loaded from its own package. 1162 * 1163 * @return an empty string 1164 * @deprecated This method is no longer used as plugins are loaded from 1165 * their own APK via the system's package manager. 1166 * @hide Since API level {@link android.os.Build.VERSION_CODES#JELLY_BEAN_MR2} 1167 */ 1168 @Deprecated 1169 public String getPluginsPath() { 1170 // Unconditionally returns empty string, so no need for derived classes to override. 1171 return ""; 1172 } 1173 1174 /** 1175 * Tells JavaScript to open windows automatically. This applies to the 1176 * JavaScript function window.open(). The default is false. 1177 * 1178 * @param flag true if JavaScript can open windows automatically 1179 */ 1180 public abstract void setJavaScriptCanOpenWindowsAutomatically(boolean flag); 1181 1182 /** 1183 * Gets whether JavaScript can open windows automatically. 1184 * 1185 * @return true if JavaScript can open windows automatically during 1186 * window.open() 1187 * @see #setJavaScriptCanOpenWindowsAutomatically 1188 */ 1189 public abstract boolean getJavaScriptCanOpenWindowsAutomatically(); 1190 1191 /** 1192 * Sets the default text encoding name to use when decoding html pages. 1193 * The default is "UTF-8". 1194 * 1195 * @param encoding the text encoding name 1196 */ 1197 public abstract void setDefaultTextEncodingName(String encoding); 1198 1199 /** 1200 * Gets the default text encoding name. 1201 * 1202 * @return the default text encoding name as a string 1203 * @see #setDefaultTextEncodingName 1204 */ 1205 public abstract String getDefaultTextEncodingName(); 1206 1207 /** 1208 * Sets the WebView's user-agent string. If the string is null or empty, 1209 * the system default value will be used. 1210 */ 1211 public abstract void setUserAgentString(String ua); 1212 1213 /** 1214 * Gets the WebView's user-agent string. 1215 * 1216 * @return the WebView's user-agent string 1217 * @see #setUserAgentString 1218 */ 1219 public abstract String getUserAgentString(); 1220 1221 /** 1222 * Returns the default User-Agent used by a WebView. 1223 * An instance of WebView could use a different User-Agent if a call 1224 * is made to {@link WebSettings#setUserAgentString(String)}. 1225 * 1226 * @param context a Context object used to access application assets 1227 */ 1228 public static String getDefaultUserAgent(Context context) { 1229 return WebViewFactory.getProvider().getStatics().getDefaultUserAgent(context); 1230 } 1231 1232 /** 1233 * Tells the WebView whether it needs to set a node to have focus when 1234 * {@link WebView#requestFocus(int, android.graphics.Rect)} is called. The 1235 * default value is true. 1236 * 1237 * @param flag whether the WebView needs to set a node 1238 */ 1239 public abstract void setNeedInitialFocus(boolean flag); 1240 1241 /** 1242 * Sets the priority of the Render thread. Unlike the other settings, this 1243 * one only needs to be called once per process. The default value is 1244 * {@link RenderPriority#NORMAL}. 1245 * 1246 * @param priority the priority 1247 * @deprecated It is not recommended to adjust thread priorities, and this will 1248 * not be supported in future versions. 1249 */ 1250 @Deprecated 1251 public abstract void setRenderPriority(RenderPriority priority); 1252 1253 /** 1254 * Overrides the way the cache is used. The way the cache is used is based 1255 * on the navigation type. For a normal page load, the cache is checked 1256 * and content is re-validated as needed. When navigating back, content is 1257 * not revalidated, instead the content is just retrieved from the cache. 1258 * This method allows the client to override this behavior by specifying 1259 * one of {@link #LOAD_DEFAULT}, 1260 * {@link #LOAD_CACHE_ELSE_NETWORK}, {@link #LOAD_NO_CACHE} or 1261 * {@link #LOAD_CACHE_ONLY}. The default value is {@link #LOAD_DEFAULT}. 1262 * 1263 * @param mode the mode to use 1264 */ 1265 public abstract void setCacheMode(int mode); 1266 1267 /** 1268 * Gets the current setting for overriding the cache mode. 1269 * 1270 * @return the current setting for overriding the cache mode 1271 * @see #setCacheMode 1272 */ 1273 public abstract int getCacheMode(); 1274 1275 /** 1276 * Configures the WebView's behavior when a secure origin attempts to load a resource from an 1277 * insecure origin. 1278 * 1279 * By default, apps that target {@link android.os.Build.VERSION_CODES#KITKAT} or below default 1280 * to {@link #MIXED_CONTENT_ALWAYS_ALLOW}. Apps targeting 1281 * {@link android.os.Build.VERSION_CODES#LOLLIPOP} default to {@link #MIXED_CONTENT_NEVER_ALLOW}. 1282 * 1283 * The preferred and most secure mode of operation for the WebView is 1284 * {@link #MIXED_CONTENT_NEVER_ALLOW} and use of {@link #MIXED_CONTENT_ALWAYS_ALLOW} is 1285 * strongly discouraged. 1286 * 1287 * @param mode The mixed content mode to use. One of {@link #MIXED_CONTENT_NEVER_ALLOW}, 1288 * {@link #MIXED_CONTENT_NEVER_ALLOW} or {@link #MIXED_CONTENT_COMPATIBILITY_MODE}. 1289 */ 1290 public abstract void setMixedContentMode(int mode); 1291 1292 /** 1293 * Gets the current behavior of the WebView with regard to loading insecure content from a 1294 * secure origin. 1295 * @return The current setting, one of {@link #MIXED_CONTENT_NEVER_ALLOW}, 1296 * {@link #MIXED_CONTENT_NEVER_ALLOW} or {@link #MIXED_CONTENT_COMPATIBILITY_MODE}. 1297 */ 1298 public abstract int getMixedContentMode(); 1299 1300 /** 1301 * Sets whether to use a video overlay for embedded encrypted video. 1302 * In API levels prior to {@link android.os.Build.VERSION_CODES#LOLLIPOP}, encrypted video can 1303 * only be rendered directly on a secure video surface, so it had been a hard problem to play 1304 * encrypted video in HTML. When this flag is on, WebView can play encrypted video (MSE/EME) 1305 * by using a video overlay (aka hole-punching) for videos embedded using HTML <video> 1306 * tag.<br> 1307 * Caution: This setting is intended for use only in a narrow set of circumstances and apps 1308 * should only enable it if they require playback of encrypted video content. It will impose 1309 * the following limitations on the WebView: 1310 * <ul> 1311 * <li> Only one video overlay can be played at a time. 1312 * <li> Changes made to position or dimensions of a video element may be propagated to the 1313 * corresponding video overlay with a noticeable delay. 1314 * <li> The video overlay is not visible to web APIs and as such may not interact with 1315 * script or styling. For example, CSS styles applied to the <video> tag may be ignored. 1316 * </ul> 1317 * This is not an exhaustive set of constraints and it may vary with new versions of the 1318 * WebView. 1319 * @hide 1320 */ 1321 @SystemApi 1322 public abstract void setVideoOverlayForEmbeddedEncryptedVideoEnabled(boolean flag); 1323 1324 /** 1325 * Gets whether a video overlay will be used for embedded encrypted video. 1326 * 1327 * @return true if WebView uses a video overlay for embedded encrypted video. 1328 * @see #setVideoOverlayForEmbeddedEncryptedVideoEnabled 1329 * @hide 1330 */ 1331 @SystemApi 1332 public abstract boolean getVideoOverlayForEmbeddedEncryptedVideoEnabled(); 1333 } 1334