[WebView] Add a new flushVisualState API to AwContents.

android_webview/java/src/org/chromium/android_webview/AwContents.java

Index: android_webview/java/src/org/chromium/android_webview/AwContents.java
diff --git a/android_webview/java/src/org/chromium/android_webview/AwContents.java b/android_webview/java/src/org/chromium/android_webview/AwContents.java
index 4d80be73e6d07d234a2cfeef69823b3e5675638d..77fe602994e8332d3933af6f55a4429f5abf8f03 100644
--- a/android_webview/java/src/org/chromium/android_webview/AwContents.java
+++ b/android_webview/java/src/org/chromium/android_webview/AwContents.java
@@ -182,6 +182,15 @@ public class AwContents implements SmartClipProvider {
         }
     }
 
+    /**
+     * Callback used when flushing the visual state, see {@link #flushVisualState}.
+     */
+    @VisibleForTesting
+    public abstract static class VisualStateFlushCallback {
+        public abstract void onComplete();
+        public abstract void onFailure();
+    }
+
     private long mNativeAwContents;
     private final AwBrowserContext mBrowserContext;
     private ViewGroup mContainerView;
@@ -2020,6 +2029,21 @@ public class AwContents implements SmartClipProvider {
         if (!isDestroyed()) nativeSetJsOnlineProperty(mNativeAwContents, networkUp);
     }
 
+    /**
+     * Flush the visual state.
+     *
+     * Flushing the visual state means queuing a callback in Blink that will be invoked when the
+     * contents of the DOM tree at the moment that the callback was enqueued (or later) are drawn
+     * into the screen. In other words, the following events need to happen before the callback is
+     * invoked:
+     * 1. The DOM tree is committed becoming the pending tree - see ThreadProxy::BeginMainFrame
+     * 2. The pending tree is activated becoming the active tree
+     * 3. A frame swap happens that draws the active tree into the screen
+     */
+    public void flushVisualState(VisualStateFlushCallback callback) {
+        nativeFlushVisualState(mNativeAwContents, callback);
+    }
+
     //--------------------------------------------------------------------------------------------
     //  Methods called from native via JNI
     //--------------------------------------------------------------------------------------------
@@ -2123,6 +2147,28 @@ public class AwContents implements SmartClipProvider {
         mContentsClient.getCallbackHelper().postOnNewPicture(mPictureListenerContentProvider);
     }
 
+    /**
+     * Invokes the given {@link VisualStateFlushCallback}.
+     *
+     * @param result true if the flush request was successful and false otherwise
+     */
+    @CalledByNative
+    public static void flushVisualStateCallback(
+            final VisualStateFlushCallback callback, final boolean result) {
+        // Posting avoids invoking the callback inside invoking_composite_
+        // (see synchronous_compositor_impl.cc and crbug/452530).
+        new Handler().post(new Runnable() {

[mkosiba (inactive), 2015/01/27 22:07:20]

uh.. creating a new handler... could we maybe obtain the Handler from the
containerview and use that instead?

[boliu, 2015/01/30 01:45:42]

Let's keep this api fast and avoid any java allocation if possible, so should
get rid of the new Runnable as well.

In that sense apps needing to allocate a new VisualStateFlushCallback kinda
sucks too :(

I'm ok with filing a bug for this and fix it later, but definitely before we
ship.

[Ignacio Solla, 2015/02/05 16:00:38]

The Runnable will not be needed when we move to activations, so no point on
worrying about that (we already have a bug for that: crbug/452530).

I have filed crbug/455651 for the VisualStateFlushCallback

[Ignacio Solla, 2015/02/05 16:00:38]

Done.

+            @Override
+            public void run() {
+                if (result) {
+                    callback.onComplete();
+                } else {
+                    callback.onFailure();
+                }
+            }
+        });
+    }
+
     // Called as a result of nativeUpdateLastHitTestData.
     @CalledByNative
     private void updateHitTestData(
@@ -2688,6 +2734,8 @@ public class AwContents implements SmartClipProvider {
     private native long nativeGetAwDrawGLViewContext(long nativeAwContents);
     private native long nativeCapturePicture(long nativeAwContents, int width, int height);
     private native void nativeEnableOnNewPicture(long nativeAwContents, boolean enabled);
+    private native void nativeFlushVisualState(
+            long nativeAwContents, VisualStateFlushCallback callback);
     private native void nativeClearView(long nativeAwContents);
     private native void nativeSetExtraHeadersForUrl(long nativeAwContents,
             String url, String extraHeaders);