From 84fe617c5b3e90b961091af24ef26b9fadc8c70c Mon Sep 17 00:00:00 2001 From: Joe Fernandez Date: Tue, 29 Oct 2013 01:55:12 -0700 Subject: [PATCH] docs: Print API training for KitKat release Change-Id: Ifbe40961d4f4a6d4c0546c621174ec45c2a30911 (cherry picked from commit 0f737930b88cdc4b1ff82d7865a312e9a701a8d6) --- docs/html/training/printing/custom-docs.jd | 362 +++++++++++++++++++++++++++++ docs/html/training/printing/html-docs.jd | 175 ++++++++++++++ docs/html/training/printing/index.jd | 57 +++++ docs/html/training/printing/photos.jd | 84 +++++++ docs/html/training/training_toc.cs | 24 ++ 5 files changed, 702 insertions(+) create mode 100644 docs/html/training/printing/custom-docs.jd create mode 100644 docs/html/training/printing/html-docs.jd create mode 100644 docs/html/training/printing/index.jd create mode 100644 docs/html/training/printing/photos.jd diff --git a/docs/html/training/printing/custom-docs.jd b/docs/html/training/printing/custom-docs.jd new file mode 100644 index 000000000000..dd0eceb6dde1 --- /dev/null +++ b/docs/html/training/printing/custom-docs.jd @@ -0,0 +1,362 @@ +page.title=Printing Custom Documents +parent.title=Printing Content +parent.link=index.html + +trainingnavtop=true +next.title= +next.link= + +@jd:body + +
+ +
+ +

For some applications, such as drawing apps, page layout apps and other apps that focus on + graphic output, creating beautiful printed pages is a key feature. In this case, it is not enough + to print an image or an HTML document. The print output for these types of applications requires + precise control of everything that goes into a page, including fonts, text flow, page breaks, + headers, footers, and graphic elements.

+ +

Creating print output that is completely customized for your application requires more + programming investment than the previously discussed approaches. You must build components that + communicate with the print framework, adjust to printer settings, draw page elements and + manage printing on multiple pages.

+ +

This lesson shows you how you connect with the print manager, create a print adapter and + build content for printing.

+ + + + +

When your application manages the printing process directly, the first step after receiving a + print request from your user is to connect to the Android print framework and obtain an instance + of the {@link android.print.PrintManager} class. This class allows you to initialize a print job + and begin the printing lifecycle. The following code example shows how to get the print manager + and start the printing process.

+ +
+private void doPrint() {
+    // Get a PrintManager instance
+    PrintManager printManager = (PrintManager) getActivity()
+            .getSystemService(Context.PRINT_SERVICE);
+
+    // Set job name, which will be displayed in the print queue
+    String jobName = getActivity().getString(R.string.app_name) + " Document";
+
+    // Start a print job, passing in a PrintDocumentAdapter implementation
+    // to handle the generation of a print document
+    printManager.print(jobName, new MyPrintDocumentAdapter(getActivity()),
+            null); //
+}
+
+ +

The example code above demonstrates how to name a print job and set an instance of the {@link + android.print.PrintDocumentAdapter} class which handles the steps of the printing lifecycle. The + implementation of the print adapter class is discussed in the next section.

+ +

