79. A Guide to Android Custom Document Printing

As we have seen in the preceding chapters, the Android Printing framework makes it relatively easy to build printing support into applications as long as the content is in the form of an image or HTML markup. More advanced printing requirements can be met by making use of the custom document printing feature of the Printing framework.

79.1 An Overview of Android Custom Document Printing

In simplistic terms, custom document printing uses canvases to represent the pages of the document to be printed. The application draws the content to be printed onto these canvases in the form of shapes, colors, text and images. In actual fact, the canvases are represented by instances of the Android Canvas class, thereby providing access to a rich selection of drawing options. Once all the pages have been drawn, the document is then printed.

While this sounds simple enough, there are actually a number of steps that need to be performed to make this happen, which can be summarized as follows:

•Implement a custom print adapter sub-classed from the PrintDocumentAdapter class

•Obtain a reference to the Print Manager Service

•Create an instance of the PdfDocument class in which to store the document pages

•Add pages to the PdfDocument in the form of PdfDocument.Page instances

•Obtain...

79.2 Preparing the Custom Document Printing Project

Select the Create New Project quick start option from the welcome screen and, within the resulting new project dialog, choose the Empty Activity template before clicking on the Next button.

Enter CustomPrint into the Name field and specify com.ebookfrenzy.customprint as the package name. Before clicking on the Finish button, change the Minimum API level setting to API 26: Android 8.0 (Oreo) and the Language menu to Java.

Load the activity_main.xml layout file into the Layout Editor tool and, in Design mode, select and delete the “Hello World!” TextView object. Drag and drop a Button view from the Form Widgets section of the palette and position it in the center of the layout view. With the Button view selected, change the text property to “Print Document” and extract the string to a new resource. On completion, the user interface layout should match that shown in Figure 79-1:

Figure 79-1

...

79.3 Creating the Custom Print Adapter

Most of the work involved in printing a custom document from within an Android application involves the implementation of the custom print adapter. This example will require a print adapter with the onLayout() and onWrite() callback methods implemented. Within the MainActivity.java file, add the template for this new class so that it reads as follows:

package com.ebookfrenzy.customprint;

.

.

import android.os.CancellationSignal;

import android.os.ParcelFileDescriptor;

import android.print.PageRange;

import android.print.PrintAttributes;

import android.print.PrintDocumentAdapter;

import android.content.Context;

 

public class MainActivity extends AppCompatActivity {

 

    public static class MyPrintDocumentAdapter extends PrintDocumentAdapter

    {

        Context context;

 

    &...

79.4 Implementing the onLayout() Callback Method

Remaining within the MainActivity.java file, begin by adding some import directives that will be required by the code in the onLayout() method:

package com.ebookfrenzy.customprint;

.

.

import android.print.PrintDocumentInfo;

import android.print.pdf.PrintedPdfDocument;

import android.graphics.pdf.PdfDocument;

 

public class MainActivity extends AppCompatActivity {

.

.

}

Next, modify the MyPrintDocumentAdapter class to declare variables to be used within the onLayout() method:

public static class MyPrintDocumentAdapter extends PrintDocumentAdapter

{

       Context context;

       int pageHeight;

       int pageWidth;

       PdfDocument myPdfDocument;

       int totalpages = 4;

.

.

}

Note that...

79.5 Implementing the onWrite() Callback Method

The onWrite() callback method is responsible for rendering the pages of the document and then notifying the Printing framework that the document is ready to be printed. When completed, the onWrite() method reads as follows:

package com.ebookfrenzy.customprint;

 

import java.io.FileOutputStream;

import java.io.IOException;

.

.

import android.graphics.pdf.PdfDocument.PageInfo;

.

.

@Override

public void onWrite(final PageRange[] pageRanges,

                   final ParcelFileDescriptor destination,

                   final CancellationSignal cancellationSignal,

                   final WriteResultCallback callback...

79.6 Checking a Page is in Range

As previously outlined, when the onWrite() method is called it is passed an array of PageRange objects indicating the ranges of pages within the document that are to be printed. The PageRange class is designed to store the start and end pages of a page range which, in turn, may be accessed via the getStart() and getEnd() methods of the class.

When the onWrite() method was implemented in the previous section, a call was made to a method named pageInRange(), which takes as arguments an array of PageRange objects and a page number. The role of the pageInRange() method is to identify whether the specified page number is within the ranges specified and may be implemented within the MyPrintDocumentAdapter class in the MainActivity.java class as follows:

public class MyPrintDocumentAdapter extends PrintDocumentAdapter {

.

.

       private boolean pageInRange(PageRange[] pageRanges, int page)

  ...

79.7 Drawing the Content on the Page Canvas

We have now reached the point where some code needs to be written to draw the content on the pages so that they are ready for printing. The content that gets drawn is completely application specific and limited only by what can be achieved using the Android Canvas class. For the purposes of this example, however, some simple text and graphics will be drawn on the canvas.

The onWrite() method has been designed to call a method named drawPage() which takes as arguments the PdfDocument.Page object representing the current page and an integer representing the page number. Within the MainActivity.java file this method should now be implemented as follows:

package com.ebookfrenzy.customprint;

.

.

import android.graphics.Canvas;

import android.graphics.Color;

import android.graphics.Paint;

 

public class MainActivity extends AppCompatActivity {

.

.

       public static class...

79.8 Starting the Print Job

When the “Print Document” button is touched by the user, the printDocument() onClick event handler method will be called. All that now remains before testing can commence, therefore, is to add this method to the MainActivity.java file, taking particular care to ensure that it is placed outside of the MyPrintDocumentAdapter class:

package com.ebookfrenzy.customprint;

.

.

import android.print.PrintManager;

import android.view.View;

 

public class MainActivity extends AppCompatActivity {

 

       public void printDocument(View view)

       {

           PrintManager printManager = (PrintManager) this

                   .getSystemService(Context.PRINT_SERVICE);

 

  ...

79.9 Testing the Application

Compile and run the application on an Android device or emulator that is running Android 4.4 or later. When the application has loaded, touch the “Print Document” button to initiate the print job and select a suitable target for the output (the Save to PDF option is a useful option for avoiding wasting paper and printer ink).

Check the printed output which should consist of 4 pages including text and graphics. Figure 79-3, for example, shows the four pages of the document viewed as a PDF file ready to be saved on the device.

Experiment with other print configuration options such as changing the paper size, orientation and pages settings within the print panel. Each setting change should be reflected in the printed output, indicating that the custom print document adapter is functioning correctly.

Figure 79-3

79.10 Summary

Although more complex to implement than the Android Printing framework HTML and image printing options, custom document printing provides considerable flexibility in terms of printing complex content from within an Android application. The majority of the work involved in implementing custom document printing involves the creation of a custom Print Adapter class such that it not only draws the content on the document pages, but also responds correctly as changes are made by the user to print settings such as the page size and range of pages to be printed.