| /* |
| * Copyright (C) 2020 The Android Open Source Project |
| * |
| * Licensed under the Apache License, Version 2.0 (the "License"); |
| * you may not use this file except in compliance with the License. |
| * You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| |
| package android.view; |
| |
| import android.annotation.NonNull; |
| import android.annotation.UiThread; |
| import android.graphics.Rect; |
| import android.os.CancellationSignal; |
| |
| import java.util.function.Consumer; |
| |
| /** |
| * A ScrollCaptureCallback is responsible for providing rendered snapshots of scrolling content for |
| * the scroll capture system. A single callback is responsible for providing support to a single |
| * scrolling UI element. At request time, the system will select the best candidate from among all |
| * callbacks registered within the window. |
| * <p> |
| * A callback is assigned to a View using {@link View#setScrollCaptureCallback}, or to the window as |
| * {@link Window#registerScrollCaptureCallback}. The point where the callback is registered defines |
| * the frame of reference for the bounds measurements used. |
| * <p> |
| * <b>Terminology</b> |
| * <dl> |
| * <dt>Containing View</dt> |
| * <dd>The view on which this callback is attached, or the root view of the window if the callback |
| * is assigned directly to a window.</dd> |
| * |
| * <dt>Scroll Bounds</dt> |
| * <dd>A rectangle which describes an area within the containing view where scrolling content |
| * appears. This may be the entire view or any rectangle within. This defines a frame of reference |
| * for requests as well as the width and maximum height of a single request.</dd> |
| * |
| * <dt>Scroll Delta</dt> |
| * <dd>The distance the scroll position has moved since capture started. Implementations are |
| * responsible for tracking changes in vertical scroll position during capture. This is required to |
| * map the capture area to the correct location, given the current scroll position. |
| * |
| * <dt>Capture Area</dt> |
| * <dd>A rectangle which describes the area to capture, relative to scroll bounds. The vertical |
| * position remains relative to the starting scroll position and any movement since ("Scroll Delta") |
| * should be subtracted to locate the correct local position, and scrolled into view as necessary. |
| * </dd> |
| * </dl> |
| * |
| * @see View#setScrollCaptureHint(int) |
| * @see View#setScrollCaptureCallback(ScrollCaptureCallback) |
| * @see Window#registerScrollCaptureCallback(ScrollCaptureCallback) |
| */ |
| @UiThread |
| public interface ScrollCaptureCallback { |
| |
| /** |
| * The system is searching for the appropriate scrolling container to capture and would like to |
| * know the size and position of scrolling content handled by this callback. |
| * <p> |
| * To determine scroll bounds, an implementation should inset the visible bounds of the |
| * containing view to cover only the area where scrolling content may be positioned. This |
| * should cover only the content which tracks with scrolling movement. |
| * <p> |
| * Return the updated rectangle to {@link Consumer#accept onReady.accept}. If for any reason the |
| * scrolling content is not available to capture, a empty rectangle may be returned which will |
| * exclude this view from consideration. |
| * <p> |
| * This request may be cancelled via the provided {@link CancellationSignal}. When this happens, |
| * any future call to {@link Consumer#accept onReady.accept} will have no effect and this |
| * content will be omitted from the search results. |
| * |
| * @param signal signal to cancel the operation in progress |
| * @param onReady consumer for the updated rectangle |
| */ |
| void onScrollCaptureSearch(@NonNull CancellationSignal signal, @NonNull Consumer<Rect> onReady); |
| |
| /** |
| * Scroll Capture has selected this callback to provide the scrolling image content. |
| * <p> |
| * {@link Runnable#run onReady.run} should be called when ready to begin handling image |
| * requests. |
| * <p> |
| * This request may be cancelled via the provided {@link CancellationSignal}. When this happens, |
| * any future call to {@link Runnable#run onReady.run} will have no effect and provided session |
| * will not be activated. |
| * |
| * @param session the current session, resources provided by it are valid for use until the |
| * {@link #onScrollCaptureEnd(Runnable) session ends} |
| * @param signal signal to cancel the operation in progress |
| * @param onReady signal used to report completion of the request |
| */ |
| void onScrollCaptureStart(@NonNull ScrollCaptureSession session, |
| @NonNull CancellationSignal signal, @NonNull Runnable onReady); |
| |
| /** |
| * An image capture has been requested from the scrolling content. |
| * <p> |
| * The requested rectangle describes an area inside the target view, relative to |
| * <code>scrollBounds</code>. The content may be offscreen, above or below the current visible |
| * portion of the target view. To handle the request, render the available portion of this |
| * rectangle to a buffer and return it via the Surface available from {@link |
| * ScrollCaptureSession#getSurface()}. |
| * <p> |
| * Note: Implementations are only required to render the requested content, and may do so into |
| * off-screen buffers without scrolling if they are able. |
| * <p> |
| * The resulting available portion of the request must be computed as a portion of {@code |
| * captureArea}, and sent to signal the operation is complete, using {@link Consumer#accept |
| * onComplete.accept}. If the requested rectangle is partially or fully out of bounds the |
| * resulting portion should be returned. If no portion is available (outside of available |
| * content), then skip sending any buffer and report an empty Rect as result. |
| * <p> |
| * This request may be cancelled via the provided {@link CancellationSignal}. When this happens, |
| * any future call to {@link Consumer#accept onComplete.accept} will be ignored until the next |
| * request. |
| * |
| * @param session the current session, resources provided by it are valid for use until the |
| * {@link #onScrollCaptureEnd(Runnable) session ends} |
| * @param signal signal to cancel the operation in progress |
| * @param captureArea the area to capture, a rectangle within {@code scrollBounds} |
| * @param onComplete a consumer for the captured area |
| */ |
| void onScrollCaptureImageRequest(@NonNull ScrollCaptureSession session, |
| @NonNull CancellationSignal signal, @NonNull Rect captureArea, |
| @NonNull Consumer<Rect> onComplete); |
| |
| /** |
| * Signals that capture has ended. Implementations should release any temporary resources or |
| * references to objects in use during the capture. Any resources obtained from the session are |
| * now invalid and attempts to use them after this point may throw an exception. |
| * <p> |
| * The window should be returned to its original state when capture started. At a minimum, the |
| * content should be scrolled to its original position. |
| * <p> |
| * {@link Runnable#run onReady.run} should be called as soon as possible after the window is |
| * ready for normal interactive use. After the callback (or after a timeout, if not called) the |
| * screenshot tool will be dismissed and the window may become visible to the user at any time. |
| * |
| * @param onReady a callback to inform the system that the application has completed any |
| * cleanup and is ready to become visible |
| */ |
| void onScrollCaptureEnd(@NonNull Runnable onReady); |
| } |
| |