diff options
author | Joe Fernandez <joefernandez@google.com> | 2013-10-30 20:50:11 -0700 |
---|---|---|
committer | Android Git Automerger <android-git-automerger@android.com> | 2013-10-30 20:50:11 -0700 |
commit | 47bdcb99155775e4fa89c3881f4842c9a8a38995 (patch) | |
tree | afe71e5a841a65f013a5397ca772fe629377925e /docs/html/training | |
parent | 9790eb41bc510f44676a85d9b04af96ca677479b (diff) | |
parent | a68a71b237a3c52601849bb6b23fff66337dc799 (diff) | |
download | frameworks_base-47bdcb99155775e4fa89c3881f4842c9a8a38995.zip frameworks_base-47bdcb99155775e4fa89c3881f4842c9a8a38995.tar.gz frameworks_base-47bdcb99155775e4fa89c3881f4842c9a8a38995.tar.bz2 |
am a68a71b2: am 720963a7: Merge "docs: Print API training for KitKat release" into klp-dev
* commit 'a68a71b237a3c52601849bb6b23fff66337dc799':
docs: Print API training for KitKat release
Diffstat (limited to 'docs/html/training')
-rw-r--r-- | docs/html/training/printing/custom-docs.jd | 362 | ||||
-rw-r--r-- | docs/html/training/printing/html-docs.jd | 175 | ||||
-rw-r--r-- | docs/html/training/printing/index.jd | 57 | ||||
-rw-r--r-- | docs/html/training/printing/photos.jd | 84 | ||||
-rw-r--r-- | docs/html/training/training_toc.cs | 24 |
5 files changed, 702 insertions, 0 deletions
diff --git a/docs/html/training/printing/custom-docs.jd b/docs/html/training/printing/custom-docs.jd new file mode 100644 index 0000000..dd0eceb --- /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 + +<div id="tb-wrapper"> +<div id="tb"> + +<h2>This lesson teaches you to</h2> +<ol> + <li><a href="#print-manager">Connect to the Print Manager</a></li> + <li><a href="#print-adapter">Create a Print Adapter</a> + <ol> + <li><a href="#doc-info">Compute print document info</a></li> + <li><a href="#write-file">Write a print document file</a></li> + </ol> + </li> + <li><a href="#draw-content">Drawing PDF Page Content</a></li> +</ol> + +</div> +</div> + +<p>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.</p> + +<p>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.</p> + +<p>This lesson shows you how you connect with the print manager, create a print adapter and + build content for printing.</p> + + +<h2 id="print-manager">Connect to the Print Manager</h2> + +<p>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.</p> + +<pre> +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); // +} +</pre> + +<p>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.</p> + +<p class="note"> + <strong>Note:</strong> 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. +</p> + + +<h2 id="print-adapter">Create a Print Adapter</h2> + +<p>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.</p> + +<p>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:</p> + +<ul> + <li>{@link android.print.PrintDocumentAdapter#onStart onStart()} - Called once at the + beginning of the print process. If your application has any one-time preparation tasks to + perform, such as getting a snapshot of the data to be printed, execute them here. Implementing + this method in your adapter is not required.</li> + <li>{@link android.print.PrintDocumentAdapter#onLayout onLayout()} - Called each time a + user changes a print setting which impacts the output, such as a different page size, + or page orientation, giving your application an opportunity to compute the layout of the + pages to be printed. At the minimum, this method must return how many pages are expected + in the printed document.</li> + <li>{@link android.print.PrintDocumentAdapter#onWrite onWrite()} - Called to render printed + pages into a file to be printed. This method may be called one or more times after each + {@link android.print.PrintDocumentAdapter#onLayout onLayout()} call.</li> + <li>{@link android.print.PrintDocumentAdapter#onFinish onFinish()} - Called once at the end + of the print process. If your application has any one-time tear-down tasks to perform, + execute them here. Implementing this method in your adapter is not required.</li> +</ul> + +<p>The following sections describe how to implement the layout and write methods, which are + critical to the functioning of a print adapter.</p> + +<p class="note"> + <strong>Note:</strong> 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. +</p> + + +<h3 id="doc-info">Compute print document info</h3> + +<p>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}: + +<pre> +@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."); + } +} +</pre> + +<p>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.</p> + +<p class="note"> + <strong>Note:</strong> 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. +</p> + +<p>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:</p> + +<pre> +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); +} +</pre> + + +<h3 id="write-file">Write a print document file</h3> + +<p>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.</p> + +<p class="note"> + <strong>Note:</strong> 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. +</p> + +<p class="note"> + <strong>Note:</strong> 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. +</p> + + +<p>The following sample demonstrates the basic mechanics of this process using the {@link + android.print.pdf.PrintedPdfDocument} class to create a PDF file:</p> + +<pre> +@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); + + ... +} +</pre> + +<p>This sample delegates rendering of PDF page content to <code>drawPage()</code> + method, which is discussed in the next section. +</p> + +<p>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. + </p> + + +<p class="note"> + <strong>Note:</strong> 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 <a href="{@docRoot}guide/components/processes-and-threads.html">Processes + and Threads</a>. +</p> + + +<h2 id="draw-content">Drawing PDF Page Content</h2> + +<p>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.</p> + +<p>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:</p> + +<pre> +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); +} +</pre> + +<p>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.</p> + +<p> + <strong>Tip:</strong> 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. +</p> diff --git a/docs/html/training/printing/html-docs.jd b/docs/html/training/printing/html-docs.jd new file mode 100644 index 0000000..2c7f8e3 --- /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 + +<div id="tb-wrapper"> +<div id="tb"> + +<h2>This lesson teaches you to</h2> +<ol> + <li><a href="#load-html">Load an HTML Document</a></li> + <li><a href="#print-job">Create a Print Job</a></li> +</ol> + +</div> +</div> + +<p>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.</p> + +<p>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.</p> + +<p>This lesson shows you how to quickly build an HTML document containing text and graphics and +use {@link android.webkit.WebView} to print it.</p> + + +<h2 id="load-html">Load an HTML Document</h2> + +<p>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.</p> + +<p>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:</p> + +<ol> + <li>Create a {@link android.webkit.WebViewClient} that starts a print job after + the HTML resource is loaded.</li> + <li>Load the HTML resource into the {@link android.webkit.WebView} object.</li> +</ol> + +<p>The following code sample demonstrates how to create a simple {@link + android.webkit.WebViewClient} and load an HTML document created on the fly:</p> + +<pre> +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; +} +</pre> + +<p class="note"> + <strong>Note:</strong> 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. +</p> + +<p class="note"> + <strong>Note:</strong> 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. +</p> + +<p> + 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: +</p> + +<pre> +webView.loadDataWithBaseURL("file:///android_asset/images/", htmlBody, + "text/HTML", "UTF-8", null); +</pre> + +<p>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.</p> + +<pre> +// Print an existing web page (remember to request INTERNET permission!): +webView.loadUrl("http://developer.android.com/about/index.html"); +</pre> + +<p>When using {@link android.webkit.WebView} for creating print documents, you should be aware of + the following limitations:</p> + +<ul> + <li>You cannot add headers or footers, including page numbers, to the document.</li> + <li>The printing options for the HTML document do not include the ability to print page + ranges, for example: Printing page 2 to 4 of a 10 page HTML document is not supported.</li> + <li>An instance of {@link android.webkit.WebView} can only process one print job at a time.</li> + <li>An HTML document containing CSS print attributes, such as landscape properties, is not + supported.</li> + <li>You cannot use JavaScript in a HTML document to trigger printing.</li> +</ul> + +<p class="note"> + <strong>Note:</strong> 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. +</p> + +<p>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: + <a href="custom-docs.html">Printing a Custom Document</a> lesson.</p> + + +<h2 id="print-job">Create a Print Job</h2> + +<p>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:</p> + +<pre> +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); +} +</pre> + +<p>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.</p> diff --git a/docs/html/training/printing/index.jd b/docs/html/training/printing/index.jd new file mode 100644 index 0000000..7b67b74 --- /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 + +<div id="tb-wrapper"> + <div id="tb"> + + <h2>Dependencies and prerequisites</h2> + + <ul> + <li>Android 4.4 (API Level 19) or higher</li> + </ul> + + </div> +</div> + +<p> + 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. +</p> + +<p> + 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. +</p> + + +<h2>Lessons</h2> + +<dl> + <dt> + <strong><a href="photos.html">Printing a Photo</a></strong> + </dt> + <dd>This lesson shows you how to print an image.</dd> + + <dt> + <strong><a href="html-docs.html">Printing an HTML Document</a></strong> + </dt> + <dd>This lesson shows you how to print an HTML document.</dd> + + <dt> + <strong><a href="custom-docs.html">Printing a Custom Document</a></strong> + </dt> + <dd>This lesson shows you how you connect to the Android print manager, create a print adapter + and build content for printing.</dd> +</dl> + + diff --git a/docs/html/training/printing/photos.jd b/docs/html/training/printing/photos.jd new file mode 100644 index 0000000..f0289ef --- /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 + +<div id="tb-wrapper"> +<div id="tb"> + +<h2>This lesson teaches you to</h2> +<ol> + <li><a href="#image">Print an Image</a></li> +</ol> + +</div> +</div> + +<p> + 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 <a href="{@docRoot}tools/support-library/index.html" + >Android Support Library</a> provides a convenient function for enabling image printing using a + minimal amount of code and simple set of print layout options. +</p> + +<p>This lesson shows you how to print an image using the v4 support library {@link + android.support.v4.print.PrintHelper} class.</p> + + +<h2 id="image">Print an Image</h2> + +<p>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:</p> + +<ul> + <li>{@link android.support.v4.print.PrintHelper#SCALE_MODE_FIT SCALE_MODE_FIT} - This + option sizes the image so that the whole image is shown within the printable area of the page. + </li> + <li>{@link android.support.v4.print.PrintHelper#SCALE_MODE_FILL SCALE_MODE_FILL} - This + option scales the image so that it fills the entire printable area of the page. Choosing this + setting means that some portion of the top and bottom, or left and right edges of the image is + not printed. This option is the default value if you do not set a scale mode.</li> +</ul> + +<p>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:</p> + +<pre> +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); +} +</pre> + +<p> + 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 <a href="{@docRoot}design/patterns/actionbar.html">Action Bar</a> design + guide. +</p> + +<p>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.</p> + +<p>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 + <a href="html-docs.html">Printing an HTML Document</a> or + <a href="custom-docs.html">Printing a Custom Document</a> + lessons.</p> + diff --git a/docs/html/training/training_toc.cs b/docs/html/training/training_toc.cs index 347f2de..547faae 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." </li> </ul> </li> + + <li class="nav-section"> + <div class="nav-section-header"> + <a href="<?cs var:toroot ?>training/printing/index.html" + description= + "How to print photos, HTML documents, and custom documents from your app." + >Printing Content</a> + </div> + <ul> + <li><a href="<?cs var:toroot ?>training/printing/photos.html"> + Photos + </a> + </li> + <li><a href="<?cs var:toroot ?>training/printing/html-docs.html"> + HTML Documents + </a> + </li> + <li><a href="<?cs var:toroot ?>training/printing/custom-docs.html"> + Custom Documents + </a> + </li> + </ul> + </li> + </ul> </li> <!-- End multimedia --> |