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