PrintDocumentAdapter.java revision 85b1f883056a1d74473fd9ce774948878f389ab6 
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;
21
22import java.io.FileDescriptor;
23import java.util.List;
24
25/**
26 * Base class that provides the content of a document to be printed.
27 *
28 * <h3>Lifecycle</h3>
29 * <p>
30 * <ul>
31 * <li>
32 * Initially, you will receive a call to {@link #onStart()}. This callback
33 * can be used to allocate resources.
34 * </li>
35 * <li>
36 * Next, you will get one or more calls to {@link #onLayout(PrintAttributes,
37 * PrintAttributes, CancellationSignal, LayoutResultCallback, Bundle)} to
38 * inform you that the print attributes (page size, density, etc) changed
39 * giving you an opportunity to layout the content to match the new constraints.
40 * </li>
41 * <li>
42 * After every call to {@link #onLayout(PrintAttributes, PrintAttributes,
43 * CancellationSignal, LayoutResultCallback, Bundle)}, you may get a call to
44 * {@link #onWrite(PageRange[], FileDescriptor, CancellationSignal, WriteResultCallback)}
45 * asking you to write a PDF file with the content for specific pages.
46 * </li>
47 * <li>
48 * Finally, you will receive a call to {@link #onFinish()}. You can use this
49 * callback to release resources allocated in {@link #onStart()}.
50 * </li>
51 * </ul>
52 * </p>
53 * <h3>Implementation</h3>
54 * <p>
55 * The APIs defined in this class are designed to enable doing part or all
56 * of the work on an arbitrary thread. For example, if the printed content
57 * does not depend on the UI state, i.e. on what is shown on the screen, then
58 * you can off load the entire work on a dedicated thread, thus making your
59 * application interactive while the print work is being performed.
60 * </p>
61 * <p>
62 * You can also do work on different threads, for example if you print UI
63 * content, you can handle {@link #onStart()} and {@link #onLayout(PrintAttributes,
64 * PrintAttributes, CancellationSignal, LayoutResultCallback, Bundle)} on
65 * the UI thread (assuming onStart initializes resources needed for layout).
66 * This will ensure that the UI does not change while you are laying out the
67 * printed content. Then you can handle {@link #onWrite(PageRange[], FileDescriptor,
68 * CancellationSignal, WriteResultCallback)} and {@link #onFinish()} on another
69 * thread. This will ensure that the UI is frozen for the minimal amount of
70 * time. Also this assumes that you will generate the printed content in
71 * {@link #onLayout(PrintAttributes, PrintAttributes, CancellationSignal,
72 * LayoutResultCallback, Bundle)} which is not mandatory. If you use multiple
73 * threads, you are responsible for proper synchronization.
74 * </p>
75 */
76public abstract class PrintDocumentAdapter {
77
78    /**
79     * Meta-data key: mapped to a boolean value that is <code>true</code> if
80     * the current layout is for a print preview, <code>false</code> otherwise.
81     */
82    public static final String METADATA_KEY_PRINT_PREVIEW = "KEY_METADATA_PRINT_PREVIEW";
83
84    /**
85     * Called when printing starts. You can use this callback to allocate
86     * resources. This method is invoked on the main thread.
87     */
88    public void onStart() {
89        /* do nothing - stub */
90    }
91
92    /**
93     * Called when the print attributes (page size, density, etc) changed
94     * giving you a chance to layout the content such that it matches the
95     * new constraints. This method is invoked on the main thread.
96     * <p>
97     * After you are done laying out, you <strong>must</strong> invoke: {@link
98     * LayoutResultCallback#onLayoutFinished(PrintDocumentInfo, boolean)} with
99     * the last argument <code>true</code> or <code>false</code> depending on
100     * whether the layout changed the content or not, respectively; and {@link
101     * LayoutResultCallback#onLayoutFailed(CharSequence)}, if an error occurred.
102     * </p>
103     * <p>
104     * <strong>Note:</strong> If the content is large and a layout will be
105     * performed, it is a good practice to schedule the work on a dedicated
106     * thread and register an observer in the provided {@link
107     * CancellationSignal} upon invocation of which you should stop the
108     * layout. The cancellation callback will not be made on the main
109     * thread.
110     * </p>
111     *
112     * @param oldAttributes The old print attributes.
113     * @param newAttributes The new print attributes.
114     * @param cancellationSignal Signal for observing cancel layout requests.
115     * @param callback Callback to inform the system for the layout result.
116     * @param metadata Additional information about how layout the content.
117     *
118     * @see LayoutResultCallback
119     * @see CancellationSignal
120     * @see #METADATA_KEY_PRINT_PREVIEW
121     */
122    public abstract void onLayout(PrintAttributes oldAttributes, PrintAttributes newAttributes,
123            CancellationSignal cancellationSignal, LayoutResultCallback callback,
124            Bundle metadata);
125
126    /**
127     * Called when specific pages of the content should be written in the
128     * from of a PDF file to the given file descriptor. This method is invoked
129     * on the main thread.
130     *<p>
131     * After you are done writing, you should <strong>not</strong> close the
132     * file descriptor, rather you must invoke: {@link WriteResultCallback
133     * #onWriteFinished(List)}, if writing completed successfully; or {@link
134     * WriteResultCallback#onWriteFailed(CharSequence)}, if an error occurred.
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, FileDescriptor 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[], FileDescriptor, 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