/* * Copyright (C) 2013 The Android Open Source Project * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package android.print; import android.os.Bundle; import android.os.CancellationSignal; import java.io.FileDescriptor; import java.util.List; /** * Base class that provides the content of a document to be printed. * *
*
* The APIs defined in this class are designed to enable doing part or all * of the work on an arbitrary thread. For example, if the printed content * does not depend on the UI state, i.e. on what is shown on the screen, then * you can off load the entire work on a dedicated thread, thus making your * application interactive while the print work is being performed. *
** You can also do work on different threads, for example if you print UI * content, you can handle {@link #onStart()} and {@link #onLayout(PrintAttributes, * PrintAttributes, CancellationSignal, LayoutResultCallback, Bundle)} on * the UI thread (assuming onStart initializes resources needed for layout). * This will ensure that the UI does not change while you are laying out the * printed content. Then you can handle {@link #onWrite(List, FileDescriptor, * CancellationSignal, WriteResultCallback)} and {@link #onFinish()} on another * thread. This will ensure that the UI is frozen for the minimal amount of * time. Also this assumes that you will generate the printed content in * {@link #onLayout(PrintAttributes, PrintAttributes, CancellationSignal, * LayoutResultCallback, Bundle)} which is not mandatory. If you use multiple * threads, you are responsible for proper synchronization. *
*/ public abstract class PrintDocumentAdapter { /** * Meta-data key: mapped to a boolean value that istrue
if
* the current layout is for a print preview, false
otherwise.
*/
public static final String METADATA_KEY_PRINT_PREVIEW = "KEY_METADATA_PRINT_PREVIEW";
/**
* Called when printing starts. You can use this callback to allocate
* resources. This method is invoked on the main thread.
*/
public void onStart() {
/* do nothing - stub */
}
/**
* Called when the print attributes (page size, density, etc) changed
* giving you a chance to layout the content such that it matches the
* new constraints. This method is invoked on the main thread.
*
* After you are done laying out, you must invoke: {@link
* LayoutResultCallback#onLayoutFinished(PrintDocumentInfo, boolean)} with
* the last argument true
or false
depending on
* whether the layout changed the content or not, respectively; and {@link
* LayoutResultCallback#onLayoutFailed(CharSequence)}, if an error occurred.
*
* Note: If the content is large and a layout will be * performed, it is a good practice to schedule the work on a dedicated * thread and register an observer in the provided {@link * CancellationSignal} upon invocation of which you should stop the * layout. The cancellation callback will not be made on the main * thread. *
* * @param oldAttributes The old print attributes. * @param newAttributes The new print attributes. * @param cancellationSignal Signal for observing cancel layout requests. * @param callback Callback to inform the system for the layout result. * @param metadata Additional information about how layout the content. * * @see LayoutResultCallback * @see CancellationSignal * @see #METADATA_KEY_PRINT_PREVIEW */ public abstract void onLayout(PrintAttributes oldAttributes, PrintAttributes newAttributes, CancellationSignal cancellationSignal, LayoutResultCallback callback, Bundle metadata); /** * Called when specific pages of the content should be written in the * from of a PDF file to the given file descriptor. This method is invoked * on the main thread. ** After you are done writing, you should not close the * file descriptor, rather you must invoke: {@link WriteResultCallback * #onWriteFinished(List)}, if writing completed successfully; or {@link * WriteResultCallback#onWriteFailed(CharSequence)}, if an error occurred. *
** Note: If the printed content is large, it is a good * practice to schedule writing it on a dedicated thread and register an * observer in the provided {@link CancellationSignal} upon invocation of * which you should stop writing. The cancellation callback will not be * made on the main thread. *
* * @param pages The pages whose content to print. * @param destination The destination file descriptor to which to write. * @param cancellationSignal Signal for observing cancel writing requests. * @param callback Callback to inform the system for the write result. * * @see WriteResultCallback * @see CancellationSignal */ public abstract void onWrite(List