PrintDocumentAdapter.java revision a00271533f639c8ed36429c663889ac9f654bc72 
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.CancellationSignal;
20
21import java.io.FileDescriptor;
22import java.util.List;
23
24/**
25 * Base class that provides the content of a document to be printed.
26 *
27 * <h3>Lifecycle</h3>
28 * <p>
29 * <ul>
30 * <li>
31 * Initially, you will receive a call to {@link #onStart()}. This callback
32 * can be used to allocate resources.
33 * </li>
34 * <li>
35 * Next, you will get one or more calls to {@link #onLayout(PrintAttributes,
36 * PrintAttributes, CancellationSignal, LayoutResultCallback)} to inform you
37 * that the print attributes (page size, density, etc) changed giving you an
38 * opportunity to layout the content to match the new constraints.
39 * </li>
40 * <li>
41 * After every call to {@link #onLayout(PrintAttributes, PrintAttributes,
42 * CancellationSignal, LayoutResultCallback)}, you may get a call to {@link
43 * #onWrite(List, FileDescriptor, CancellationSignal, WriteResultCallback)}
44 * asking you to write a PDF file with the content for specific pages.
45 * </li>
46 * <li>
47 * Finally, you will receive a call to {@link #onFinish()}. You can use this
48 * callback to release resources allocated in {@link #onStart()}.
49 * </li>
50 * </ul>
51 * </p>
52 */
53public abstract class PrintDocumentAdapter {
54
55    /**
56     * Called when printing starts. You can use this callback to allocate
57     * resources. This method is invoked on the main thread.
58     */
59    public void onStart() {
60        /* do nothing - stub */
61    }
62
63    /**
64     * Called when the print attributes (page size, density, etc) changed
65     * giving you a chance to layout the content such that it matches the
66     * new constraints. This method is invoked on the main thread.
67     * <p>
68     * After you are done laying out, you must invoke: {@link LayoutResultCallback
69     * #onLayoutFinished(PrintDocumentInfo, boolean)} with the last argument <code>true
70     * </code> or <code>false</code> depending on whether the layout changed the
71     * content or not, respectively; and {@link LayoutResultCallback#onLayoutFailed(
72     * CharSequence), if an error occurred.
73     * </p>
74     * <p>
75     * <strong>Note:</strong> If the content is large and a layout will be
76     * performed, it is a good practice to schedule the work on a dedicated
77     * thread and register an observer in the provided {@link
78     * CancellationSignal} upon invocation of which you should stop the
79     * layout. The cancellation callback will not be made on the main
80     * thread.
81     * </p>
82     *
83     * @param oldAttributes The old print attributes.
84     * @param newAttributes The new print attributes.
85     * @param cancellationSignal Signal for observing cancel layout requests.
86     * @param callback Callback to inform the system for the layout result.
87     *
88     * @see LayoutResultCallback
89     * @see CancellationSignal
90     */
91    public abstract void onLayout(PrintAttributes oldAttributes, PrintAttributes newAttributes,
92            CancellationSignal cancellationSignal, LayoutResultCallback callback);
93
94    /**
95     * Called when specific pages of the content should be written in the
96     * from of a PDF file to the given file descriptor. This method is invoked
97     * on the main thread.
98     *<p>
99     * After you are done writing, you should <strong>not</strong> close the
100     * file descriptor, rather you must invoke: {@link WriteResultCallback
101     * #onWriteFinished()}, if writing completed successfully; or {@link
102     * WriteResultCallback#onWriteFailed(CharSequence)}, if an error occurred.
103     * </p>
104     * <p>
105     * <strong>Note:</strong> If the printed content is large, it is a good
106     * practice to schedule writing it on a dedicated thread and register an
107     * observer in the provided {@link CancellationSignal} upon invocation of
108     * which you should stop writing. The cancellation callback will not be
109     * made on the main thread.
110     * </p>
111     *
112     * @param pages The pages whose content to print.
113     * @param destination The destination file descriptor to which to write.
114     * @param cancellationSignal Signal for observing cancel writing requests.
115     * @param callback Callback to inform the system for the write result.
116     *
117     * @see WriteResultCallback
118     * @see CancellationSignal
119     */
120    public abstract void onWrite(List<PageRange> pages, FileDescriptor destination,
121            CancellationSignal cancellationSignal, WriteResultCallback callback);
122
123    /**
124     * Called when printing finishes. You can use this callback to release
125     * resources acquired in {@link #onStart()}. This method is invoked on
126     * the main thread.
127     */
128    public void onFinish() {
129        /* do nothing - stub */
130    }
131
132    /**
133     * Base class for implementing a callback for the result of {@link
134     * PrintDocumentAdapter#onWrite(List, FileDescriptor, CancellationSignal,
135     * WriteResultCallback)}.
136     */
137    public static abstract class WriteResultCallback {
138
139        /**
140         * @hide
141         */
142        public WriteResultCallback() {
143            /* do nothing - hide constructor */
144        }
145
146        /**
147         * Notifies that all the data was written.
148         *
149         * @param pages The pages that were written.
150         */
151        public void onWriteFinished(List<PageRange> pages) {
152            /* do nothing - stub */
153        }
154
155        /**
156         * Notifies that an error occurred while writing the data.
157         *
158         * @param error Error message. May be null if error is unknown.
159         */
160        public void onWriteFailed(CharSequence error) {
161            /* do nothing - stub */
162        }
163    }
164
165    /**
166     * Base class for implementing a callback for the result of {@link
167     * PrintDocumentAdapter#onLayout(PrintAttributes, PrintAttributes,
168     * CancellationSignal, LayoutResultCallback)}.
169     */
170    public static abstract class LayoutResultCallback {
171
172        /**
173         * @hide
174         */
175        public LayoutResultCallback() {
176            /* do nothing - hide constructor */
177        }
178
179        /**
180         * Notifies that the layout finished and whether the content changed.
181         *
182         * @param info An info object describing the document.
183         * @param changed Whether the layout changed.
184         *
185         * @see PrintDocumentInfo
186         */
187        public void onLayoutFinished(PrintDocumentInfo info, boolean changed) {
188            /* do nothing - stub */
189        }
190
191        /**
192         * Notifies that an error occurred while laying out the document.
193         *
194         * @param error Error message. May be null if error is unknown.
195         */
196        public void onLayoutFailed(CharSequence error) {
197            /* do nothing - stub */
198        }
199    }
200}
201