Clarify docs for WebView multiwindow settings.
Update the documentation for WebSettings to explain the special behavior
used when multiple window support is disabled, and to clarify that
in setJavaScriptCanOpenWindowsAutomatically, "automatically" means
"without a user gesture".
Test: m offline-sdk-docs
Flag: DOCS_ONLY
Change-Id: I0752e58f9145f7bda7c33a8f43929878bd08951b
diff --git a/core/java/android/webkit/WebSettings.java b/core/java/android/webkit/WebSettings.java
index d12eda3..fe26510 100644
--- a/core/java/android/webkit/WebSettings.java
+++ b/core/java/android/webkit/WebSettings.java
@@ -741,9 +741,17 @@
public abstract boolean getUseWideViewPort();
/**
- * Sets whether the WebView whether supports multiple windows. If set to
- * true, {@link WebChromeClient#onCreateWindow} must be implemented by the
- * host application. The default is {@code false}.
+ * Sets whether the WebView should support multiple windows.
+ *
+ * <p>If set to {@code true}, the {@link WebChromeClient#onCreateWindow}
+ * callback must be implemented by the application to handle the
+ * creation of new windows.
+ *
+ * <p>The default is {@code false}. When multiple window support is disabled,
+ * requests to open new windows (either from the {@code window.open()}
+ * JavaScript API or from links with {@code target="_blank"}) will instead
+ * be treated as top-level navigations, replacing the current page in the
+ * same WebView.
*
* @param support whether to support multiple windows
*/
@@ -1338,18 +1346,24 @@
}
/**
- * Tells JavaScript to open windows automatically. This applies to the
- * JavaScript function {@code window.open()}. The default is {@code false}.
+ * Allows JavaScript to open windows without a user gesture. This applies to
+ * the JavaScript function {@code window.open()}. The default is
+ * {@code false}: attempts without a user gesture will fail and do nothing.
+ * <p>
+ * This is not affected by the {@link #setSupportMultipleWindows} setting;
+ * the user gesture requirement is enforced even if multiple windows are
+ * disabled.
*
- * @param flag {@code true} if JavaScript can open windows automatically
+ * @param flag {@code true} if JavaScript can open windows without a user
+ * gesture.
*/
public abstract void setJavaScriptCanOpenWindowsAutomatically(boolean flag);
/**
- * Gets whether JavaScript can open windows automatically.
+ * Gets whether JavaScript can open windows without a user gesture.
*
- * @return {@code true} if JavaScript can open windows automatically during
- * {@code window.open()}
+ * @return {@code true} if JavaScript can open windows without a user
+ * gesture using {@code window.open()}
* @see #setJavaScriptCanOpenWindowsAutomatically
*/
public abstract boolean getJavaScriptCanOpenWindowsAutomatically();