PrintDocumentAdapter.java revision c6066799ad130140159230d14451b429eb828755 
1/*
2 * Copyright (C) 2013 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package android.print;
18
19import android.os.Bundle;
20import android.os.CancellationSignal;
21import android.os.ParcelFileDescriptor;
22
23/**
24 * Base class that provides the content of a document to be printed.
25 *
26 * <h3>Lifecycle</h3>
27 * <p>
28 * <ul>
29 * <li>
30 * Initially, you will receive a call to {@link #onStart()}. This callback
31 * can be used to allocate resources.
32 * </li>
33 * <li>
34 * Next, you will get one or more calls to {@link #onLayout(PrintAttributes,
35 * PrintAttributes, CancellationSignal, LayoutResultCallback, Bundle)} to
36 * inform you that the print attributes (page size, density, etc) changed
37 * giving you an opportunity to layout the content to match the new constraints.
38 * </li>
39 * <li>
40 * After every call to {@link #onLayout(PrintAttributes, PrintAttributes,
41 * CancellationSignal, LayoutResultCallback, Bundle)}, you may get a call to
42 * {@link #onWrite(PageRange[], ParcelFileDescriptor, CancellationSignal, WriteResultCallback)}
43 * asking you to write a PDF file with the content for specific pages.
44 * </li>
45 * <li>
46 * Finally, you will receive a call to {@link #onFinish()}. You can use this
47 * callback to release resources allocated in {@link #onStart()}.
48 * </li>
49 * </ul>
50 * </p>
51 * <h3>Implementation</h3>
52 * <p>
53 * The APIs defined in this class are designed to enable doing part or all
54 * of the work on an arbitrary thread. For example, if the printed content
55 * does not depend on the UI state, i.e. on what is shown on the screen, then
56 * you can offload the entire work on a dedicated thread, thus making your
57 * application interactive while the print work is being performed.
58 * </p>
59 * <p>
60 * You can also do work on different threads, for example if you print UI
61 * content, you can handle {@link #onStart()} and {@link #onLayout(PrintAttributes,
62 * PrintAttributes, CancellationSignal, LayoutResultCallback, Bundle)} on
63 * the UI thread (assuming onStart initializes resources needed for layout).
64 * This will ensure that the UI does not change while you are laying out the
65 * printed content. Then you can handle {@link #onWrite(PageRange[], ParcelFileDescriptor,
66 * CancellationSignal, WriteResultCallback)} and {@link #onFinish()} on another
67 * thread. This will ensure that the UI is frozen for the minimal amount of
68 * time. Also this assumes that you will generate the printed content in
69 * {@link #onLayout(PrintAttributes, PrintAttributes, CancellationSignal,
70 * LayoutResultCallback, Bundle)} which is not mandatory. If you use multiple
71 * threads, you are responsible for proper synchronization.
72 * </p>
73 */
74public abstract class PrintDocumentAdapter {
75
76    /**
77     * Meta-data key: mapped to a boolean value that is <code>true</code> if
78     * the current layout is for a print preview, <code>false</code> otherwise.
79     */
80    public static final String METADATA_KEY_PRINT_PREVIEW = "KEY_METADATA_PRINT_PREVIEW";
81
82    /**
83     * Called when printing starts. You can use this callback to allocate
84     * resources. This method is invoked on the main thread.
85     */
86    public void onStart() {
87        /* do nothing - stub */
88    }
89
90    /**
91     * Called when the print attributes (page size, density, etc) changed
92     * giving you a chance to layout the content such that it matches the
93     * new constraints. This method is invoked on the main thread.
94     * <p>
95     * After you are done laying out, you <strong>must</strong> invoke: {@link
96     * LayoutResultCallback#onLayoutFinished(PrintDocumentInfo, boolean)} with
97     * the last argument <code>true</code> or <code>false</code> depending on
98     * whether the layout changed the content or not, respectively; and {@link
99     * LayoutResultCallback#onLayoutFailed(CharSequence)}, if an error occurred.
100     * Note that you must call one of the methods of the given callback.
101     * </p>
102     * <p>
103     * <strong>Note:</strong> If the content is large and a layout will be
104     * performed, it is a good practice to schedule the work on a dedicated
105     * thread and register an observer in the provided {@link
106     * CancellationSignal} upon invocation of which you should stop the
107     * layout. The cancellation callback will not be made on the main
108     * thread.
109     * </p>
110     *
111     * @param oldAttributes The old print attributes.
112     * @param newAttributes The new print attributes.
113     * @param cancellationSignal Signal for observing cancel layout requests.
114     * @param callback Callback to inform the system for the layout result.
115     * @param metadata Additional information about how layout the content.
116     *
117     * @see LayoutResultCallback
118     * @see CancellationSignal
119     * @see #METADATA_KEY_PRINT_PREVIEW
120     */
121    public abstract void onLayout(PrintAttributes oldAttributes, PrintAttributes newAttributes,
122            CancellationSignal cancellationSignal, LayoutResultCallback callback,
123            Bundle metadata);
124
125    /**
126     * Called when specific pages of the content should be written in the
127     * form of a PDF file to the given file descriptor. This method is invoked
128     * on the main thread.
129     *<p>
130     * After you are done writing, you should close the file descriptor and
131     * invoke {@link WriteResultCallback #onWriteFinished(PageRange[]), if writing
132     * completed successfully; or {@link WriteResultCallback#onWriteFailed(
133     * CharSequence)}, if an error occurred. Note that you must call one of
134     * the methods of the given callback.
135     * </p>
136     * <p>
137     * <strong>Note:</strong> If the printed content is large, it is a good
138     * practice to schedule writing it on a dedicated thread and register an
139     * observer in the provided {@link CancellationSignal} upon invocation of
140     * which you should stop writing. The cancellation callback will not be
141     * made on the main thread.
142     * </p>
143     *
144     * @param pages The pages whose content to print - non-overlapping in ascending order.
145     * @param destination The destination file descriptor to which to write.
146     * @param cancellationSignal Signal for observing cancel writing requests.
147     * @param callback Callback to inform the system for the write result.
148     *
149     * @see WriteResultCallback
150     * @see CancellationSignal
151     */
152    public abstract void onWrite(PageRange[] pages, ParcelFileDescriptor destination,
153            CancellationSignal cancellationSignal, WriteResultCallback callback);
154
155    /**
156     * Called when printing finishes. You can use this callback to release
157     * resources acquired in {@link #onStart()}. This method is invoked on
158     * the main thread.
159     */
160    public void onFinish() {
161        /* do nothing - stub */
162    }
163
164    /**
165     * Base class for implementing a callback for the result of {@link
166     * PrintDocumentAdapter#onWrite(PageRange[], ParcelFileDescriptor, CancellationSignal,
167     * WriteResultCallback)}.
168     */
169    public static abstract class WriteResultCallback {
170
171        /**
172         * @hide
173         */
174        public WriteResultCallback() {
175            /* do nothing - hide constructor */
176        }
177
178        /**
179         * Notifies that all the data was written.
180         *
181         * @param pages The pages that were written. Cannot be null or empty.
182         */
183        public void onWriteFinished(PageRange[] pages) {
184            /* do nothing - stub */
185        }
186
187        /**
188         * Notifies that an error occurred while writing the data.
189         *
190         * @param error Error message. May be null if error is unknown.
191         */
192        public void onWriteFailed(CharSequence error) {
193            /* do nothing - stub */
194        }
195
196        /**
197         * Notifies that write was cancelled as a result of a cancellation request.
198         */
199        public void onWriteCancelled() {
200            /* do nothing - stub */
201        }
202    }
203
204    /**
205     * Base class for implementing a callback for the result of {@link
206     * PrintDocumentAdapter#onLayout(PrintAttributes, PrintAttributes,
207     * CancellationSignal, LayoutResultCallback, Bundle)}.
208     */
209    public static abstract class LayoutResultCallback {
210
211        /**
212         * @hide
213         */
214        public LayoutResultCallback() {
215            /* do nothing - hide constructor */
216        }
217
218        /**
219         * Notifies that the layout finished and whether the content changed.
220         *
221         * @param info An info object describing the document. Cannot be null.
222         * @param changed Whether the layout changed.
223         *
224         * @see PrintDocumentInfo
225         */
226        public void onLayoutFinished(PrintDocumentInfo info, boolean changed) {
227            /* do nothing - stub */
228        }
229
230        /**
231         * Notifies that an error occurred while laying out the document.
232         *
233         * @param error Error message. May be null if error is unknown.
234         */
235        public void onLayoutFailed(CharSequence error) {
236            /* do nothing - stub */
237        }
238
239        /**
240         * Notifies that layout was cancelled as a result of a cancellation request.
241         */
242        public void onLayoutCancelled() {
243            /* do nothing - stub */
244        }
245    }
246}
247