继承 Object

类概述

这是一个基类，用来提供要打印的文档的内容。

生命周期

• •. 最开始，妳的 onStart() 会被调用。 这个回调函数可用于分配资源。

• •. 然后 ，妳的 onLayout(PrintAttributes, PrintAttributes, CancellationSignal, LayoutResultCallback, Bundle) 会被调用一次或多次， 以告知妳，当前打印任务 的某些属性 (页面尺寸 、密度等等 ) 发生了改变，使得 妳有机会来对内容进行重新排版，以匹配新的约束条件。

• •. 在每次调用 onLayout(PrintAttributes, PrintAttributes, CancellationSignal, LayoutResultCallback, Bundle) 之后 ， 妳的 onWrite(PageRange[], ParcelFileDescriptor, CancellationSignal, WriteResultCallback) 可能 会 被调用一次， 要求妳 将特定页面的内容输出到一个可移植文档格式（ PDF ）文件中。

• •. 最终 ，妳的 onFinish() 会被调用。 妳可以在这个回调函数中释放那些在 onStart() 中分配的资源。

onStart() 回调函数 是第一个被调用的函数，可用来 在打印之前 做一些一次性的初始化操作或者资源分配。之后 不会再次调用这个回调函数。

onLayout(PrintAttributes, PrintAttributes, CancellationSignal, LayoutResultCallback, Bundle) 回调函数 中，需要依据当前 的打印属性（ PrintAttributes ）来对内容进行排版。直到 妳调用了所传入的回调实例的某个方法的时候，才认为此方法执行完毕。因此， 在妳调用其中的某个回调函数以表明本方法执行完毕之前，不会收到对于这个类的任何其它方法的调用。

在 onWrite(PageRange[], ParcelFileDescriptor, CancellationSignal, WriteResultCallback) 函数 中，妳需要将某些页面的内容渲染并输出到所提供的目标中。 直到 妳调用了所传入的回调实例的某个方法的时候，才认为此方法执行完毕。因此， 在妳调用其中的某个回调函数以表明本方法执行完毕之前，不会收到对于这个类的任何其它方法的调用。如果之前 未调用过 onLayout(PrintAttributes, PrintAttributes, CancellationSignal, LayoutResultCallback, Bundle) 的话，也不会对这个方法进行调用。

onFinish() 回调函数 是最后一个被调用的函数，可用来在打印之后做一些一次性的清理工作或者资源的释放。 之后 不会再次调用这个回调函数。

实现

在这个类中定义的那些应用编程接口，被设计为，可在任意的线程中进行全部的工作或者其中的部分工作。例如，如果所打印的内容不依赖于界面的状态（就是说，不依赖于屏幕上当前显示着什么），那么， 妳可以将整个工作交给一个独立的线程来做，这就使得，在打印工作正在进行时，妳的应用程序仍然处于交互状态。注意，尽管妳的当前活动会被系统的打印界面覆盖，使得用户无法与它交互，但是，在程序的主线程中处理打印工作的话，可能会影响妳的应用程序中其它组件的性能，因为它们都是在主线程中执行的。

妳也可以使用多个线程来协调完成整个工作，例如，妳想打印界面上的当前内容，那么，妳可以在界面线程（假设onStart中会初始化某些与布局相关的资源）中处理 onStart() 和 onLayout(PrintAttributes, PrintAttributes, CancellationSignal, LayoutResultCallback, Bundle) 。 这样就会确保，当妳对打印内容进行排版时，界面不会发生改变。然后，妳可以在另一个线程中处理 onWrite(PageRange[], ParcelFileDescriptor, CancellationSignal, WriteResultCallback) 和 onFinish() 。这会确保，主线程的忙碌时间尽可能地短。这种处理方式也假设了，妳在 onLayout(PrintAttributes, PrintAttributes, CancellationSignal, LayoutResultCallback, Bundle) 中就生成了要打印的内容，当然，这不是强制要求的。如果妳使用多个线程的话，那么，妳要做好适当的同步。

摘要

嵌套类
class	PrintDocumentAdapter.LayoutResultCallback	一个基类，用于实现对于 onLayout(PrintAttributes, PrintAttributes, CancellationSignal, LayoutResultCallback, Bundle) 的结果的回调函数。
class	PrintDocumentAdapter.WriteResultCallback	一个基类，用于实现对于 onWrite(PageRange[], ParcelFileDescriptor, CancellationSignal, WriteResultCallback) 的结果的回调函数。

公有方法

public abstract void  onLayout  ( PrintAttributes  oldAttributes,  PrintAttributes  newAttributes,  CancellationSignal  cancellationSignal, PrintDocumentAdapter.LayoutResultCallback  callback,  Bundle  extras)

