Most visited

Recently visited

Added in API level 19

PrintDocumentAdapter

public abstract class PrintDocumentAdapter
extends Object

java.lang.Object
   ↳ android.print.PrintDocumentAdapter


提供要打印的文档内容的基类。

Lifecycle

onStart()回调始终是您将收到的第一个调用,对于在打印前进行一次性设置或资源分配很有用。 您将不会再收到此处的电话。

onLayout(PrintAttributes, PrintAttributes, CancellationSignal, LayoutResultCallback, Bundle)回调要求您根据当前的PrintAttributes布局内容。 除非您调用传入的回调实例中的某个方法,否则此方法的执行不会被视为已完成。 因此,直到通过调用其中一种回调方法完成此方法的执行,您才会收到对此类的任何其他方法的后续调用。

onWrite(PageRange[], ParcelFileDescriptor, CancellationSignal, WriteResultCallback)要求您呈现某些页面的内容并将其写入所提供的目标。 直到您调用传入的回调实例中的某个方法之前,此方法的执行才算完成。 因此,直到通过调用其中一种回调方法完成此方法的执行,您才会收到对此类的任何其他方法的后续调用。 如果没有先前调用onLayout(PrintAttributes, PrintAttributes, CancellationSignal, LayoutResultCallback, Bundle)您将永远不会收到一个或多个对此方法的调用onLayout(PrintAttributes, PrintAttributes, CancellationSignal, LayoutResultCallback, Bundle)

onFinish()回调始终是您将收到的最后一次调用,对于在打印后进行一次性清理或资源释放非常有用。 您将不会再收到此处的电话。

Implementation

在这个类中定义的API被设计为可以在任意线程上执行部分或全部工作。 例如,如果打印的内容不依赖于UI状态(即屏幕上显示的内容),则可以在专用线程上卸载整个工作,从而在执行打印工作时使应用程序互动。 请注意,尽管您的活动已由系统打印用户界面覆盖,并且用户无法与其交互,但在主应用程序线程上执行打印工作可能会影响其他应用程序组件的性能,因为它们也在该线程上执行。

您也可以在不同的线程上工作,例如,如果您打印UI内容,则可以在UI线程上处理onStart()onLayout(PrintAttributes, PrintAttributes, CancellationSignal, LayoutResultCallback, Bundle) (假设onStart初始化布局所需的资源)。 这将确保您在布置打印内容时不会更改用户界面。 然后你可以在另一个线程上处理onWrite(PageRange[], ParcelFileDescriptor, CancellationSignal, WriteResultCallback)onFinish() 这将确保主线程在最短的时间内忙碌。 此外,这假设您将生成onLayout(PrintAttributes, PrintAttributes, CancellationSignal, LayoutResultCallback, Bundle)的打印内容,这不是强制性的。 如果您使用多个线程,则需要负责正确的同步。

Summary

Nested classes

class PrintDocumentAdapter.LayoutResultCallback

用于实现onLayout(PrintAttributes, PrintAttributes, CancellationSignal, LayoutResultCallback, Bundle)结果回调的基类。

class PrintDocumentAdapter.WriteResultCallback

用于实现onWrite(PageRange[], ParcelFileDescriptor, CancellationSignal, WriteResultCallback)结果回调的基类。

Constants

String EXTRA_PRINT_PREVIEW

额外:如果当前布局用于打印预览,则映射为布尔值 true ,否则为 false

Public constructors

PrintDocumentAdapter()

Public methods

void onFinish()

打印完成时调用。

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

当打印属性(页面大小,密度等)发生变化时会调用,使您有机会对内容进行布局,使其与新约束匹配。

void onStart()

打印开始时调用。

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

当内容的特定页面应该以PDF文件的形式写入给定的文件描述符时调用。

Inherited methods

From class java.lang.Object

Constants

EXTRA_PRINT_PREVIEW

Added in API level 19
String EXTRA_PRINT_PREVIEW

Extra:如果当前布局用于打印预览,则映射为布尔值true ,否则为false onLayout(PrintAttributes, PrintAttributes, CancellationSignal, LayoutResultCallback, Bundle)回调的Bundle参数中提供了此额外信息。

也可以看看:

常量值:“EXTRA_PRINT_PREVIEW”

Public constructors

PrintDocumentAdapter

Added in API level 19
PrintDocumentAdapter ()

Public methods

onFinish