+ Note: The last parameter in the {@link android.print.PrintManager#print print()} + method takes a {@link android.print.PrintAttributes} object. You can use this parameter to + provide hints to the printing framework and pre-set options based on the previous printing cycle, + thereby improving the user experience. You may also use this parameter to set options that are + more appropriate to the content being printed, such as setting the orientation to landscape + when printing a photo that is in that orientation. +

+ + + + +

A print adapter interacts with the Android print framework and handles the steps of the + printing process. This process requires users to select printers and print options before creating + a document for printing. These selections can influence the final output as the user chooses + printers with different output capabilities, different page sizes, or different page orientations. + As these selections are made, the print framework asks your adapter to lay out and generate a + print document, in preparation for final output. Once a user taps the print button, the framework + takes the final print document and passes it to a print provider for output. During the printing + process, users can choose to cancel the print action, so your print adapter must also listen for + and react to a cancellation requests.

+ +

The {@link android.print.PrintDocumentAdapter} abstract class is designed to handle the + printing lifecycle, which has four main callback methods. You must implement these methods + in your print adapter in order to interact properly with the print framework:

+ + + +

The following sections describe how to implement the layout and write methods, which are + critical to the functioning of a print adapter.

+ +

+ Note: These adapter methods are called on the main thread of your application. If + you expect the execution of these methods in your implementation to take a significant amount of + time, implement them to execute within a separate thread. For example, you can encapsulate the + layout or print document writing work in separate {@link android.os.AsyncTask} objects. +

+ + +

Compute print document info

+ +

Within an implementation of the {@link android.print.PrintDocumentAdapter} class, your + application must be able to specify the type of document it is creating and calculate the total + number of pages for print job, given information about the printed page size. + The implementation of the {@link android.print.PrintDocumentAdapter#onLayout onLayout()} method in + the adapter makes these calculations and provides information about the expected output of the + print job in a {@link android.print.PrintDocumentInfo} class, including the number of pages and + content type. The following code example shows a basic implementation of the {@link + android.print.PrintDocumentAdapter#onLayout onLayout()} method for a {@link + android.print.PrintDocumentAdapter}: + +

+@Override
+public void onLayout(PrintAttributes oldAttributes,
+                     PrintAttributes newAttributes,
+                     CancellationSignal cancellationSignal,
+                     LayoutResultCallback callback,
+                     Bundle metadata) {
+    // Create a new PdfDocument with the requested page attributes
+    mPdfDocument = new PrintedPdfDocument(getActivity(), newAttributes);
+
+    // Respond to cancellation request
+    if (cancellationSignal.isCancelled() ) {
+        callback.onLayoutCancelled();
+        return;
+    }
+
+    // Compute the expected number of printed pages
+    int pages = computePageCount(newAttributes);
+
+    if (pages > 0) {
+        // Return print information to print framework
+        PrintDocumentInfo info = new PrintDocumentInfo
+                .Builder("print_output.pdf")
+                .setContentType(PrintDocumentInfo.CONTENT_TYPE_DOCUMENT)
+                .setPageCount(pages);
+                .build();
+        // Content layout reflow is complete
+        callback.onLayoutFinished(info, true);
+    } else {
+        // Otherwise report an error to the print framework
+        callback.onLayoutFailed("Page count calculation failed.");
+    }
+}
+
+ +

The execution of {@link android.print.PrintDocumentAdapter#onLayout onLayout()} method can + have three outcomes: completion, cancellation, or failure in the case where calculation of the + layout cannot be completed. You must indicate one of these results by calling the appropriate + method of the {@link android.print.PrintDocumentAdapter.LayoutResultCallback} object.

+ +

+ Note: The boolean parameter of the + {@link android.print.PrintDocumentAdapter.LayoutResultCallback#onLayoutFinished + onLayoutFinished()} method indicates whether or not the layout content has actually changed + since the last request. Setting this parameter properly allows the print framework to avoid + unnecessarily calling the {@link android.print.PrintDocumentAdapter#onWrite onWrite()} method, + essentially caching the previously written print document and improving performance. +

+ +

The main work of {@link android.print.PrintDocumentAdapter#onLayout onLayout()} is + calculating the number of pages that are expected as output given the attributes of the printer. + How you calculate this number is highly dependent on how your application lays out pages for + printing. The following code example shows an implementation where the number of pages is + determined by the print orientation:

+ +
+private int computePageCount(PrintAttributes printAttributes) {
+    int itemsPerPage = 4; // default item count for portrait mode
+
+    MediaSize pageSize = printAttributes.getMediaSize();
+    if (!pageSize.isPortrait()) {
+        // Six items per page in landscape orientation
+        itemsPerPage = 6;
+    }
+
+    // Determine number of print items
+    int printItemCount = getPrintItemCount();
+
+    return (int) Math.ceil(printItemCount / itemsPerPage);
+}
+
+ + +

Write a print document file

+ +

When it is time to write print output to a file, the Android print framework calls the {@link + android.print.PrintDocumentAdapter#onWrite onWrite()} method of your application's {@link + android.print.PrintDocumentAdapter} class. The method's parameters specify which pages should be + written and the output file to be used. Your implementation of this method must then render each + requested page of content to a multi-page PDF document file. When this process is complete, you + call the {@link android.print.PrintDocumentAdapter.WriteResultCallback#onWriteFinished + onWriteFinished()} method of the callback object.

+ +

+ Note: The Android print framework may call the {@link + android.print.PrintDocumentAdapter#onWrite onWrite()} method one or more times for every + call to {@link android.print.PrintDocumentAdapter#onLayout onLayout()}. For this reason, it is + important to set the boolean parameter of + {@link android.print.PrintDocumentAdapter.LayoutResultCallback#onLayoutFinished + onLayoutFinished()} method to {@code false} when the print content layout has not changed, + to avoid unnecessary re-writes of the print document. +

+ +

+ Note: The boolean parameter of the + {@link android.print.PrintDocumentAdapter.LayoutResultCallback#onLayoutFinished + onLayoutFinished()} method indicates whether or not the layout content has actually changed + since the last request. Setting this parameter properly allows the print framework to avoid + unnecessarily calling the {@link android.print.PrintDocumentAdapter#onLayout onLayout()} method, + essentially caching the previously written print document and improving performance. +

+ + +

The following sample demonstrates the basic mechanics of this process using the {@link + android.print.pdf.PrintedPdfDocument} class to create a PDF file:

+ +
+@Override
+public void onWrite(final PageRange[] pageRanges,
+                    final ParcelFileDescriptor destination,
+                    final CancellationSignal cancellationSignal,
+                    final WriteResultCallback callback) {
+    // Iterate over each page of the document,
+    // check if it's in the output range.
+    for (int i = 0; i < totalPages; i++) {
+        // Check to see if this page is in the output range.
+        if (containsPage(pageRanges, i)) {
+            // If so, add it to writtenPagesArray. writtenPagesArray.size()
+            // is used to compute the next output page index.
+            writtenPagesArray.append(writtenPagesArray.size(), i);
+            PdfDocument.Page page = mPdfDocument.startPage(i);
+
+            // check for cancellation
+            if (cancellationSignal.isCancelled()) {
+                callback.onWriteCancelled();
+                mPdfDocument.close();
+                mPdfDocument = null;
+                return;
+            }
+
+            // Draw page content for printing
+            drawPage(page);
+
+            // Rendering is complete, so page can be finalized.
+            mPdfDocument.finishPage(page);
+        }
+    }
+
+    // Write PDF document to file
+    try {
+        mPdfDocument.writeTo(new FileOutputStream(
+                destination.getFileDescriptor()));
+    } catch (IOException e) {
+        callback.onWriteFailed(e.toString());
+        return;
+    } finally {
+        mPdfDocument.close();
+        mPdfDocument = null;
+    }
+    PageRange[] writtenPages = computeWrittenPages();
+    // Signal the print framework the document is complete
+    callback.onWriteFinished(writtenPages);
+
+    ...
+}
+
+ +

This sample delegates rendering of PDF page content to drawPage() + method, which is discussed in the next section. +

+ +

As with layout, execution of {@link android.print.PrintDocumentAdapter#onWrite onWrite()} + method can have three outcomes: completion, cancellation, or failure in the case where the + the content cannot be written. You must indicate one of these results by calling the + appropriate method of the {@link android.print.PrintDocumentAdapter.WriteResultCallback} object. +

+ + +

+ Note: Rendering a document for printing can be a resource-intensive operation. In + order to avoid blocking the main user interface thread of your application, you should consider + performing the page rendering and writing operations on a separate thread, for example + in an {@link android.os.AsyncTask}. + For more information about working with execution threads like asynchronous tasks, + see Processes + and Threads. +

+ + +

Drawing PDF Page Content

+ +

When your application prints, your application must generate a PDF document and pass it to + the Android print framework for printing. You can use any PDF generation library for this + purpose. This lesson shows how to use the {@link android.print.pdf.PrintedPdfDocument} class + to generate PDF pages from your content.

+ +

The {@link android.print.pdf.PrintedPdfDocument} class uses a {@link android.graphics.Canvas} + object to draw elements on an PDF page, similar to drawing on an activity layout. You can draw + elements on the printed page using the {@link android.graphics.Canvas} draw methods. The following + example code demonstrates how to draw some simple elements on a PDF document page using these + methods:

+ +
+private void drawPage(PdfDocument.Page page) {
+    Canvas canvas = page.getCanvas();
+
+    // units are in points (1/72 of an inch)
+    int titleBaseLine = 72;
+    int leftMargin = 54;
+
+    Paint paint = new Paint();
+    paint.setColor(Color.BLACK);
+    paint.setTextSize(36);
+    canvas.drawText("Test Title", leftMargin, titleBaseLine, paint);
+
+    paint.setTextSize(11);
+    canvas.drawText("Test paragraph", leftMargin, titleBaseLine + 25, paint);
+
+    paint.setColor(Color.BLUE);
+    canvas.drawRect(100, 100, 172, 172, paint);
+}
+
+ +

When using {@link android.graphics.Canvas} to draw on a PDF page, elements are specified in + points, which is 1/72 of an inch. Make sure you use this unit of measure for specifying the size + of elements on the page. For positioning of drawn elements, the coordinate system starts at 0,0 + for the top left corner of the page.

+ +

+ Tip: While the {@link android.graphics.Canvas} object allows you to place print + elements on the edge of a PDF document, many printers are not able to print to the edge of a + physical piece of paper. Make sure that you account for the unprintable edges of the page when + you build a print document with this class. +

diff --git a/docs/html/training/printing/html-docs.jd b/docs/html/training/printing/html-docs.jd new file mode 100644 index 000000000000..2c7f8e304338 --- /dev/null +++ b/docs/html/training/printing/html-docs.jd @@ -0,0 +1,175 @@ +page.title=Printing HTML Documents +parent.title=Printing Content +parent.link=index.html + +trainingnavtop=true +next.title=Printing Custom Documents +next.link=custom-docs.html + +@jd:body + +
+
+ +

This lesson teaches you to

+
    +
  1. Load an HTML Document
    2. +
  2. Create a Print Job
    3. +
+ +
+
+ +

Printing out content beyond a simple photo on Android requires composing text and graphics in a + print document. The Android framework provides a way to use HTML to compose a document and + print it with a minimum of code.

+ +

In Android 4.4 (API level 19), the {@link android.webkit.WebView} class has been updated to + enable printing HTML content. The class allows you to load a local HTML resource or download + a page from the web, create a print job and hand it off to Android's print services.

+ +

This lesson shows you how to quickly build an HTML document containing text and graphics and +use {@link android.webkit.WebView} to print it.

+ + +

Load an HTML Document

+ +

Printing an HTML document with {@link android.webkit.WebView} involves loading an HTML + resource or building an HTML document as a string. This section describes how to build an HTML + string and load it into a {@link android.webkit.WebView} for printing.

+ +

This view object is typically used as part of an activity layout. However, if your application + is not using a {@link android.webkit.WebView}, you can create an instance of the class + specifically for printing purposes. The main steps for creating this custom print view are:

+ +
    +
  1. Create a {@link android.webkit.WebViewClient} that starts a print job after + the HTML resource is loaded.
    2. +
  2. Load the HTML resource into the {@link android.webkit.WebView} object.
    3. +
+ +

The following code sample demonstrates how to create a simple {@link + android.webkit.WebViewClient} and load an HTML document created on the fly:

+ +
+private WebView mWebView;
+
+private void doWebViewPrint() {
+    // Create a WebView object specifically for printing
+    WebView webView = new WebView(getActivity());
+    webView.setWebViewClient(new WebViewClient() {
+
+            public boolean shouldOverrideUrlLoading(WebView view, String url) {
+                return false;
+            }
+
+            @Override
+            public void onPageFinished(WebView view, String url) {
+                Log.i(TAG, "page finished loading " + url);
+                createWebPrintJob(view);
+                mWebView = null;
+            }
+    });
+
+    // Generate an HTML document on the fly:
+    String htmlDocument = "<html><body><h1>Test Content</h1><p>Testing, " +
+            "testing, testing...</p></body></html>";
+    webView.loadDataWithBaseURL(null, htmlDocument, "text/HTML", "UTF-8", null);
+
+    // Keep a reference to WebView object until you pass the PrintDocumentAdapter
+    // to the PrintManager
+    mWebView = webView;
+}
+
+ +

+ Note: Make sure your call for generating a print job happens in the {@link + android.webkit.WebViewClient#onPageFinished onPageFinished()} method of the {@link + android.webkit.WebViewClient} you created in the previous section. If you don't wait until page + loading is finished, the print output may be incomplete or blank, or may fail completely. +

+ +

+ Note: The example code above holds an instance of the + {@link android.webkit.WebView} object so that is it not garbage collected before the print job + is created. Make sure you do the same in your own implementation, otherwise the print process + may fail. +

+ +

+ If you want to include graphics in the page, place the graphic files in the {@code assets/} + directory of your project and specify a base URL in the first parameter of the + {@link android.webkit.WebView#loadDataWithBaseURL loadDataWithBaseURL()} method, as shown in the + following code example: +

+ +
+webView.loadDataWithBaseURL("file:///android_asset/images/", htmlBody,
+        "text/HTML", "UTF-8", null);
+
+ +

You can also load a web page for printing by replacing the + {@link android.webkit.WebView#loadDataWithBaseURL loadDataWithBaseURL()} method with + {@link android.webkit.WebView#loadUrl loadUrl()} as shown below.

+ +
+// Print an existing web page (remember to request INTERNET permission!):
+webView.loadUrl("http://developer.android.com/about/index.html");
+
+ +

When using {@link android.webkit.WebView} for creating print documents, you should be aware of + the following limitations:

+ + + +

+ Note: The content of a {@link android.webkit.WebView} object that is included in + a layout can also be printed once it has loaded a document. +

+ +

If you want to create a more customized print output and have complete control of the content + draw on the printed page, jump to the next lesson: + Printing a Custom Document lesson.

+ + + + +

After creating a {@link android.webkit.WebView} and loading your HTML content, your + application is almost done with its part of the printing process. The next steps are accessing + the {@link android.print.PrintManager}, creating a print adapter, and finally, creating a print + job. The following example illustrates how to perform these steps:

+ +
+private void createWebPrintJob(WebView webView) {
+
+    // Get a PrintManager instance
+    PrintManager printManager = (PrintManager) getActivity()
+            .getSystemService(Context.PRINT_SERVICE);
+
+    // Get a print adapter instance
+    PrintDocumentAdapter printAdapter = webView.createPrintDocumentAdapter();
+
+    // Create a print job with name and adapter instance
+    String jobName = getString(R.string.app_name) + " Document";
+    PrintJob printJob = printManager.print(jobName, printAdapter,
+            new PrintAttributes.Builder().build());
+
+    // Save the job object for later status checking
+    mPrintJobs.add(printJob);
+}
+
+ +

This example saves an instance of the {@link android.print.PrintJob} object for use by the + application, which is not required. Your application may use this object to track the progress of + the print job as it's being processed. This approach is useful when you want to monitor the status + of the print job in you application for completion, failure, or user cancellation. Creating an + in-app notification is not required, because the print framework automatically creates a system + notification for the print job.

diff --git a/docs/html/training/printing/index.jd b/docs/html/training/printing/index.jd new file mode 100644 index 000000000000..7b67b746707b --- /dev/null +++ b/docs/html/training/printing/index.jd @@ -0,0 +1,57 @@ +page.title=Printing Content +page.tags="print","navigation","gesturedetector","scroller" + +trainingnavtop=true +startpage=true +@jd:body + +
+
+ +

Dependencies and prerequisites

+ +
    +
  • Android 4.4 (API Level 19) or higher
    • +
+ +
+
+ +

+ Android users frequently view content solely on their devices, but there are times when + showing someone a screen is not an adequate way to share information. Being able to print + information from your Android application gives users a way to see a larger version of the + content from your app or share it with another person who is not using your application. + Printing also allows them to create a snapshot of information that does not depend on having a + device, sufficient battery power, or a wireless network connection. +

+ +

+ In Android 4.4 (API level 19) and higher, the framework provides services for printing images and + documents directly from Android applications. This training describes how to enable printing in + your application, including printing images, HTML pages and creating custom documents for + printing. +

+ + +

Lessons

+ +
+
+ Printing a Photo +
+
This lesson shows you how to print an image.
+ +
+ Printing an HTML Document +
+
This lesson shows you how to print an HTML document.
+ +
+ Printing a Custom Document +
+
This lesson shows you how you connect to the Android print manager, create a print adapter + and build content for printing.
+
+ + diff --git a/docs/html/training/printing/photos.jd b/docs/html/training/printing/photos.jd new file mode 100644 index 000000000000..f0289ef0d95a --- /dev/null +++ b/docs/html/training/printing/photos.jd @@ -0,0 +1,84 @@ +page.title=Printing Photos +parent.title=Printing Content +parent.link=index.html + +trainingnavtop=true +next.title=Printing HTML Documents +next.link=html-docs.html + +@jd:body + +
+
+ +

This lesson teaches you to

+
    +
  1. Print an Image
    2. +
+ +
+
+ +

+ Taking and sharing photos is one of the most popular uses for mobile devices. If your application + takes photos, displays them, or allows users to share images, you should consider enabling printing + of those images in your application. The Android Support Library provides a convenient function for enabling image printing using a + minimal amount of code and simple set of print layout options. +

+ +

This lesson shows you how to print an image using the v4 support library {@link + android.support.v4.print.PrintHelper} class.

+ + +

Print an Image

+ +

The Android Support Library {@link android.support.v4.print.PrintHelper} class provides + a simple way to print of images. The class has a single layout option, {@link + android.support.v4.print.PrintHelper#setScaleMode setScaleMode()}, which allows you to print with + one of two options:

+ + + +

Both scaling options for {@link android.support.v4.print.PrintHelper#setScaleMode + setScaleMode()} keep the existing aspect ratio of the image intact. The following code example + shows how to create an instance of the {@link android.support.v4.print.PrintHelper} class, set the + scaling option, and start the printing process:

+ +
+private void doPhotoPrint() {
+    PrintHelper photoPrinter = new PrintHelper(getActivity());
+    photoPrinter.setScaleMode(PrintHelper.SCALE_MODE_FIT);
+    Bitmap bitmap = BitmapFactory.decodeResource(getResources(),
+            R.drawable.droids);
+    photoPrinter.printBitmap("droids.jpg - test print", bitmap);
+}
+
+ +

+ This method can be called as the action for a menu item. Note that menu items for actions that are + not always supported (such as printing) should be placed in the overflow menu. For more + information, see the Action Bar design + guide. +

+ +

After the {@link android.support.v4.print.PrintHelper#printBitmap printBitmap()} method is + called, no further action from your application is required. The Android print user interface + appears, allowing the user to select a printer and printing options. The user can then print the + image or cancel the action. If the user chooses to print the image, a print job is created and a + printing notification appears in the system bar.

+ +

If you want to include additional content in your printouts beyond just an image, you must + construct a print document. For information on creating documents for printing, see the + Printing an HTML Document or + Printing a Custom Document + lessons.

+ diff --git a/docs/html/training/training_toc.cs b/docs/html/training/training_toc.cs index 39386bc1cc66..f176437836dc 100644 --- a/docs/html/training/training_toc.cs +++ b/docs/html/training/training_toc.cs @@ -335,6 +335,30 @@ include the action bar on devices running Android 2.1 or higher." + +
  • +
    + Printing Content +
    + +
    • + -- 2.11.0