Merge "Improve documentation and rename insertVisualStateCallback to...

    }

    /**

     * Callback interface supplied to {@link #insertVisualStateCallback} for receiving

     * Callback interface supplied to {@link #postVisualStateCallback} for receiving

     * notifications about the visual state.

     */

    public static abstract class VisualStateCallback {

        /**

         * Invoked when the visual state is ready to be drawn in the next {@link #onDraw}.

         *

         * @param requestId the id supplied to the corresponding {@link #insertVisualStateCallback}

         * request

         * @param requestId The identifier passed to {@link #postVisualStateCallback} when this

         *                  callback was posted.

         */

        public abstract void onComplete(long requestId);

    }

    }

    /**

     * Inserts a {@link VisualStateCallback}.

     * Posts a {@link VisualStateCallback}, which will be called when

     * the current state of the WebView is ready to be drawn.

     *

     * <p>Updates to the the DOM are reflected asynchronously such that when the DOM is updated the

     * subsequent {@link WebView#onDraw} invocation might not reflect those updates. The

     * <p>Because updates to the the DOM are processed asynchronously, updates to the DOM may not

     * immediately be reflected visually by subsequent {@link WebView#onDraw} invocations. The

     * {@link VisualStateCallback} provides a mechanism to notify the caller when the contents of

     * the DOM at the current time are ready to be drawn the next time the {@link WebView} draws.

     * By current time we mean the time at which this API was called. The next draw after the

     * callback completes is guaranteed to reflect all the updates to the DOM applied before the

     * current time, but it may also contain updates applied after the current time.</p>

     * the DOM at the current time are ready to be drawn the next time the {@link WebView}

     * draws.</p>

     *

     * <p>The next draw after the callback completes is guaranteed to reflect all the updates to the

     * DOM up to the the point at which the {@link VisualStateCallback} was posted, but it may also

     * contain updates applied after the callback was posted.</p>

     *

     * <p>The state of the DOM covered by this API includes the following:

     * <ul>

     * {@link VisualStateCallback#onComplete} method.</li>

     * </ul></p>

     *

     * <p>When using this API it is also recommended to enable pre-rasterization if the

     * {@link WebView} is offscreen to avoid flickering. See WebSettings#setOffscreenPreRaster for

     * <p>When using this API it is also recommended to enable pre-rasterization if the {@link

     * WebView} is offscreen to avoid flickering. See {@link WebSettings#setOffscreenPreRaster} for

     * more details and do consider its caveats.</p>

     *

     * @param requestId an id that will be returned in the callback to allow callers to match

     * @param requestId An id that will be returned in the callback to allow callers to match

     *                  requests with callbacks.

     * @param callback the callback to be invoked.

     * @param callback  The callback to be invoked.

     */

    public void insertVisualStateCallback(long requestId, VisualStateCallback callback) {

    public void postVisualStateCallback(long requestId, VisualStateCallback callback) {

        checkThread();

        mProvider.insertVisualStateCallback(requestId, callback);

    }

    }

    /**

     * Notify the host application that the page commit is visible.

     * Notify the host application that {@link android.webkit.WebView} content left over from

     * previous page navigations will no longer be drawn.

     *

     * <p>This is the earliest point at which we can guarantee that the contents of the previously

     * loaded page will not longer be drawn in the next {@link WebView#onDraw}. The next draw will

     * render the {@link WebView#setBackgroundColor background color} of the WebView or some of the

     * contents from the committed page already. This callback may be useful when reusing

     * {@link WebView}s to ensure that no stale content is shown. This method is only called for

     * the main frame.</p>

     * <p>This callback can be used to determine the point at which it is safe to make a recycled

     * {@link android.webkit.WebView} visible, ensuring that no stale content is shown. It is called

     * at the earliest point at which it can be guaranteed that {@link WebView#onDraw} will no

     * longer draw any content from previous navigations. The next draw will display either the

     * {@link WebView#setBackgroundColor background color} of the {@link WebView}, or some of the

     * contents of the newly loaded page.

     *

     * <p>This method is called when the state of the DOM at the point at which the

     * body of the HTTP response (commonly the string of html) had started loading will be visible.

     * If you set a background color for the page in the HTTP response body this will most likely

     * be visible and perhaps some other elements. At that point no other resources had usually

     * been loaded, so you can expect images for example to not be visible. If you want

     * a finer level of granularity consider calling {@link WebView#insertVisualStateCallback}

     * directly.</p>

     * <p>This method is called when the body of the HTTP response has started loading, is reflected

     * in the DOM, and will be visible in subsequent draws. This callback occurs early in the

     * document loading process, and as such you should expect that linked resources (for example,

     * css and images) may not be available.</p>

     *

     * <p>Please note that all the conditions and recommendations presented in

     * {@link WebView#insertVisualStateCallback} also apply to this API.<p>

     * <p>For more fine-grained notification of visual state updates, see {@link

     * WebView#postVisualStateCallback}.</p>

     *

     * @param url the url of the committed page

     * <p>Please note that all the conditions and recommendations applicable to

     * {@link WebView#postVisualStateCallback} also apply to this API.<p>

     *

     * <p>This callback is only called for main frame navigations.</p>

     *

     * @param view The {@link android.webkit.WebView} for which the navigation occurred.

     * @param url  The URL corresponding to the page navigation that triggered this callback.

     */

    public void onPageCommitVisible(WebView view, String url) {

    }