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
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
|
/*
* Copyright (C) 2013 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.print;
import android.os.Bundle;
import android.os.CancellationSignal;
import android.os.ParcelFileDescriptor;
import java.util.List;
/**
* Base class that provides the content of a document to be printed.
*
* <h3>Lifecycle</h3>
* <p>
* <ul>
* <li>
* Initially, you will receive a call to {@link #onStart()}. This callback
* can be used to allocate resources.
* </li>
* <li>
* Next, you will get one or more calls to {@link #onLayout(PrintAttributes,
* PrintAttributes, CancellationSignal, LayoutResultCallback, Bundle)} to
* inform you that the print attributes (page size, density, etc) changed
* giving you an opportunity to layout the content to match the new constraints.
* </li>
* <li>
* After every call to {@link #onLayout(PrintAttributes, PrintAttributes,
* CancellationSignal, LayoutResultCallback, Bundle)}, you may get a call to
* {@link #onWrite(PageRange[], ParcelFileDescriptor, CancellationSignal, WriteResultCallback)}
* asking you to write a PDF file with the content for specific pages.
* </li>
* <li>
* Finally, you will receive a call to {@link #onFinish()}. You can use this
* callback to release resources allocated in {@link #onStart()}.
* </li>
* </ul>
* </p>
* <h3>Implementation</h3>
* <p>
* The APIs defined in this class are designed to enable doing part or all
* of the work on an arbitrary thread. For example, if the printed content
* does not depend on the UI state, i.e. on what is shown on the screen, then
* you can off load the entire work on a dedicated thread, thus making your
* application interactive while the print work is being performed.
* </p>
* <p>
* You can also do work on different threads, for example if you print UI
* content, you can handle {@link #onStart()} and {@link #onLayout(PrintAttributes,
* PrintAttributes, CancellationSignal, LayoutResultCallback, Bundle)} on
* the UI thread (assuming onStart initializes resources needed for layout).
* This will ensure that the UI does not change while you are laying out the
* printed content. Then you can handle {@link #onWrite(PageRange[], ParcelFileDescriptor,
* CancellationSignal, WriteResultCallback)} and {@link #onFinish()} on another
* thread. This will ensure that the UI is frozen for the minimal amount of
* time. Also this assumes that you will generate the printed content in
* {@link #onLayout(PrintAttributes, PrintAttributes, CancellationSignal,
* LayoutResultCallback, Bundle)} which is not mandatory. If you use multiple
* threads, you are responsible for proper synchronization.
* </p>
*/
public abstract class PrintDocumentAdapter {
/**
* Meta-data key: mapped to a boolean value that is <code>true</code> if
* the current layout is for a print preview, <code>false</code> otherwise.
*/
public static final String METADATA_KEY_PRINT_PREVIEW = "KEY_METADATA_PRINT_PREVIEW";
/**
* Called when printing starts. You can use this callback to allocate
* resources. This method is invoked on the main thread.
*/
public void onStart() {
/* do nothing - stub */
}
/**
* Called when the print attributes (page size, density, etc) changed
* giving you a chance to layout the content such that it matches the
* new constraints. This method is invoked on the main thread.
* <p>
* After you are done laying out, you <strong>must</strong> invoke: {@link
* LayoutResultCallback#onLayoutFinished(PrintDocumentInfo, boolean)} with
* the last argument <code>true</code> or <code>false</code> depending on
* whether the layout changed the content or not, respectively; and {@link
* LayoutResultCallback#onLayoutFailed(CharSequence)}, if an error occurred.
* </p>
* <p>
* When doing a layout you may satisfy some of the constraints in the print
* attributes such as applying the appropriate fitting, emitting content in the
* requested orientation, using the specified margins, generating content with
* the desired color mode, producing output with the given media size. Ideally,
* you will satisfy all of these constraints. It is important that if you
* satisfy a given constraint, you update the {@link PrintDocumentInfo} that
* is returned in the given {@link LayoutResultCallback}. This way the printer
* will have more accurate information about the content, thus producing a
* better output. For example, assume that your application is printing
* an image and the print attributes request landscape and fitting mode scale
* to fill. The result of this operation should be the entire media is filled
* and the content is rotated ninety degrees. In this case it is beneficial
* you do the rotation and select a higher resolution image to utilize
* the wider media (the height is now the width), rather to use a lower
* resolution image that is later stretched by the printer. If you applied
* the rotation you have to update the returned print document info to
* reflect that the content is already in landscape by calling
* {@link PrintDocumentInfo.Builder#setOrientation(int)} with {@link
* PrintAttributes#ORIENTATION_LANDSCAPE}. In this case the printer does not
* have to rotate the content.
* </p>
* <p>
* <strong>Note:</strong> If the content is large and a layout will be
* performed, it is a good practice to schedule the work on a dedicated
* thread and register an observer in the provided {@link
* CancellationSignal} upon invocation of which you should stop the
* layout. The cancellation callback will not be made on the main
* thread.
* </p>
*
* @param oldAttributes The old print attributes.
* @param newAttributes The new print attributes.
* @param cancellationSignal Signal for observing cancel layout requests.
* @param callback Callback to inform the system for the layout result.
* @param metadata Additional information about how layout the content.
*
* @see LayoutResultCallback
* @see CancellationSignal
* @see #METADATA_KEY_PRINT_PREVIEW
*/
public abstract void onLayout(PrintAttributes oldAttributes, PrintAttributes newAttributes,
CancellationSignal cancellationSignal, LayoutResultCallback callback,
Bundle metadata);
/**
* Called when specific pages of the content should be written in the
* from of a PDF file to the given file descriptor. This method is invoked
* on the main thread.
*<p>
* After you are done writing, you should close the file descriptor and
* invoke {@link WriteResultCallback #onWriteFinished(List)}, if writing
* completed successfully; or {@link WriteResultCallback#onWriteFailed(
* CharSequence)}, if an error occurred.
* </p>
* <p>
* <strong>Note:</strong> If the printed content is large, it is a good
* practice to schedule writing it on a dedicated thread and register an
* observer in the provided {@link CancellationSignal} upon invocation of
* which you should stop writing. The cancellation callback will not be
* made on the main thread.
* </p>
*
* @param pages The pages whose content to print - non-overlapping in ascending order.
* @param destination The destination file descriptor to which to write.
* @param cancellationSignal Signal for observing cancel writing requests.
* @param callback Callback to inform the system for the write result.
*
* @see WriteResultCallback
* @see CancellationSignal
*/
public abstract void onWrite(PageRange[] pages, ParcelFileDescriptor destination,
CancellationSignal cancellationSignal, WriteResultCallback callback);
/**
* Called when printing finishes. You can use this callback to release
* resources acquired in {@link #onStart()}. This method is invoked on
* the main thread.
*/
public void onFinish() {
/* do nothing - stub */
}
/**
* Base class for implementing a callback for the result of {@link
* PrintDocumentAdapter#onWrite(PageRange[], ParcelFileDescriptor, CancellationSignal,
* WriteResultCallback)}.
*/
public static abstract class WriteResultCallback {
/**
* @hide
*/
public WriteResultCallback() {
/* do nothing - hide constructor */
}
/**
* Notifies that all the data was written.
*
* @param pages The pages that were written. Cannot be null or empty.
*/
public void onWriteFinished(PageRange[] pages) {
/* do nothing - stub */
}
/**
* Notifies that an error occurred while writing the data.
*
* @param error Error message. May be null if error is unknown.
*/
public void onWriteFailed(CharSequence error) {
/* do nothing - stub */
}
/**
* Notifies that write was cancelled as a result of a cancellation request.
*/
public void onWriteCancelled() {
/* do nothing - stub */
}
}
/**
* Base class for implementing a callback for the result of {@link
* PrintDocumentAdapter#onLayout(PrintAttributes, PrintAttributes,
* CancellationSignal, LayoutResultCallback, Bundle)}.
*/
public static abstract class LayoutResultCallback {
/**
* @hide
*/
public LayoutResultCallback() {
/* do nothing - hide constructor */
}
/**
* Notifies that the layout finished and whether the content changed.
*
* @param info An info object describing the document. Cannot be null.
* @param changed Whether the layout changed.
*
* @see PrintDocumentInfo
*/
public void onLayoutFinished(PrintDocumentInfo info, boolean changed) {
/* do nothing - stub */
}
/**
* Notifies that an error occurred while laying out the document.
*
* @param error Error message. May be null if error is unknown.
*/
public void onLayoutFailed(CharSequence error) {
/* do nothing - stub */
}
/**
* Notifies that layout was cancelled as a result of a cancellation request.
*/
public void onLayoutCancelled() {
/* do nothing - stub */
}
}
}
|