[WebView] Improve documentation around full screen mode.

onShowCustomView and onHideCustomView are only used for full screen
support so we make that more explicit now (perhaps we should consider
rename and deprecate).

In M40 the WebView will also support full screen for non <video>
elements so we also consider that use case.

Change-Id: Ie4e245defbdd3e53bff98ac73305dd5e5e46334c

2 files changed, 26 insertions, 16 deletions

diff --git a/core/java/android/webkit/WebChromeClient.java b/core/java/android/webkit/WebChromeClient.java
index 768dc9f70ff6..4737e9be3f99 100644
--- a/core/java/android/webkit/WebChromeClient.java
+++ b/core/java/android/webkit/WebChromeClient.java
@@ -70,13 +70,14 @@ public class WebChromeClient {
     }
 
     /**
-     * Notify the host application that the current page would
-     * like to show a custom View.  This is used for Fullscreen
-     * video playback; see "HTML5 Video support" documentation on
+     * Notify the host application that the current page has entered full
+     * screen mode. The host application must show the custom View which
+     * contains the web contents — video or other HTML content —
+     * in full screen mode. Also see "Full screen support" documentation on
      * {@link WebView}.
      * @param view is the View object to be shown.
-     * @param callback is the callback to be invoked if and when the view
-     * is dismissed.
+     * @param callback invoke this callback to request the page to exit
+     * full screen mode.
      */
     public void onShowCustomView(View view, CustomViewCallback callback) {};
 
@@ -96,8 +97,10 @@ public class WebChromeClient {
             CustomViewCallback callback) {};
 
     /**
-     * Notify the host application that the current page would
-     * like to hide its custom view.
+     * Notify the host application that the current page has exited full
+     * screen mode. The host application must hide the custom View, ie. the
+     * View passed to {@link #onShowCustomView} when the content entered fullscreen.
+     * Also see "Full screen support" documentation on {@link WebView}.
      */
     public void onHideCustomView() {}
 
@@ -377,10 +380,9 @@ public class WebChromeClient {
     }
 
     /**
-     * When the user starts to playback a video element, it may take time for enough
-     * data to be buffered before the first frames can be rendered. While this buffering
-     * is taking place, the ChromeClient can use this function to provide a View to be
-     * displayed. For example, the ChromeClient could show a spinner animation.
+     * Obtains a View to be displayed while buffering of full screen video is taking
+     * place. The host application can override this method to provide a View
+     * containing a spinner or similar.
      *
      * @return View The View to be displayed whilst the video is loading.
      */
diff --git a/core/java/android/webkit/WebView.java b/core/java/android/webkit/WebView.java
index 3694863f72cf..cee6c8f4dd57 100644
--- a/core/java/android/webkit/WebView.java
+++ b/core/java/android/webkit/WebView.java
@@ -233,11 +233,19 @@ import java.util.Map;
  *
  * <h3>HTML5 Video support</h3>
  *
- * <p>In order to support inline HTML5 video in your application, you need to have hardware
- * acceleration turned on, and set a {@link android.webkit.WebChromeClient}. For full screen support,
- * implementations of {@link WebChromeClient#onShowCustomView(View, WebChromeClient.CustomViewCallback)}
- * and {@link WebChromeClient#onHideCustomView()} are required,
- * {@link WebChromeClient#getVideoLoadingProgressView()} is optional.
+ * <p>In order to support inline HTML5 video in your application you need to have hardware
+ * acceleration turned on.
+ * </p>
+ *
+ * <h3>Full screen support</h3>
+ *
+ * <p>In order to support full screen &mdash; for video or other HTML content &mdash; you need to set a
+ * {@link android.webkit.WebChromeClient} and implement both
+ * {@link WebChromeClient#onShowCustomView(View, WebChromeClient.CustomViewCallback)}
+ * and {@link WebChromeClient#onHideCustomView()}. If the implementation of either of these two methods is
+ * missing then the web contents will not be allowed to enter full screen. Optionally you can implement
+ * {@link WebChromeClient#getVideoLoadingProgressView()} to customize the View displayed whilst a video
+ * is loading.
  * </p>
  *
  * <h3>Layout size</h3>