Added in API level 19
void onFinish ()

打印完成时调用。 您可以使用此回调释放onStart()获取的资源。 此方法在主线程上调用。

onLayout

Added in API level 19
void onLayout (PrintAttributes oldAttributes, 
                PrintAttributes newAttributes, 
                CancellationSignal cancellationSignal, 
                PrintDocumentAdapter.LayoutResultCallback callback, 
                Bundle extras)

当打印属性(页面大小,密度等)发生变化时会调用,使您有机会对内容进行布局,使其与新约束匹配。 此方法在主线程上调用。

完成布局之后,您必须调用: onLayoutFinished(PrintDocumentInfo, boolean) ,最后一个参数为truefalse具体取决于布局是否分别更改了内容; 或者onLayoutFailed(CharSequence) ,如果发生错误; onLayoutCancelled()如果通过CancellationSignal的传递取消请求响应中取消CancellationSignal 请注意,您必须调用给定回调的其中一个方法,才能将此方法视为已完成,即在调用回调实例上的方法完成当前布局操作之前,您将不会收到对此适配器的任何调用。 回调方法可以从任意线程中调用。

传递给此方法的参数之一是CancellationSignal ,它用于将请求从系统传播到您的应用程序以取消当前的布局操作。 例如,如果用户在执行布局操作时更改可能影响布局的打印选项,则可能会要求取消。 在这种情况下,系统将尝试取消当前布局,因为必须执行另一个布局。 通常,您应该在取消信号中注册取消回拨。 取消回调不会在主线程中进行,并且可以按如下注册:

 cancellationSignal.setOnCancelListener(new OnCancelListener() {
     @Override
     public void onCancel() {
         // Cancel layout
     }
 });
 

注意:如果内容很大并且将执行布局,则最好在专用线程上安排工作并在提供的 CancellationSignal注册一个观察者,在调用该 CancellationSignal时应停止布局。

Parameters
oldAttributes PrintAttributes: The old print attributes.
newAttributes PrintAttributes: The new print attributes.
cancellationSignal CancellationSignal: Signal for observing cancel layout requests.
callback PrintDocumentAdapter.LayoutResultCallback: Callback to inform the system for the layout result.
extras Bundle: Additional information about how to layout the content.

也可以看看:

onStart

Added in API level 19
void onStart ()

打印开始时调用。 您可以使用此回调来分配资源。 此方法在主线程上调用。

onWrite

Added in API level 19
void onWrite (PageRange[] pages, 
                ParcelFileDescriptor destination, 
                CancellationSignal cancellationSignal, 
                PrintDocumentAdapter.WriteResultCallback callback)

当内容的特定页面应该以PDF文件的形式写入给定的文件描述符时调用。 此方法在主线程上调用。

onWriteFinished(PageRange[]) ,如果写入成功完成,应关闭文件描述符并调用onWriteFinished(PageRange[]) ; onWriteFailed(CharSequence) ,如果发生错误; 或者onWriteCancelled() ,如果通过在CancellationSignal传递的取消请求的回复取消CancellationSignal 请注意, 必须调用给定回调的其中一个方法,才能将此方法视为已完成,即在调用回调实例上的方法完成当前写入操作之前,您将不会收到对此适配器的任何调用。 回调方法可以从任意线程中调用。

传递给此方法的参数之一是CancellationSignal ,它用于将请求从系统传播到您的应用程序以取消当前写入操作。 例如,如果用户在执行写入操作时更改可能影响布局的打印选项,则可能会要求取消。 在这种情况下,系统将尝试取消当前的写入,因为必须执行布局,然后可以写入。 通常,您应该在取消信号中注册取消回拨。 取消回调不会在主线程中进行,并且可以按如下注册:

 cancellationSignal.setOnCancelListener(new OnCancelListener() {
     @Override
     public void onCancel() {
         // Cancel write
     }
 });
 

注意:如果打印的内容很大,最好将其编写在专用线程上,并在提供的 CancellationSignal注册一个观察者,然后您应该停止写入。

Parameters
pages PageRange: The pages whose content to print - non-overlapping in ascending order.
destination ParcelFileDescriptor: The destination file descriptor to which to write.
cancellationSignal CancellationSignal: Signal for observing cancel writing requests.
callback PrintDocumentAdapter.WriteResultCallback: Callback to inform the system for the write result.

也可以看看:

Hooray!