1a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov/* 2a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * Copyright (C) 2013 The Android Open Source Project 3a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * 4a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * Licensed under the Apache License, Version 2.0 (the "License"); 5a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * you may not use this file except in compliance with the License. 6a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * You may obtain a copy of the License at 7a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * 8a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * http://www.apache.org/licenses/LICENSE-2.0 9a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * 10a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * Unless required by applicable law or agreed to in writing, software 11a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * distributed under the License is distributed on an "AS IS" BASIS, 12a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * See the License for the specific language governing permissions and 14a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * limitations under the License. 15a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov */ 16a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov 17a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganovpackage android.print; 18a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov 196283608e0bd40548742839f5a8b02f7e5c9c5c7cSvetoslavimport android.os.Bundle; 20a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganovimport android.os.CancellationSignal; 21d26d4898fcc9b78f4b66118895c375384098205eSvetoslav Ganovimport android.os.ParcelFileDescriptor; 22a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov 23a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov/** 24a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * Base class that provides the content of a document to be printed. 25a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * 26a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * <h3>Lifecycle</h3> 27a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * <p> 28a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * <ul> 29a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * <li> 30a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * Initially, you will receive a call to {@link #onStart()}. This callback 31a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * can be used to allocate resources. 32a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * </li> 33a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * <li> 34a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * Next, you will get one or more calls to {@link #onLayout(PrintAttributes, 356283608e0bd40548742839f5a8b02f7e5c9c5c7cSvetoslav * PrintAttributes, CancellationSignal, LayoutResultCallback, Bundle)} to 366283608e0bd40548742839f5a8b02f7e5c9c5c7cSvetoslav * inform you that the print attributes (page size, density, etc) changed 376283608e0bd40548742839f5a8b02f7e5c9c5c7cSvetoslav * giving you an opportunity to layout the content to match the new constraints. 38a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * </li> 39a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * <li> 40a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * After every call to {@link #onLayout(PrintAttributes, PrintAttributes, 414d4c66dd38e940082e385b49a33f4022ab04c738Svetoslav Ganov * CancellationSignal, LayoutResultCallback, Bundle)}, you <strong>may</strong> get 424d4c66dd38e940082e385b49a33f4022ab04c738Svetoslav Ganov * a call to {@link #onWrite(PageRange[], ParcelFileDescriptor, CancellationSignal, 434d4c66dd38e940082e385b49a33f4022ab04c738Svetoslav Ganov * WriteResultCallback)} asking you to write a PDF file with the content for 444d4c66dd38e940082e385b49a33f4022ab04c738Svetoslav Ganov * specific pages. 45a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * </li> 46a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * <li> 47a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * Finally, you will receive a call to {@link #onFinish()}. You can use this 48a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * callback to release resources allocated in {@link #onStart()}. 49a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * </li> 50a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * </ul> 514d4c66dd38e940082e385b49a33f4022ab04c738Svetoslav Ganov * <p> 524d4c66dd38e940082e385b49a33f4022ab04c738Svetoslav Ganov * The {@link #onStart()} callback is always the first call you will receive and 534d4c66dd38e940082e385b49a33f4022ab04c738Svetoslav Ganov * is useful for doing one time setup or resource allocation before printing. You 544d4c66dd38e940082e385b49a33f4022ab04c738Svetoslav Ganov * will not receive a subsequent call here. 554d4c66dd38e940082e385b49a33f4022ab04c738Svetoslav Ganov * </p> 564d4c66dd38e940082e385b49a33f4022ab04c738Svetoslav Ganov * <p> 574d4c66dd38e940082e385b49a33f4022ab04c738Svetoslav Ganov * The {@link #onLayout(PrintAttributes, PrintAttributes, CancellationSignal, 584d4c66dd38e940082e385b49a33f4022ab04c738Svetoslav Ganov * LayoutResultCallback, Bundle)} callback requires that you layout the content 594d4c66dd38e940082e385b49a33f4022ab04c738Svetoslav Ganov * based on the current {@link PrintAttributes}. The execution of this method is 604d4c66dd38e940082e385b49a33f4022ab04c738Svetoslav Ganov * not considered completed until you invoke one of the methods on the passed in 614d4c66dd38e940082e385b49a33f4022ab04c738Svetoslav Ganov * callback instance. Hence, you will not receive a subsequent call to any other 624d4c66dd38e940082e385b49a33f4022ab04c738Svetoslav Ganov * method of this class until the execution of this method is complete by invoking 634d4c66dd38e940082e385b49a33f4022ab04c738Svetoslav Ganov * one of the callback methods. 644d4c66dd38e940082e385b49a33f4022ab04c738Svetoslav Ganov * </p> 654d4c66dd38e940082e385b49a33f4022ab04c738Svetoslav Ganov * <p> 664d4c66dd38e940082e385b49a33f4022ab04c738Svetoslav Ganov * The {@link #onWrite(PageRange[], ParcelFileDescriptor, CancellationSignal, 674d4c66dd38e940082e385b49a33f4022ab04c738Svetoslav Ganov * WriteResultCallback)} requires that you render and write the content of some 684d4c66dd38e940082e385b49a33f4022ab04c738Svetoslav Ganov * pages to the provided destination. The execution of this method is not 694d4c66dd38e940082e385b49a33f4022ab04c738Svetoslav Ganov * considered complete until you invoke one of the methods on the passed in 704d4c66dd38e940082e385b49a33f4022ab04c738Svetoslav Ganov * callback instance. Hence, you will not receive a subsequent call to any other 714d4c66dd38e940082e385b49a33f4022ab04c738Svetoslav Ganov * method of this class until the execution of this method is complete by invoking 724d4c66dd38e940082e385b49a33f4022ab04c738Svetoslav Ganov * one of the callback methods. You will never receive a sequence of one or more 734d4c66dd38e940082e385b49a33f4022ab04c738Svetoslav Ganov * calls to this method without a previous call to {@link #onLayout(PrintAttributes, 744d4c66dd38e940082e385b49a33f4022ab04c738Svetoslav Ganov * PrintAttributes, CancellationSignal, LayoutResultCallback, Bundle)}. 754d4c66dd38e940082e385b49a33f4022ab04c738Svetoslav Ganov * </p> 764d4c66dd38e940082e385b49a33f4022ab04c738Svetoslav Ganov * <p> 774d4c66dd38e940082e385b49a33f4022ab04c738Svetoslav Ganov * The {@link #onFinish()} callback is always the last call you will receive and 784d4c66dd38e940082e385b49a33f4022ab04c738Svetoslav Ganov * is useful for doing one time cleanup or resource deallocation after printing. 794d4c66dd38e940082e385b49a33f4022ab04c738Svetoslav Ganov * You will not receive a subsequent call here. 804d4c66dd38e940082e385b49a33f4022ab04c738Svetoslav Ganov * </p> 81a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * </p> 826283608e0bd40548742839f5a8b02f7e5c9c5c7cSvetoslav * <h3>Implementation</h3> 836283608e0bd40548742839f5a8b02f7e5c9c5c7cSvetoslav * <p> 846283608e0bd40548742839f5a8b02f7e5c9c5c7cSvetoslav * The APIs defined in this class are designed to enable doing part or all 856283608e0bd40548742839f5a8b02f7e5c9c5c7cSvetoslav * of the work on an arbitrary thread. For example, if the printed content 866283608e0bd40548742839f5a8b02f7e5c9c5c7cSvetoslav * does not depend on the UI state, i.e. on what is shown on the screen, then 8719fba5d34a444ce145ab0d3a12c578d9d5d3f38cSvetoslav Ganov * you can offload the entire work on a dedicated thread, thus making your 884d4c66dd38e940082e385b49a33f4022ab04c738Svetoslav Ganov * application interactive while the print work is being performed. Note that 894d4c66dd38e940082e385b49a33f4022ab04c738Svetoslav Ganov * while your activity is covered by the system print UI and a user cannot 904d4c66dd38e940082e385b49a33f4022ab04c738Svetoslav Ganov * interact with it, doing the printing work on the main application thread 914d4c66dd38e940082e385b49a33f4022ab04c738Svetoslav Ganov * may affect the performance of your other application components as they 924d4c66dd38e940082e385b49a33f4022ab04c738Svetoslav Ganov * are also executed on that thread. 936283608e0bd40548742839f5a8b02f7e5c9c5c7cSvetoslav * </p> 946283608e0bd40548742839f5a8b02f7e5c9c5c7cSvetoslav * <p> 956283608e0bd40548742839f5a8b02f7e5c9c5c7cSvetoslav * You can also do work on different threads, for example if you print UI 966283608e0bd40548742839f5a8b02f7e5c9c5c7cSvetoslav * content, you can handle {@link #onStart()} and {@link #onLayout(PrintAttributes, 976283608e0bd40548742839f5a8b02f7e5c9c5c7cSvetoslav * PrintAttributes, CancellationSignal, LayoutResultCallback, Bundle)} on 986283608e0bd40548742839f5a8b02f7e5c9c5c7cSvetoslav * the UI thread (assuming onStart initializes resources needed for layout). 996283608e0bd40548742839f5a8b02f7e5c9c5c7cSvetoslav * This will ensure that the UI does not change while you are laying out the 100d26d4898fcc9b78f4b66118895c375384098205eSvetoslav Ganov * printed content. Then you can handle {@link #onWrite(PageRange[], ParcelFileDescriptor, 1016283608e0bd40548742839f5a8b02f7e5c9c5c7cSvetoslav * CancellationSignal, WriteResultCallback)} and {@link #onFinish()} on another 1024d4c66dd38e940082e385b49a33f4022ab04c738Svetoslav Ganov * thread. This will ensure that the main thread is busy for a minimal amount of 1036283608e0bd40548742839f5a8b02f7e5c9c5c7cSvetoslav * time. Also this assumes that you will generate the printed content in 1046283608e0bd40548742839f5a8b02f7e5c9c5c7cSvetoslav * {@link #onLayout(PrintAttributes, PrintAttributes, CancellationSignal, 1056283608e0bd40548742839f5a8b02f7e5c9c5c7cSvetoslav * LayoutResultCallback, Bundle)} which is not mandatory. If you use multiple 1066283608e0bd40548742839f5a8b02f7e5c9c5c7cSvetoslav * threads, you are responsible for proper synchronization. 1076283608e0bd40548742839f5a8b02f7e5c9c5c7cSvetoslav * </p> 108a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov */ 109a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganovpublic abstract class PrintDocumentAdapter { 110a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov 111a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov /** 1126811f4e92cbb64e72a0d13eb9b99b5894bd59c76Svetoslav * Extra: mapped to a boolean value that is <code>true</code> if 1136283608e0bd40548742839f5a8b02f7e5c9c5c7cSvetoslav * the current layout is for a print preview, <code>false</code> otherwise. 1144d4c66dd38e940082e385b49a33f4022ab04c738Svetoslav Ganov * This extra is provided in the {@link Bundle} argument of the {@link 1154d4c66dd38e940082e385b49a33f4022ab04c738Svetoslav Ganov * #onLayout(PrintAttributes, PrintAttributes, CancellationSignal, 1164d4c66dd38e940082e385b49a33f4022ab04c738Svetoslav Ganov * LayoutResultCallback, Bundle)} callback. 1174d4c66dd38e940082e385b49a33f4022ab04c738Svetoslav Ganov * 1184d4c66dd38e940082e385b49a33f4022ab04c738Svetoslav Ganov * @see #onLayout(PrintAttributes, PrintAttributes, CancellationSignal, 1194d4c66dd38e940082e385b49a33f4022ab04c738Svetoslav Ganov * LayoutResultCallback, Bundle) 1206283608e0bd40548742839f5a8b02f7e5c9c5c7cSvetoslav */ 1216811f4e92cbb64e72a0d13eb9b99b5894bd59c76Svetoslav public static final String EXTRA_PRINT_PREVIEW = "EXTRA_PRINT_PREVIEW"; 1226283608e0bd40548742839f5a8b02f7e5c9c5c7cSvetoslav 1236283608e0bd40548742839f5a8b02f7e5c9c5c7cSvetoslav /** 124a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * Called when printing starts. You can use this callback to allocate 125a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * resources. This method is invoked on the main thread. 126a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov */ 127a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov public void onStart() { 128a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov /* do nothing - stub */ 129a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov } 130a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov 131a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov /** 132a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * Called when the print attributes (page size, density, etc) changed 133a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * giving you a chance to layout the content such that it matches the 134a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * new constraints. This method is invoked on the main thread. 135a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * <p> 1366283608e0bd40548742839f5a8b02f7e5c9c5c7cSvetoslav * After you are done laying out, you <strong>must</strong> invoke: {@link 1376283608e0bd40548742839f5a8b02f7e5c9c5c7cSvetoslav * LayoutResultCallback#onLayoutFinished(PrintDocumentInfo, boolean)} with 1386283608e0bd40548742839f5a8b02f7e5c9c5c7cSvetoslav * the last argument <code>true</code> or <code>false</code> depending on 1394d4c66dd38e940082e385b49a33f4022ab04c738Svetoslav Ganov * whether the layout changed the content or not, respectively; or {@link 1404d4c66dd38e940082e385b49a33f4022ab04c738Svetoslav Ganov * LayoutResultCallback#onLayoutFailed(CharSequence)}, if an error occurred; 1414d4c66dd38e940082e385b49a33f4022ab04c738Svetoslav Ganov * or {@link LayoutResultCallback#onLayoutCancelled()} if layout was 1424d4c66dd38e940082e385b49a33f4022ab04c738Svetoslav Ganov * cancelled in a response to a cancellation request via the passed in 1434d4c66dd38e940082e385b49a33f4022ab04c738Svetoslav Ganov * {@link CancellationSignal}. Note that you <strong>must</strong> call one of 14457b296f5a9b547e5a5aad2f19f082f2b9400d88aSvetoslav * the methods of the given callback for this method to be considered complete 14557b296f5a9b547e5a5aad2f19f082f2b9400d88aSvetoslav * which is you will not receive any calls to this adapter until the current 14657b296f5a9b547e5a5aad2f19f082f2b9400d88aSvetoslav * layout operation is complete by invoking a method on the callback instance. 14757b296f5a9b547e5a5aad2f19f082f2b9400d88aSvetoslav * The callback methods can be invoked from an arbitrary thread. 148a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * </p> 149a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * <p> 15057b296f5a9b547e5a5aad2f19f082f2b9400d88aSvetoslav * One of the arguments passed to this method is a {@link CancellationSignal} 15157b296f5a9b547e5a5aad2f19f082f2b9400d88aSvetoslav * which is used to propagate requests from the system to your application for 15257b296f5a9b547e5a5aad2f19f082f2b9400d88aSvetoslav * canceling the current layout operation. For example, a cancellation may be 15357b296f5a9b547e5a5aad2f19f082f2b9400d88aSvetoslav * requested if the user changes a print option that may affect layout while 15457b296f5a9b547e5a5aad2f19f082f2b9400d88aSvetoslav * you are performing a layout operation. In such a case the system will make 15557b296f5a9b547e5a5aad2f19f082f2b9400d88aSvetoslav * an attempt to cancel the current layout as another one will have to be performed. 15657b296f5a9b547e5a5aad2f19f082f2b9400d88aSvetoslav * Typically, you should register a cancellation callback in the cancellation 15757b296f5a9b547e5a5aad2f19f082f2b9400d88aSvetoslav * signal. The cancellation callback <strong>will not</strong> be made on the 15857b296f5a9b547e5a5aad2f19f082f2b9400d88aSvetoslav * main thread and can be registered as follows: 15957b296f5a9b547e5a5aad2f19f082f2b9400d88aSvetoslav * </p> 16057b296f5a9b547e5a5aad2f19f082f2b9400d88aSvetoslav * <pre> 16157b296f5a9b547e5a5aad2f19f082f2b9400d88aSvetoslav * cancellationSignal.setOnCancelListener(new OnCancelListener() { 16257b296f5a9b547e5a5aad2f19f082f2b9400d88aSvetoslav * @Override 16357b296f5a9b547e5a5aad2f19f082f2b9400d88aSvetoslav * public void onCancel() { 16457b296f5a9b547e5a5aad2f19f082f2b9400d88aSvetoslav * // Cancel layout 16557b296f5a9b547e5a5aad2f19f082f2b9400d88aSvetoslav * } 16657b296f5a9b547e5a5aad2f19f082f2b9400d88aSvetoslav * }); 16757b296f5a9b547e5a5aad2f19f082f2b9400d88aSvetoslav * </pre> 16857b296f5a9b547e5a5aad2f19f082f2b9400d88aSvetoslav * <p> 169a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * <strong>Note:</strong> If the content is large and a layout will be 170a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * performed, it is a good practice to schedule the work on a dedicated 171a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * thread and register an observer in the provided {@link 172a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * CancellationSignal} upon invocation of which you should stop the 17357b296f5a9b547e5a5aad2f19f082f2b9400d88aSvetoslav * layout. 174a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * </p> 175a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * 176a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * @param oldAttributes The old print attributes. 177a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * @param newAttributes The new print attributes. 178a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * @param cancellationSignal Signal for observing cancel layout requests. 179a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * @param callback Callback to inform the system for the layout result. 1806811f4e92cbb64e72a0d13eb9b99b5894bd59c76Svetoslav * @param extras Additional information about how to layout the content. 181a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * 182a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * @see LayoutResultCallback 183a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * @see CancellationSignal 1846811f4e92cbb64e72a0d13eb9b99b5894bd59c76Svetoslav * @see #EXTRA_PRINT_PREVIEW 185a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov */ 186a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov public abstract void onLayout(PrintAttributes oldAttributes, PrintAttributes newAttributes, 1876283608e0bd40548742839f5a8b02f7e5c9c5c7cSvetoslav CancellationSignal cancellationSignal, LayoutResultCallback callback, 1886811f4e92cbb64e72a0d13eb9b99b5894bd59c76Svetoslav Bundle extras); 189a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov 190a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov /** 191a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * Called when specific pages of the content should be written in the 19219fba5d34a444ce145ab0d3a12c578d9d5d3f38cSvetoslav Ganov * form of a PDF file to the given file descriptor. This method is invoked 193a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * on the main thread. 194a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov *<p> 195d26d4898fcc9b78f4b66118895c375384098205eSvetoslav Ganov * After you are done writing, you should close the file descriptor and 1964d4c66dd38e940082e385b49a33f4022ab04c738Svetoslav Ganov * invoke {@link WriteResultCallback#onWriteFinished(PageRange[])}, if writing 197d26d4898fcc9b78f4b66118895c375384098205eSvetoslav Ganov * completed successfully; or {@link WriteResultCallback#onWriteFailed( 1984d4c66dd38e940082e385b49a33f4022ab04c738Svetoslav Ganov * CharSequence)}, if an error occurred; or {@link WriteResultCallback#onWriteCancelled()}, 1994d4c66dd38e940082e385b49a33f4022ab04c738Svetoslav Ganov * if writing was cancelled in a response to a cancellation request via the passed 2004d4c66dd38e940082e385b49a33f4022ab04c738Svetoslav Ganov * in {@link CancellationSignal}. Note that you <strong>must</strong> call one of 20157b296f5a9b547e5a5aad2f19f082f2b9400d88aSvetoslav * the methods of the given callback for this method to be considered complete which 20257b296f5a9b547e5a5aad2f19f082f2b9400d88aSvetoslav * is you will not receive any calls to this adapter until the current write 20357b296f5a9b547e5a5aad2f19f082f2b9400d88aSvetoslav * operation is complete by invoking a method on the callback instance. The callback 20457b296f5a9b547e5a5aad2f19f082f2b9400d88aSvetoslav * methods can be invoked from an arbitrary thread. 20557b296f5a9b547e5a5aad2f19f082f2b9400d88aSvetoslav * </p> 20657b296f5a9b547e5a5aad2f19f082f2b9400d88aSvetoslav * <p> 20757b296f5a9b547e5a5aad2f19f082f2b9400d88aSvetoslav * One of the arguments passed to this method is a {@link CancellationSignal} 20857b296f5a9b547e5a5aad2f19f082f2b9400d88aSvetoslav * which is used to propagate requests from the system to your application for 20957b296f5a9b547e5a5aad2f19f082f2b9400d88aSvetoslav * canceling the current write operation. For example, a cancellation may be 21057b296f5a9b547e5a5aad2f19f082f2b9400d88aSvetoslav * requested if the user changes a print option that may affect layout while 21157b296f5a9b547e5a5aad2f19f082f2b9400d88aSvetoslav * you are performing a write operation. In such a case the system will make 21257b296f5a9b547e5a5aad2f19f082f2b9400d88aSvetoslav * an attempt to cancel the current write as a layout will have to be performed 21357b296f5a9b547e5a5aad2f19f082f2b9400d88aSvetoslav * which then may be followed by a write. Typically, you should register a 21457b296f5a9b547e5a5aad2f19f082f2b9400d88aSvetoslav * cancellation callback in the cancellation signal. The cancellation callback 21557b296f5a9b547e5a5aad2f19f082f2b9400d88aSvetoslav * <strong>will not</strong> be made on the main thread and can be registered 21657b296f5a9b547e5a5aad2f19f082f2b9400d88aSvetoslav * as follows: 217a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * </p> 21857b296f5a9b547e5a5aad2f19f082f2b9400d88aSvetoslav * <pre> 21957b296f5a9b547e5a5aad2f19f082f2b9400d88aSvetoslav * cancellationSignal.setOnCancelListener(new OnCancelListener() { 22057b296f5a9b547e5a5aad2f19f082f2b9400d88aSvetoslav * @Override 22157b296f5a9b547e5a5aad2f19f082f2b9400d88aSvetoslav * public void onCancel() { 22257b296f5a9b547e5a5aad2f19f082f2b9400d88aSvetoslav * // Cancel write 22357b296f5a9b547e5a5aad2f19f082f2b9400d88aSvetoslav * } 22457b296f5a9b547e5a5aad2f19f082f2b9400d88aSvetoslav * }); 22557b296f5a9b547e5a5aad2f19f082f2b9400d88aSvetoslav * </pre> 226a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * <p> 227a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * <strong>Note:</strong> If the printed content is large, it is a good 228a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * practice to schedule writing it on a dedicated thread and register an 229a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * observer in the provided {@link CancellationSignal} upon invocation of 23057b296f5a9b547e5a5aad2f19f082f2b9400d88aSvetoslav * which you should stop writing. 231a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * </p> 232a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * 23385b1f883056a1d74473fd9ce774948878f389ab6Svetoslav Ganov * @param pages The pages whose content to print - non-overlapping in ascending order. 234a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * @param destination The destination file descriptor to which to write. 235a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * @param cancellationSignal Signal for observing cancel writing requests. 236a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * @param callback Callback to inform the system for the write result. 237a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * 238a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * @see WriteResultCallback 239a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * @see CancellationSignal 240a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov */ 241d26d4898fcc9b78f4b66118895c375384098205eSvetoslav Ganov public abstract void onWrite(PageRange[] pages, ParcelFileDescriptor destination, 242a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov CancellationSignal cancellationSignal, WriteResultCallback callback); 243a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov 244a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov /** 245a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * Called when printing finishes. You can use this callback to release 246a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * resources acquired in {@link #onStart()}. This method is invoked on 247a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * the main thread. 248a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov */ 249a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov public void onFinish() { 250a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov /* do nothing - stub */ 251a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov } 252a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov 253a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov /** 254a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * Base class for implementing a callback for the result of {@link 255d26d4898fcc9b78f4b66118895c375384098205eSvetoslav Ganov * PrintDocumentAdapter#onWrite(PageRange[], ParcelFileDescriptor, CancellationSignal, 256a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * WriteResultCallback)}. 257a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov */ 258a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov public static abstract class WriteResultCallback { 259a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov 260a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov /** 261a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * @hide 262a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov */ 263a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov public WriteResultCallback() { 264a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov /* do nothing - hide constructor */ 265a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov } 266a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov 267a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov /** 268a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * Notifies that all the data was written. 269a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * 2704d4c66dd38e940082e385b49a33f4022ab04c738Svetoslav Ganov * @param pages The pages that were written. Cannot be <code>null</code> 2714d4c66dd38e940082e385b49a33f4022ab04c738Svetoslav Ganov * or empty. 272a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov */ 27385b1f883056a1d74473fd9ce774948878f389ab6Svetoslav Ganov public void onWriteFinished(PageRange[] pages) { 274a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov /* do nothing - stub */ 275a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov } 276a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov 277a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov /** 278a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * Notifies that an error occurred while writing the data. 279a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * 2804d4c66dd38e940082e385b49a33f4022ab04c738Svetoslav Ganov * @param error The <strong>localized</strong> error message. 2814d4c66dd38e940082e385b49a33f4022ab04c738Svetoslav Ganov * shown to the user. May be <code>null</code> if error is unknown. 282a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov */ 283a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov public void onWriteFailed(CharSequence error) { 284a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov /* do nothing - stub */ 285a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov } 28685b1f883056a1d74473fd9ce774948878f389ab6Svetoslav Ganov 28785b1f883056a1d74473fd9ce774948878f389ab6Svetoslav Ganov /** 28885b1f883056a1d74473fd9ce774948878f389ab6Svetoslav Ganov * Notifies that write was cancelled as a result of a cancellation request. 28985b1f883056a1d74473fd9ce774948878f389ab6Svetoslav Ganov */ 29085b1f883056a1d74473fd9ce774948878f389ab6Svetoslav Ganov public void onWriteCancelled() { 29185b1f883056a1d74473fd9ce774948878f389ab6Svetoslav Ganov /* do nothing - stub */ 29285b1f883056a1d74473fd9ce774948878f389ab6Svetoslav Ganov } 293a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov } 294a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov 295a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov /** 296a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * Base class for implementing a callback for the result of {@link 297a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * PrintDocumentAdapter#onLayout(PrintAttributes, PrintAttributes, 2986283608e0bd40548742839f5a8b02f7e5c9c5c7cSvetoslav * CancellationSignal, LayoutResultCallback, Bundle)}. 299a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov */ 300a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov public static abstract class LayoutResultCallback { 301a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov 302a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov /** 303a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * @hide 304a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov */ 305a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov public LayoutResultCallback() { 306a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov /* do nothing - hide constructor */ 307a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov } 308a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov 309a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov /** 310a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * Notifies that the layout finished and whether the content changed. 311a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * 3124d4c66dd38e940082e385b49a33f4022ab04c738Svetoslav Ganov * @param info An info object describing the document. Cannot be <code>null</code>. 313a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * @param changed Whether the layout changed. 314a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * 315a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * @see PrintDocumentInfo 316a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov */ 317a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov public void onLayoutFinished(PrintDocumentInfo info, boolean changed) { 318a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov /* do nothing - stub */ 319a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov } 320a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov 321a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov /** 322a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * Notifies that an error occurred while laying out the document. 323a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov * 3244d4c66dd38e940082e385b49a33f4022ab04c738Svetoslav Ganov * @param error The <strong>localized</strong> error message. 3254d4c66dd38e940082e385b49a33f4022ab04c738Svetoslav Ganov * shown to the user. May be <code>null</code> if error is unknown. 326a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov */ 327a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov public void onLayoutFailed(CharSequence error) { 328a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov /* do nothing - stub */ 329a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov } 33085b1f883056a1d74473fd9ce774948878f389ab6Svetoslav Ganov 33185b1f883056a1d74473fd9ce774948878f389ab6Svetoslav Ganov /** 33285b1f883056a1d74473fd9ce774948878f389ab6Svetoslav Ganov * Notifies that layout was cancelled as a result of a cancellation request. 33385b1f883056a1d74473fd9ce774948878f389ab6Svetoslav Ganov */ 33485b1f883056a1d74473fd9ce774948878f389ab6Svetoslav Ganov public void onLayoutCancelled() { 33585b1f883056a1d74473fd9ce774948878f389ab6Svetoslav Ganov /* do nothing - stub */ 33685b1f883056a1d74473fd9ce774948878f389ab6Svetoslav Ganov } 337a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov } 338a00271533f639c8ed36429c663889ac9f654bc72Svetoslav Ganov} 339