1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
|
/*
* 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);
}
|
