1 page.title=Printing HTML Documents 2 parent.title=Printing Content 3 parent.link=index.html 4 5 trainingnavtop=true 6 next.title=Printing Custom Documents 7 next.link=custom-docs.html 8 9 @jd:body 10 11 <div id="tb-wrapper"> 12 <div id="tb"> 13 14 <h2>This lesson teaches you to</h2> 15 <ol> 16 <li><a href="#load-html">Load an HTML Document</a></li> 17 <li><a href="#print-job">Create a Print Job</a></li> 18 </ol> 19 20 </div> 21 </div> 22 23 <p>Printing out content beyond a simple photo on Android requires composing text and graphics in a 24 print document. The Android framework provides a way to use HTML to compose a document and 25 print it with a minimum of code.</p> 26 27 <p>In Android 4.4 (API level 19), the {@link android.webkit.WebView} class has been updated to 28 enable printing HTML content. The class allows you to load a local HTML resource or download 29 a page from the web, create a print job and hand it off to Android's print services.</p> 30 31 <p>This lesson shows you how to quickly build an HTML document containing text and graphics and 32 use {@link android.webkit.WebView} to print it.</p> 33 34 35 <h2 id="load-html">Load an HTML Document</h2> 36 37 <p>Printing an HTML document with {@link android.webkit.WebView} involves loading an HTML 38 resource or building an HTML document as a string. This section describes how to build an HTML 39 string and load it into a {@link android.webkit.WebView} for printing.</p> 40 41 <p>This view object is typically used as part of an activity layout. However, if your application 42 is not using a {@link android.webkit.WebView}, you can create an instance of the class 43 specifically for printing purposes. The main steps for creating this custom print view are:</p> 44 45 <ol> 46 <li>Create a {@link android.webkit.WebViewClient} that starts a print job after 47 the HTML resource is loaded.</li> 48 <li>Load the HTML resource into the {@link android.webkit.WebView} object.</li> 49 </ol> 50 51 <p>The following code sample demonstrates how to create a simple {@link 52 android.webkit.WebViewClient} and load an HTML document created on the fly:</p> 53 54 <pre> 55 private WebView mWebView; 56 57 private void doWebViewPrint() { 58 // Create a WebView object specifically for printing 59 WebView webView = new WebView(getActivity()); 60 webView.setWebViewClient(new WebViewClient() { 61 62 public boolean shouldOverrideUrlLoading(WebView view, String url) { 63 return false; 64 } 65 66 @Override 67 public void onPageFinished(WebView view, String url) { 68 Log.i(TAG, "page finished loading " + url); 69 createWebPrintJob(view); 70 mWebView = null; 71 } 72 }); 73 74 // Generate an HTML document on the fly: 75 String htmlDocument = "<html><body><h1>Test Content</h1><p>Testing, " + 76 "testing, testing...</p></body></html>"; 77 webView.loadDataWithBaseURL(null, htmlDocument, "text/HTML", "UTF-8", null); 78 79 // Keep a reference to WebView object until you pass the PrintDocumentAdapter 80 // to the PrintManager 81 mWebView = webView; 82 } 83 </pre> 84 85 <p class="note"> 86 <strong>Note:</strong> Make sure your call for generating a print job happens in the {@link 87 android.webkit.WebViewClient#onPageFinished onPageFinished()} method of the {@link 88 android.webkit.WebViewClient} you created in the previous section. If you don't wait until page 89 loading is finished, the print output may be incomplete or blank, or may fail completely. 90 </p> 91 92 <p class="note"> 93 <strong>Note:</strong> The example code above holds an instance of the 94 {@link android.webkit.WebView} object so that is it not garbage collected before the print job 95 is created. Make sure you do the same in your own implementation, otherwise the print process 96 may fail. 97 </p> 98 99 <p> 100 If you want to include graphics in the page, place the graphic files in the {@code assets/} 101 directory of your project and specify a base URL in the first parameter of the 102 {@link android.webkit.WebView#loadDataWithBaseURL loadDataWithBaseURL()} method, as shown in the 103 following code example: 104 </p> 105 106 <pre> 107 webView.loadDataWithBaseURL("file:///android_asset/images/", htmlBody, 108 "text/HTML", "UTF-8", null); 109 </pre> 110 111 <p>You can also load a web page for printing by replacing the 112 {@link android.webkit.WebView#loadDataWithBaseURL loadDataWithBaseURL()} method with 113 {@link android.webkit.WebView#loadUrl loadUrl()} as shown below.</p> 114 115 <pre> 116 // Print an existing web page (remember to request INTERNET permission!): 117 webView.loadUrl("http://developer.android.com/about/index.html"); 118 </pre> 119 120 <p>When using {@link android.webkit.WebView} for creating print documents, you should be aware of 121 the following limitations:</p> 122 123 <ul> 124 <li>You cannot add headers or footers, including page numbers, to the document.</li> 125 <li>The printing options for the HTML document do not include the ability to print page 126 ranges, for example: Printing page 2 to 4 of a 10 page HTML document is not supported.</li> 127 <li>An instance of {@link android.webkit.WebView} can only process one print job at a time.</li> 128 <li>An HTML document containing CSS print attributes, such as landscape properties, is not 129 supported.</li> 130 <li>You cannot use JavaScript in a HTML document to trigger printing.</li> 131 </ul> 132 133 <p class="note"> 134 <strong>Note:</strong> The content of a {@link android.webkit.WebView} object that is included in 135 a layout can also be printed once it has loaded a document. 136 </p> 137 138 <p>If you want to create a more customized print output and have complete control of the content 139 draw on the printed page, jump to the next lesson: 140 <a href="custom-docs.html">Printing a Custom Document</a> lesson.</p> 141 142 143 <h2 id="print-job">Create a Print Job</h2> 144 145 <p>After creating a {@link android.webkit.WebView} and loading your HTML content, your 146 application is almost done with its part of the printing process. The next steps are accessing 147 the {@link android.print.PrintManager}, creating a print adapter, and finally, creating a print 148 job. The following example illustrates how to perform these steps:</p> 149 150 <pre> 151 private void createWebPrintJob(WebView webView) { 152 153 // Get a PrintManager instance 154 PrintManager printManager = (PrintManager) getActivity() 155 .getSystemService(Context.PRINT_SERVICE); 156 157 // Get a print adapter instance 158 PrintDocumentAdapter printAdapter = webView.createPrintDocumentAdapter(); 159 160 // Create a print job with name and adapter instance 161 String jobName = getString(R.string.app_name) + " Document"; 162 PrintJob printJob = printManager.print(jobName, printAdapter, 163 new PrintAttributes.Builder().build()); 164 165 // Save the job object for later status checking 166 mPrintJobs.add(printJob); 167 } 168 </pre> 169 170 <p>This example saves an instance of the {@link android.print.PrintJob} object for use by the 171 application, which is not required. Your application may use this object to track the progress of 172 the print job as it's being processed. This approach is useful when you want to monitor the status 173 of the print job in you application for completion, failure, or user cancellation. Creating an 174 in-app notification is not required, because the print framework automatically creates a system 175 notification for the print job.</p> 176
