}
/**
- * 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
- * requests with callbacks.
- * @param callback the callback to be invoked.
+ * @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.
*/
- 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) {
}
OSDN Git Service