自此版本开始引入 应用编程接口级别19

当打印属性（页面尺寸、密度等等）发生改变时会被调用，使得妳能够对内容进行重新排版，以匹配新的限制条件。这个方法会在主线程上被调用。

当妳完成了排版之后，妳 必须 调用 ： onLayoutFinished(PrintDocumentInfo, boolean) 最后 一个参数指定为 true 或 false ，分别表示着此次排版有改变内容或没改变内容；或者， onLayoutFailed(CharSequence) ，表明发生了某个错误；或者 ， onLayoutCancelled() ，如果通过传入的 CancellationSignal 请求了取消这次排版的话，则调用这个函数作为响应。注意， 妳 必须 调用其中 的某个方法，以表明本方法已经执行完毕。因为，如果这个方法未执行完毕的话，则，系统不会继续调用此适配器的任何后续方法。 这些回调方法，可以从任何线程中调用。

传入 这个方法的那些参数中，有一个 CancellationSignal ，用来表明系统或者 妳自己的应用程序请求取消当前的排版操作。例如， 在妳仍然在做排版操作时，如果用户改变了某个可能影响排版结果的打印选项的 话，则，系统可能会发出一个取消请求。 在这种情况下，系统会尝试取消当前的排版操作，因为需要开始进行下一次排版操作了。 一般情况下，妳应当对这个取消信号注册一个取消回调函数。取消 的回调函数 不会 在主线程中调用， 可以这样注册：

cancellationSignal . setOnCancelListener ( new OnCancelListener () {

@Override

public void onCancel () {

// 取消排版

}

});

注意 ： 如果内容 狠大的话，则，最好 将排版工作提交给一个独立的线程来进行，并且 对所提供的 CancellationSignal 注册一个观察器， 以便在收到取消请求时停止排版操作。

参数

oldAttributes	旧的打印属性。
newAttributes	新的打印属性。
cancellationSignal	用来观察取消排版操作的请求的信号。
callback	回调对象，用于向系统告知排版的结果。
extras	关于如何将内容进行排版的额外信息。

参考

• •. PrintDocumentAdapter.LayoutResultCallback

• •. CancellationSignal

• •. EXTRA_PRINT_PREVIEW

public abstract void  onWrite  ( PageRange[]  pages,  ParcelFileDescriptor  destination,  CancellationSignal  cancellationSignal, PrintDocumentAdapter.WriteResultCallback  callback)

自此版本开始引入 应用编程接口级别19

当需要将内容中特定的页面以PDF 文件的形式输出到指定的文件描述符中去的时候，会调用这个方法。这个方法会在主线程上被调用。

在妳完成输出操作之后，妳应当关闭这个文件描述符，然后调用： onWriteFinished(PageRange[]) ，表明输出成功完成；或者， onWriteFailed(CharSequence) ，表明发生了某个错误；或者 ， onWriteCancelled() ，如果通过 所传入的 CancellationSignal 发送了一个取消请求的话，则调用这个方法作为响应。 注意， 妳 必须 调用其中 的某个方法，以表明本方法已经执行完毕。因为，如果这个方法未执行完毕的话，则，系统不会继续调用此适配器的任何后续方法。 这些回调方法，可以从任何线程中调用。

传入 这个方法的那些参数中，有一个 CancellationSignal ，用来表明系统或者 妳自己的应用程序请求取消当前的输出操作。例如， 在妳仍然在做输出操作时，如果用户改变了某个可能影响排版结果的打印选项的话，则，系统可能会发出一个取消请求。 在这种情况下，系统会尝试取消当前的输出操作，因为需要开始进行一次排版操作了 ，之后可能会跟着做一次输出操作 。 一般情况下，妳应当对这个取消信号注册一个取消回调函数。取消 的回调函数 不会 在主线程中调用， 可以这样注册：

cancellationSignal . setOnCancelListener ( new OnCancelListener () {

@Override

public void onCancel () {

// 取消输出

}

});

注意 ： 如果内容 狠大的话，则，最好 将输出工作提交给一个独立的线程来进行，并且 对所提供的 CancellationSignal 注册一个观察器， 以便在收到取消请求时停止输出操作。

参数

pages	要打印其内容的那些页面——不会重叠，且以递增顺序列出。
destination	要向其中写入内容的目标文件描述符。
cancellationSignal	用于观察取消输出请求的信号。
callback	回调对象，用于向系统告知输出的结果。

参考

• •. PrintDocumentAdapter.WriteResultCallback

• •. CancellationSignal