Category: Kotlin

This chapter aims to provide a practical demonstration of both Android app links and the Android Studio App Link Assistant.

This chapter will add app linking support to an existing Android app, allowing an activity to be launched via an app link URL. In addition to launching the activity, the content displayed will be specified within the URL’s path.

About the Example App

The project used in this chapter is named AppLinking and is a basic app designed to allow users to find information about landmarks in London. The app uses a SQLite database accessed through a standard Android content provider class. The app has an existing database containing records for some popular tourist attractions in London. In addition to the existing database entries, the app lets the user add and delete landmark descriptions.

Currently, the app allows the existing records to be searched and new records to be added and deleted.

The project consists of two activities named AppLinkingActivity and LandmarkActivity. AppLinkingActivity is the main activity launched at app startup. This activity allows the user to enter search criteria and add records to the database. When a search locates a matching record, LandmarkActivity launches and displays the information for the related landmark.

This chapter will enhance the app to support app linking so that URLs can be used to display specific landmark records within the app.

The Database Schema

The data for the example app is contained within a file named landmarks.db located in the app -> assets –> databases folder of the project hierarchy. The database contains a single table named locations, the structure of which is outlined in Table 84-1:

Column	Type	Description
_id	String	The primary index, this column contains string values that uniquely identify the landmarks in the database.
title	String	The name of the landmark (e.g., London Bridge).
description	String	A description of the landmark.
personal	Boolean	Indicates whether the record is personal or public. This value is set to true for all records added by the user. Existing records provided with the database are set to false.

Loading and Running the Project

The project is contained within the AppLinking folder of the sample source code download archive located at the following URL:

https://www.ebookfrenzy.com/web/giraffekotlin/index.php

Having located the folder, open it within Android Studio and run the app on a device or emulator. Once the app is launched, the screen illustrated in Figure 84-1 below will appear:

As currently implemented, landmarks are located using the ID for the location. The default database configuration currently contains two records referenced by the IDs “londonbridge” and “toweroflondon”. Test the search feature by entering londonbridge into the ID field and clicking the Find button. When a matching record is found, the second activity (LandmarkActivity) is launched and passed information about the record to be displayed. This information takes the form of extra data added to the Intent object. LandmarkActivity uses this information to extract the record from the database and display it to the user using the screen shown in Figure 84-2.

Adding the URL Mapping

Now that the app has been loaded into Android Studio and tested, we can add app link support. The objective is for the LandmarkActivity screen to launch and display information in response to an app link click. This is achieved by mapping a URL to LandmarkActivity. For this example, the format of the URL will be as follows:

http://<website domain>/landmarks/<landmarkId>Code language: plaintext (plaintext)

When all of the steps have been completed, the following URL should, for example, cause the app to display information about the Tower of London:

http://www.yourdomain.com/landmarks/toweroflondonCode language: plaintext (plaintext)

To add a URL mapping to the project, begin by opening the App Links Assistant using the Tools -> App Links Assistant menu option. Once open, the assistant should appear as shown in Figure 84-3:

Click on the Open URL Mapping Editor button to map a URL to an activity. Within the mapping screen, click on the ‘+’ button (highlighted in Figure 84-4) to add a new URL:

In the Host field of the Add URL Mapping dialog, enter either the URL for your own website. If you do not have a website to use for this tutorial, you can still follow most of this chapter using http://www.example.com, though it will not be possible to test features that require the presence of a Digital Asset Links file.

The Path field (marked B in Figure 84-5 below) is where the path component of the URL is declared. The path must be prefixed with / so enter /landmarks into this field.

The Path menu (B) provides the following three path-matching options:

• path – The URL must match the path component of the URL exactly to launch the activity. For example, if the path is set to /landmarks, http://www.example.com/landmarks will be considered a match. A URL of http:// www.example.com/landmarks/londonbridge, however, will not be considered a match.
• pathPrefix – The specified path is only considered as the prefix. Additional path components may be included after the /landmarks component (for example, http://www.example.com/landmarks/londonbridge will still be considered a match).
• pathPattern – Allows the path to be specified using pattern matching in the form of basic regular expressions and wildcards, for example, landmarks/*/[l-L]ondon/*

Since the path in this example is a prefix to the landmark ID component, select the pathPrefix menu option.

Finally, use the Activity menu (C) to select LandmarkActivity as the activity to be launched in response to the app link:

After completing the settings in the dialog, click the OK button to commit the changes. Check that the URL is correctly formatted and assigned to the appropriate activity by entering the following URL into the Check URL Mapping field of the mapping screen (where <your domain> is set to the domain specified in the Host field above) :

http://<your domain>/landmarks/toweroflondonCode language: plaintext (plaintext)

If the mapping is configured correctly, LandmarkActivity will be listed as the mapped activity:

The latest version of Android requires that App Links be declared for HTTP and HTTPS protocols, even if only one is being used. Therefore, before proceeding to the next step, repeat the above steps to add the HTTPS version of the URL to the list.

The next step will also be performed in the URL mapping screen of the App Links Assistant, so leave the screen selected.

Adding the Intent Filter

As explained in the previous chapter, an intent filter is needed to launch the target activity in response to an app link click. In fact, when the URL mapping was added, the intent filter was automatically added to the project manifest file. With the URL mapping selected in the App Links Assistant URL mapping list, scroll down the screen until the intent filter Preview section comes into view. The preview should contain the modified AndroidManifest.xml file with the newly added intent filters included:

Although App Links Assistant has added intent filters for us, it may not have included the autoVerify setting needed when working with app links. Open the manifests -> AndroidManifest.xml file and add this setting to the two intent filters as follows:

<intent-filter android:autoVerify="true">
.
.
    <data
        android:scheme="http"
        android:host="www.ebookfrenzy.com"
        android:pathPrefix="/landmarks" />
</intent-filter>
<intent-filter android:autoVerify="true">
.
.
    <data
        android:scheme="https"
        android:host="www.ebookfrenzy.com"
        android:pathPrefix="/landmarks" />Code language: Kotlin (kotlin)

Adding Intent Handling Code

The steps taken so far ensure that the correct activity is launched in response to an appropriately formatted app link URL. The next step is to handle the intent within the LandmarkActivity class so that the correct record is extracted from the database and displayed to the user. Before making any changes to the code within the LandmarkActivity.kt file, it is worthwhile reviewing some areas of the existing code. Open the LandmarkActivity.kt file in the code editor and locate the onCreate() and handleIntent() methods which should currently read as follows:

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    binding = ActivityLandmarkBinding.inflate(layoutInflater)
    setContentView(binding.root) 
 
    handleIntent(intent)
}
 
private fun handleIntent(intent: Intent) {
 
    val landmarkId = intent.getStringExtra(AppLinkingActivity.LANDMARK_ID)
 
    landmarkId?.let {
        displayLandmark(it)
    }
}Code language: Kotlin (kotlin)

In its current form, the code expects to find the landmark ID within the extra data of the Intent bundle. Since the activity can now be launched by an app link, this code must be changed to handle both scenarios. Begin by deleting the call to handleIntent() in the onCreate() method:

override fun onCreate(savedInstanceState: Bundle?) {
.
.
    handleIntent(intent)
}Code language: Kotlin (kotlin)

To add the initial app link intent handling code, return to the App Links Assistant panel and click on the Select Activity button listed under step 2. Within the activity selection dialog, select the LandmarkActivity entry before clicking on the Insert Code button:

Return to the LandmarkActivity.kt file and note that the following code has been inserted into the onCreate() method (note that you can manually add this code if Android Studio is unable to complete the request):

// ATTENTION: This was auto-generated to handle app links.
val appLinkIntent: Intent = intent
val appLinkAction: String? = appLinkIntent.action
val appLinkData: Uri? = appLinkIntent.dataCode language: Kotlin (kotlin)

This code accesses the Intent object and extracts the Action string and Uri. If the activity launch results from an app link, the action string will be set to android.intent.action.VIEW, which matches the action declared in the intent filter added to the manifest file. If, on the other hand, the activity was launched by the standard intent launching code in the findLandmark() method of the main activity, the action string will be null. By checking the value assigned to the action string, code can be written to identify how the activity was launched and take appropriate action:

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    binding = ActivityLandmarkBinding.inflate(layoutInflater)
    setContentView(binding.root) 
 
    // ATTENTION: This was auto-generated to handle app links.
    val appLinkIntent: Intent = intent
    val appLinkAction: String? = appLinkIntent.action
    val appLinkData: Uri? = appLinkIntent.data
 
    val landmarkId = appLinkData?.lastPathSegment
 
    if (landmarkId != null) {
        displayLandmark(landmarkId)
    }
}Code language: Kotlin (kotlin)

All that remains is to add some additional code to the method to identify the last component in the app link URL path and to use that as the landmark ID when querying the database:

override fun onCreate(savedInstanceState: Bundle?) {
.
.
    // ATTENTION: This was auto-generated to handle app links.
    val appLinkIntent = intent
    val appLinkAction = appLinkIntent.action
    val appLinkData = appLinkIntent.data
 
    if (appLinkAction != null) {
 
        if (appLinkAction == "android.intent.action.VIEW") {
 
            val landmarkId = appLinkData?.lastPathSegment
 
            if (landmarkId != null) {
                displayLandmark(landmarkId)
            }
        }
    } else {
        handleIntent(appLinkIntent)
    }
}Code language: Kotlin (kotlin)

If the action string is not null, a check is made to verify that it is set to android.intent.action.VIEW before extracting the last component of the Uri path. This component is then used as the landmark ID when making the database query. If, on the other hand, the action string is null, the existing handleIntent() method is called to extract the ID from the intent data.

Testing the App

Run the app on a device or emulator and make sure it is still possible to search for the example landmarks. We have now successfully added app link support to the app. If you specified your own website URL for the app links, we can now take the example one step further by creating and installing a Digital Asset Links file.

Creating the Digital Asset Links File

As outlined in the chapter entitled An Android Intents Overview, to fully support app links, we need to install a Digital Asset Links file on the website referenced in the app link. Begin by following the steps outlined in An Android Intents Overview to locate your debug.keystore file and identify your SHA256 fingerprint.

Next, open the following page in a web browser:

https://developers.google.com/digital-asset-links/tools/generator

Once the page has loaded, enter your website URL into the Hosting site domain field, com.ebookfrenzy.applinking as the App package name, and your SHA256 fingerprint into the App package fingerprint (SHA256) field:

Click the Generate statement button to display the generated statement and place it in a file named assetlinks.json in a folder named .well-known on your web server. Return to the generator page and click on the Test statement button to verify that the file is in the correct location. On a successful test, output similar to the following will appear:

Assuming a successful test, we are now ready to try out the app link.

Testing the App Link

Test that the intent handling works by returning to the App Links Assistant panel and clicking on the Test App Links button. When prompted for a URL to test, enter the URL (using the domain referenced in the app link mapping) for the londonbridge landmark ID before clicking on the Run Test button:

Once the button has been clicked, the Landmark activity should launch on the device or emulator and display information about London Bridge.

Summary

This chapter has demonstrated the steps for implementing App Link support within an Android app project, including using the App Link Assistant in Android Studio, App Link URL mapping, intent filters, handling website association using Digital Asset Links file entries, and App Link testing.

As technology evolves, the traditional distinction between web and mobile content is beginning to blur. One area where this is particularly true is the growing popularity of progressive web apps, where web apps look and behave much like traditional mobile apps.

Another trend involves making the content within mobile apps discoverable through web searches and via URL links. In the context of Android app development, the App Links feature is designed to make it easier for users to discover and access content stored within an Android app, even if the user does not have the app installed.

An Overview of Android App Links

An app link is a standard HTTP URL that is an easy way to link directly to a particular place in your app from an external source such as a website or app. App links (also called deep links) are used primarily to encourage users to engage with an app and to allow users to share app content.

App link implementation is a multi-step process that involves the addition of intent filters to the project manifest, implementing link handling code within the associated app activities, and the use of digital asset links files to associate app and web-based content.

These steps can be performed manually by making changes within the project or automatically using the Android Studio App Links Assistant.

These steps can be performed manually by making project changes or automatically using the Android Studio App Links Assistant.

The remainder of this chapter will outline app links implementation in terms of the changes that must be made to a project. The next chapter (An Android Studio App Links Tutorial) will demonstrate the use of the App Links Assistant to achieve the same results.

App Link Intent Filters

An app link URL needs to be mapped to a specific activity within an app project. This is achieved by adding intent filters to the project’s AndroidManifest.xml file designed to launch an activity in response to an android.intent.action.VIEW action. The intent filters are declared within the element for the activity to be launched and must contain the data outlining the scheme, host, and path of the app link URL. The following manifest fragment, for example, declares an intent filter to launch an activity named MyActivity when an app link matching http:// www.example.com/welcome is detected:

<activity android:name="com.ebookfrenzy.myapp.MyActivity">
 
    <intent-filter android:autoVerify="true">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
 
        <data
            android:scheme="http"
            android:host="www.example.com"
            android:pathPrefix="/welcome" />
    </intent-filter>
</activity>Code language: HTML, XML (xml)

The order in which ambiguous intent filters are handled can be specified using the order property of the intent filter tag as follows:

<application>
    <activity android:name=" com.ebookfrenzy.myapp.MyActivity">
        <intent-filter android:autoVerify="true" android:order="1">
.
.Code language: HTML, XML (xml)

The intent filter will cause the app link to launch the correct activity, but code must still be added to the target activity to handle the intent appropriately.

Handling App Link Intents

In most cases, the launched activity will need to gain access to the app link URL and take specific action based on how the URL is structured. Continuing from the above example, the activity will likely display different content when launched via a URL containing a path of /welcome/newuser than one with the path set to /welcome/existinguser.

When the link launches the activity, it is passed an intent object containing data about the action which launched the activity, including a Uri object containing the app link URL. Within the initialization stages of the activity, code can be added to extract this data as follows:

val appLinkIntent = intent
val appLinkAction = appLinkIntent.action 
val appLinkData = appLinkIntent.dataCode language: Kotlin (kotlin)

Having obtained the Uri for the app link, the various components that make up the URL path can be used to decide the actions to perform within the activity. In the following code example, the last component of the URL is used to identify whether content should be displayed for a new or existing user:

val userType = appLinkData.lastPathSegment
 
if (userType == "newuser") {
    // display new user content
} else {
    // display existing user content
}Code language: Kotlin (kotlin)

Associating the App with a Website

Before an app link will work, an app link URL must be associated with the website on which the app link is based. This is achieved by creating a Digital Asset Links file named assetlinks.json and installing it within the website’s .well-known folder. Note that digital asset linking is only possible for websites that are HTTPS based.

A digital asset links file comprises a relation statement granting permission for a target app to be launched using the website’s link URLs and a target statement declaring the companion app package name and SHA-256 certificate fingerprint for that project. A typical asset link file might, for example, read as follows:

[{
    "relation": ["delegate_permission/common.handle_all_urls"],
    "target" : { "namespace": "android_app",
      "package_name": "<app package name here>",
                 "sha256_cert_fingerprints": ["<app certificate here>"] }
}]Code language: JSON / JSON with Comments (json)

The assetlinks.json file can contain multiple digital asset links, allowing a single website to be associated with more than one companion app.

Summary

Android App Links allow app activities to be launched via URL links from external websites and other apps. App links are implemented using intent filters within the project manifest file and intent handling code within the launched activity. Using a Digital Asset Links file, it is also possible to associate the domain name used in an app link with the corresponding website. Once the association has been established, Android no longer needs to ask the user to select the target app when an app link is used.

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 using the custom document printing feature of the Printing framework.

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 as shapes, colors, text, and images. The canvases are represented by instances of the Android Canvas class, 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, some steps 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 to store the document pages.
• Add pages to the PdfDocument in the form of PdfDocument.Page instances.
• Obtain references to the Canvas objects associated with the document pages.
• Draw content onto the canvases.
• Write the PDF document to a destination output stream provided by the Printing framework.
• Notify the Printing framework that the document is ready to print.

This chapter will provide an overview of these steps, followed by a detailed tutorial designed to demonstrate the implementation of custom document printing within Android applications.

Custom Print Adapters

The role of the print adapter is to provide the Printing framework with the content to be printed and to ensure that it is formatted correctly for the user’s chosen preferences (considering factors such as paper size and page orientation).

Much of this work is performed by the print adapters provided as part of the Android Printing framework and designed for these specific printing tasks when printing HTML and images. When printing a web page, for example, a print adapter is created for us when a call is made to the createPrintDocumentAdapter() method of an instance of the WebView class.

In the case of custom document printing, however, it is the responsibility of the application developer to design the print adapter and implement the code to draw and format the content in preparation for printing.

Custom print adapters are created by sub-classing the PrintDocumentAdapter class and overriding a set of callback methods within that class which will be called by the Printing framework at various stages in the print process. These callback methods can be summarized as follows:

· onStart() – This method is called when the printing process begins and is provided so that the application code can perform any necessary tasks to create the print job. Implementation of this method within the PrintDocumentAdapter sub-class is optional.

· onLayout() – This callback method is called after the call to the onStart() method and then again each time the user makes changes to the print settings (such as changing the orientation, paper size, or color settings). This method should adapt the content and layout to accommodate these changes. Once these changes are completed, the method must return the number of pages to be printed. Implementation of the onLayout() method within the PrintDocumentAdapter sub-class is mandatory.

· onWrite() – This method is called after each call to onLayout() and is responsible for rendering the content on the canvases of the pages to be printed. Amongst other arguments, this method is passed a file descriptor to which the resulting PDF document must be written once rendering is complete. A call is then made to the onWriteFinished() callback method passing through an argument containing information about the page ranges to be printed. Implementation of the onWrite() method within the PrintDocumentAdapter sub-class is mandatory.

· onFinish() – An optional method which, if implemented, is called once by the Printing framework when the printing process is completed, thereby providing the application the opportunity to perform any clean-up operations that may be necessary.

Preparing the Custom Document Printing Project

Select the New Project option from the welcome screen and, within the resulting new project dialog, choose the Empty Views 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 Kotlin.

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 Common 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 82-1:

When the button is selected within the application, it will be required to call a method to initiate the document printing process. Remaining within the Attributes tool window, set the onClick property to call a method named printDocument.

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.kt file, add the template for this new class so that it reads as follows:

package com.ebookfrenzy.customprint
 
import androidx.appcompat.app.AppCompatActivity
import android.os.Bundle
import android.os.ParcelFileDescriptor
import android.print.PageRange
import android.print.PrintAttributes
import android.print.PrintDocumentAdapter
import android.os.CancellationSignal
import android.content.Context
 
class MainActivity : AppCompatActivity() {
 
    inner class MyPrintDocumentAdapter(private var context: Context) 
                                             : PrintDocumentAdapter() {
 
        override fun onLayout(oldAttributes: PrintAttributes,
                              newAttributes: PrintAttributes,
                              cancellationSignal: CancellationSignal?,
                              callback: LayoutResultCallback?,
                              metadata: Bundle?) {
        }
 
        override fun onWrite(pageRanges: Array<out PageRange>?,
                             destination: ParcelFileDescriptor?,
                             cancellationSignal: CancellationSignal?,
                             callback: WriteResultCallback?) {
 
        }
    }
.
.
}Code language: Kotlin (kotlin)

As the new class currently stands, it contains a constructor method to be called when a new class instance is created. The constructor takes the context of the calling activity as an argument, which is then stored so that it can be referenced later in the two callback methods.

With the class outline established, the next step is implementing the two callback methods, beginning with onLayout().

Implementing the onLayout() Callback Method

Remaining within the MainActivity.kt 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
 
class MainActivity : AppCompatActivity() {
.
.
}Code language: Kotlin (kotlin)

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

inner class MyPrintDocumentAdapter(private var context: Context) : 
                                    PrintDocumentAdapter() {
    private var pageHeight: Int = 0
    private var pageWidth: Int = 0
    private var myPdfDocument: PdfDocument? = null
    private var totalpages = 4
.
.
}Code language: Kotlin (kotlin)

Note that for this example, a four-page document will be printed. In more complex situations, the application will most likely need to dynamically calculate the number of pages to be printed based on the quantity and layout of the content in relation to the user’s paper size and page orientation selections.

With the variables declared, implement the onLayout() method as outlined in the following code listing:

override fun onLayout(oldAttributes: PrintAttributes?,
                      newAttributes: PrintAttributes?,
                      cancellationSignal: CancellationSignal?,
                      callback: LayoutResultCallback?,
                      metadata: Bundle?) {
 
    myPdfDocument = PrintedPdfDocument(context, newAttributes)
 
    val height = newAttributes.mediaSize?.heightMils
    val width = newAttributes.mediaSize?.heightMils
 
    height?.let {
        pageHeight = it / 1000 * 72
    }
 
    width?.let {
        pageWidth = it / 1000 * 72
    }
 
    cancellationSignal?.let {
        if (it.isCanceled) {
            callback?.onLayoutCancelled()
            return
        }
    }
 
    if (totalpages > 0) {
        val builder =
                PrintDocumentInfo.Builder("print_output.pdf").setContentType(
                        PrintDocumentInfo.CONTENT_TYPE_DOCUMENT)
                        .setPageCount(totalpages)
 
        val info = builder.build()
        callback?.onLayoutFinished(info, true)
    } else {
        callback?.onLayoutFailed("Page count is zero.")
    }
}Code language: Kotlin (kotlin)

This method performs quite a few tasks, each requiring some detailed explanation.

To begin with, a new PDF document is created as a PdfDocument class instance. One of the arguments passed into the onLayout() method when the Printing framework calls it is an object of type PrintAttributes containing details about the paper size, resolution, and color settings the user selects for the print output. These settings are used when creating the PDF document, along with the context of the activity previously stored for us by our constructor method:

myPdfDocument = PrintedPdfDocument(context, newAttributes)Code language: Kotlin (kotlin)

The method then uses the PrintAttributes object to extract the height and width values for the document pages. These dimensions are stored in the object as thousandths of an inch. Since the methods that will use these values later in this example work in units of 1/72 of an inch, these numbers are converted before they are stored:

val height = newAttributes?.mediaSize?.heightMils
val width = newAttributes?.mediaSize?.heightMils
 
height?.let {
    pageHeight = it / 1000 * 72
}
 
width?.let {
    pageWidth = it / 1000 * 72
}Code language: Kotlin (kotlin)

Although this example does not make use of the user’s color selection, this property can be obtained via a call to the getColorMode() method of the PrintAttributes object, which will return a value of either COLOR_MODE_COLOR or COLOR_MODE_MONOCHROME.

When the onLayout() method is called, it is passed an object of type LayoutResultCallback. This object provides a way for the method to communicate status information back to the Printing framework via a set of methods. For example, the onLayout() method will be called if the user cancels the print process. The fact that the process has been canceled is indicated via a setting within the CancellationSignal argument. If a cancellation is detected, the onLayout() method must call the onLayoutCancelled() method of the LayoutResultCallback object to notify the Print framework that the cancellation request was received and that the layout task has been canceled:

cancellationSignal?.let {
    if (it.isCanceled) {
        callback?.onLayoutCancelled()
        return
    }
}Code language: Kotlin (kotlin)

When the layout work is complete, the method is required to call the onLayoutFinished() method of the LayoutResultCallback object, passing through two arguments. The first argument is a PrintDocumentInfo object containing information about the document to be printed. This information consists of the name of the PDF document, the type of content (in this case, a document rather than an image), and the page count. The second argument is a Boolean value indicating whether or not the layout has changed since the last call made to the onLayout() method:

if (totalpages > 0) {
    val builder = PrintDocumentInfo.Builder("print_output.pdf").setContentType(
            PrintDocumentInfo.CONTENT_TYPE_DOCUMENT)
            .setPageCount(totalpages)
 
    val info = builder.build()
    callback?.onLayoutFinished(info, true)
} else {
    callback?.onLayoutFailed("Page count is zero.")
}Code language: Kotlin (kotlin)

If the page count is zero, the code reports this failure to the Printing framework via a call to the onLayoutFailed() method of the LayoutResultCallback object.

The call to the onLayoutFinished() method notifies the Printing framework that the layout work is complete, triggering a call to the onWrite() method.

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
.
.
override fun onWrite(pageRanges: Array<out PageRange>?,
                     destination: ParcelFileDescriptor,
                     cancellationSignal: android.os.CancellationSignal?,
                     callback: WriteResultCallback?) {
 
    for (i in 0 until totalpages) {
        if (pageInRange(pageRanges, i)) {
            val newPage = PdfDocument.PageInfo.Builder(pageWidth,
                    pageHeight, i).create()
 
            val page = myPdfDocument?.startPage(newPage)
 
            cancellationSignal?.let {
                if (it.isCanceled) {
                    callback?.onWriteCancelled()
                    myPdfDocument?.close()
                    myPdfDocument = null
                    return
                }
            }
            page?.let {
                drawPage(it, i)
            }
            myPdfDocument?.finishPage(page)
        }
    }
 
    try {
        myPdfDocument?.writeTo(FileOutputStream(
                destination?.fileDescriptor))
    } catch (e: IOException) {
        callback?.onWriteFailed(e.toString())
        return
    } finally {
        myPdfDocument?.close()
        myPdfDocument = null
    }
 
    callback?.onWriteFinished(pageRanges)
}Code language: Kotlin (kotlin)

The onWrite() method starts by looping through each page in the document. However, it is important to consider that the user may have requested that only some of the pages that make up the document be printed. The Printing framework user interface panel provides the option to specify specific pages or ranges of pages to be printed. Figure 82-2, for example, shows the print panel configured to print pages 1-4, page 9, and pages 1113 of a document.

When writing the pages to the PDF document, the onWrite() method must take steps to ensure that only those pages specified by the user are printed. To make this possible, the Printing framework passes through as an argument an array of PageRange objects indicating the ranges of pages to be printed. In the above onWrite() implementation, the pageInRange() method is called for each page to verify that the page is within the specified ranges. The code for the pageInRange() method will be implemented later in this chapter.

for (i in 0 until totalpages) {
    if (pageInRange(pageRanges, i)) {Code language: Kotlin (kotlin)

For each page that is within any specified ranges, a new PdfDocument.Page object is created. When creating a new page, the height and width values previously stored by the onLayout() method are passed through as arguments so that the page size matches the print options selected by the user:

val newPage = PageInfo.Builder(pageWidth, pageHeight, i).create()
 
val page = myPdfDocument?.startPage(newPage)Code language: Kotlin (kotlin)

As with the onLayout() method, the onWrite() method is required to respond to cancellation requests. In this case, the code notifies the Printing framework that the cancellation has been performed before closing and dereferencing the myPdfDocument variable:

cancellationSignal?.let {
    if (it.isCanceled) {
        callback?.onWriteCancelled()
        myPdfDocument?.close()
        myPdfDocument = null
        return
    }
}Code language: Kotlin (kotlin)

As long as the print process has not been canceled, the method calls a method to draw the content on the current page before calling the finishedPage() method on the myPdfDocument object.

page?.let {
    drawPage(it, i)
}
myPdfDocument?.finishPage(page)Code language: Kotlin (kotlin)

The drawPage() method is responsible for drawing the content onto the page and will be implemented once the onWrite() method is complete.

When the required number of pages have been added to the PDF document, the document is then written to the destination stream using the file descriptor, which is passed through as an argument to the onWrite() method. If, for any reason, the write operation fails, the method notifies the framework by calling the onWriteFailed() method of the WriteResultCallback object (also passed as an argument to the onWrite() method).

try {
    myPdfDocument?.writeTo(FileOutputStream(
            destination?.fileDescriptor))
} catch (e: IOException) {
    callback?.onWriteFailed(e.toString())
    return
} finally {
    myPdfDocument?.close()
    myPdfDocument = null
}Code language: Kotlin (kotlin)

Finally, the onWriteFinish() method of the WriteResultsCallback object is called to notify the Printing framework that the document is ready to be printed.

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 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.kt class as follows:

inner class MyPrintDocumentAdapter(private var context: Context) : 
                                    PrintDocumentAdapter() {
.
.
   private fun pageInRange(pageRanges: Array<out PageRange>?, page: Int): 
        Boolean {
        pageRanges?.let {
            for (i in it.indices) {
                if (page >= it[i].start && page <= it[i].end)
                    return true
            }
        }
        return false
    }
.
.
}Code language: Kotlin (kotlin)

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. In 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.kt file, this method should now be implemented as follows:

package com.ebookfrenzy.customprint
.
.
import android.graphics.Color
import android.graphics.Paint
 
class MainActivity : AppCompatActivity() {
.
.
   inner class MyPrintDocumentAdapter(private var context: Context) : 
                                    PrintDocumentAdapter() {
 
        private fun drawPage(page: PdfDocument.Page,
                             pagenumber: Int) {
            var pagenum = pagenumber
            val canvas = page.canvas
 
            pagenum++ // Make sure page numbers start at 1
 
            val titleBaseLine = 72
            val leftMargin = 54
 
            val paint = Paint()
            paint.color = Color.BLACK
            paint.textSize = 40f
            canvas.drawText(
                    "Test Print Document Page " + pagenum,
                    leftMargin.toFloat(),
                    titleBaseLine.toFloat(),
                    paint)
 
            paint.textSize = 14f
            canvas.drawText("This is some test content to verify that custom document printing works", leftMargin.toFloat(), (titleBaseLine + 35).toFloat(), paint)
 
            if (pagenum % 2 == 0)
                paint.color = Color.RED
            else
                paint.color = Color.GREEN
 
            val pageInfo = page.info
 
            canvas.drawCircle((pageInfo.pageWidth / 2).toFloat(),
                    (pageInfo.pageHeight / 2).toFloat(),
                    150f,
                    paint)
        }
.
.
}Code language: Kotlin (kotlin)

Page numbering within the code starts at 0. Since documents traditionally start at page 1, the method begins by incrementing the stored page number. A reference to the Canvas object associated with the page is then obtained, and some margin and baseline values are declared:

var pagenum = pagenumber
val canvas = page.canvas
 
pagenum++ // Make sure page numbers start at 1
 
val titleBaseLine = 72
val leftMargin = 54Code language: Kotlin (kotlin)

Next, the code creates Paint and Color objects to be used for drawing, sets a text size, and draws the page title text, including the current page number:

val paint = Paint()
paint.color = Color.BLACK
paint.textSize = 40f
canvas.drawText(
        "Test Print Document Page " + pagenum,
        leftMargin.toFloat(),
        titleBaseLine.toFloat(),
        paint)Code language: Kotlin (kotlin)

The text size is then reduced, and some body text is drawn beneath the title:

paint.textSize = 14f
canvas.drawText("This is some test content to verify that custom document printing works", leftMargin.toFloat(), (titleBaseLine + 35).toFloat(), paint)Code language: Kotlin (kotlin)

The last task performed by this method involves drawing a circle (red on even-numbered pages and green on odd). Having ascertained whether the page is odd or even, the method obtains the height and width of the page before using this information to position the circle in the center of the page:

if (pagenum % 2 == 0)
    paint.color = Color.RED
else
    paint.color = Color.GREEN
 
val pageInfo = page.info
 
canvas.drawCircle((pageInfo.pageWidth / 2).toFloat(),
        (pageInfo.pageHeight / 2).toFloat(),
        150f, paint)Code language: Kotlin (kotlin)

Having drawn on the canvas, the method returns control to the onWrite() method. With the completion of the drawPage() method, the MyPrintDocumentAdapter class is now finished.

Starting the Print Job

When the user touches the “Print Document” button, 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.kt 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
 
class MainActivity : AppCompatActivity() {
 
    fun printDocument(view: View) {
        val printManager = this
                .getSystemService(Context.PRINT_SERVICE) as PrintManager
 
        val jobName = this.getString(R.string.app_name) + " Document"
 
        printManager.print(jobName, MyPrintDocumentAdapter(this), null)
    }
.
.
}Code language: Kotlin (kotlin)

This method obtains a reference to the Print Manager service running on the device before creating a new String object to serve as the job name for the print task. Finally, the print() method of the Print Manager is called to start the print job, passing through the job name and an instance of our custom print document adapter class.

Testing the Application

Compile and run the application on an Android device or emulator. 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 useful for avoiding wasting paper and printer ink).

Check the printed output, which should consist of 4 pages, including text and graphics. Figure 82-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 page settings within the print panel. The printed output should reflect each setting change, indicating that the custom print document adapter functions correctly.

Summary

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

As outlined in the previous chapter, entitled “Printing with the Android Printing Framework”, the Android Printing framework can print both web pages and dynamically created HTML content. While there is much similarity between these two approaches to printing, there are also some subtle differences that need to be considered. This chapter will work through the creation of two example applications to bring some clarity to these two printing options.

Creating the HTML Printing Example Application

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

Enter HTMLPrint into the Name field and specify com.ebookfrenzy.htmlprint 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 Kotlin.

Printing Dynamic HTML Content

The first stage of this tutorial is to add code to the project to create some HTML content and send it to the Printing framework as a print job.

Begin by locating the MainActivity.kt file (located in the Project tool window under app -> java -> com .ebookfrenzy.htmlprint) and loading it into the editing panel. Once loaded, modify the code so that it reads as outlined in the following listing:

package com.ebookfrenzy.htmlprint
 
import androidx.appcompat.app.AppCompatActivity
import android.os.Bundle
import android.print.PrintAttributes
import android.print.PrintManager
import android.webkit.WebResourceRequest
import android.webkit.WebView
import android.webkit.WebViewClient
import android.content.Context
 
class MainActivity : AppCompatActivity() {
 
    private var myWebView: WebView? = null
 
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_html_print)
 
        printWebView()
    }
 
    private fun printWebView() {
 
        val webView = WebView(this)
        webView.webViewClient = object : WebViewClient() {
 
            override fun shouldOverrideUrlLoading(view: WebView,
                                request: WebResourceRequest): Boolean {
                return false
            }
 
            override fun onPageFinished(view: WebView, url: String) {
                createWebPrintJob(view)
                myWebView = null
            }
        }
 
        val htmlDocument = "<html><body><h1>Android Print Test</h1><p>" + 
                            "This is some sample content.</p></body></html>"
 
        webView.loadDataWithBaseURL(null, htmlDocument,
                "text/HTML", "UTF-8", null)
 
        myWebView = webView
    }
}Code language: Kotlin (kotlin)

The code changes begin by declaring a variable named myWebView in which will be stored a reference to the WebView instance used for the printing operation. Within the printWebView() method, an instance of the WebView class is created to which a WebViewClient instance is assigned.

The WebViewClient assigned to the web view object is configured to indicate that loading the HTML content is to be handled by the WebView instance (by returning false from the shouldOverrideUrlLoading() method). More importantly, an onPageFinished() handler method is declared and implemented to call the createWebPrintJob() method. The onPageFinished() method will be called automatically when all HTML content has been loaded into the web view. As outlined in the previous chapter, this step is necessary when printing dynamically created HTML content to ensure that the print job is only started once the content has fully loaded into the WebView.

Next, a String object is created containing some HTML to serve as the content and subsequently loaded into the web view. Once the HTML is loaded, the onPageFinished() callback method will trigger. Finally, the method stores a reference to the web view object in the previously declared myWebView variable. Without this vital step, there is a significant risk that the Java runtime system will assume that the application no longer needs the web view object and will discard it to free up memory resulting in the print job terminating before completion. All that remains in this example is to implement the createWebPrintJob() method, which is currently configured to be called by the onPageFinished() callback method. Remaining within the MainActivity.kt file, therefore, implement this method so that it reads as follows:

private fun createWebPrintJob(webView: WebView) {
 
    val printManager = this
            .getSystemService(Context.PRINT_SERVICE) as PrintManager
 
    val printAdapter = webView.createPrintDocumentAdapter("MyDocument")
 
    val jobName = getString(R.string.app_name) + " Print Test"
 
    printManager.print(jobName, printAdapter,
            PrintAttributes.Builder().build())
}Code language: Kotlin (kotlin)

This method obtains a reference to the PrintManager service and instructs the web view instance to create a print adapter. A new string is created to store the name of the print job (in this case, based on the name of the application and the word “Print Test”).

Finally, the print job is started by calling the print() method of the print manager, passing through the job name, print adapter, and a set of default print attributes.

Compile and run the application on a device or emulator running Android 5.0 or later. Once launched, the standard Android printing page should appear as illustrated in Figure 81-1.

Print to a physical printer if you have one configured, save to Google Drive, or select the option to save to a PDF file. Once the print job has been initiated, check the generated output on your chosen destination. Note that the system will request a name and location for the PDF file when using the Save to PDF option. The Downloads folder makes a good option, the contents of which can be viewed by selecting the Downloads icon (renamed Files on Android 8) located amongst the other app icons on the device

Creating the Web Page Printing Example

The second example application created in this chapter will provide the user an Overflow menu option to print the web page currently displayed within a WebView instance.

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

Enter WebPrint into the Name field and specify com.ebookfrenzy.webprint 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 Kotlin.

Removing the Floating Action Button

Selecting the Basic Views Activity template provided a context menu and a floating action button. Since the app does not require the floating action button, it can be removed before proceeding. Load the activity_main.xml layout file into the Layout Editor, select the floating action button, and tap the keyboard Delete key to remove the object from the layout. Edit the MainActivity.kt file and remove the floating action button code from the onCreate method as follows:

override fun onCreate(savedInstanceState: Bundle?) {
.
.
    // binding.fab.setOnClickListener { view ->
    //    Snackbar.make(view, "Replace with your own action", Snackbar.LENGTH_LONG)
    //        .setAction("Action", null).show()
    //}
}Code language: JavaScript (javascript)

Removing Navigation Features

As A Guide to the Android Studio Layout Editor Tool outlines, the Basic Views Activity template contains multiple fragments and buttons to navigate from one fragment to the other. These features are unnecessary for this tutorial and will cause problems later if not removed. Before moving ahead with the tutorial, modify the project as follows:

• Within the Project tool window, navigate to and double-click on the app -> res -> navigation -> nav_graph.xml file to load it into the navigation editor.

• Within the editor, select the SecondFragment entry in the graph panel and tap the keyboard delete key to remove it from the graph.
• Locate and delete the SecondFragment.kt (app -> java -> <package name> -> SecondFragment) and fragment_second.xml (app -> res -> layout -> fragment_second.xml) files.
• Locate the FirstFragment.kt file, double-click on it to load it into the editor, and remove the code from the onViewCreated() method so that it reads as follows:

override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
    super.onViewCreated(view, savedInstanceState)
 
    // binding.buttonFirst.setOnClickListener {
    //     findNavController().navigate(R.id.action_FirstFragment_to_SecondFragment)
    // }
}Code language: JavaScript (javascript)

• Edit the MainActivity.kt file and remove the following navigation code:

.
.
// private lateinit var appBarConfiguration: AppBarConfiguration
.
.
override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
.
.
    // val navController = findNavController(R.id.nav_host_fragment_content_main)
    // appBarConfiguration = AppBarConfiguration(navController.graph)
    // setupActionBarWithNavController(navController, appBarConfiguration)
}
.
.
// override fun onSupportNavigateUp(): Boolean {
// 
//     val navController = findNavController(R.id.nav_host_fragment_content_main)
//     return navController.navigateUp(appBarConfiguration)
//             || super.onSupportNavigateUp()
//}Code language: JavaScript (javascript)

Designing the User Interface Layout

Load the content_main.xml layout resource file into the Layout Editor tool if it has not already been loaded and, in Design mode, select and delete the nav_host_fragment_content_main object. From the Widgets section of the palette, drag and drop a WebView object onto the center of the device screen layout. Click the Infer constraints toolbar button and, using the Attributes tool window, change the layout_width and layout_height properties of the WebView to match constraint so that it fills the entire layout canvas, as outlined in Figure 81-2 below.

Select the newly added WebView instance and change the ID of the view to myWebView.

Before proceeding to the next step of this tutorial, an additional permission must be added to the project to enable the WebView object to access the Internet and download a web page for printing. Add this permission by locating the AndroidManifest.xml file in the Project tool window and double-clicking on it to load it into the editing panel. Once loaded, edit the XML content to add the appropriate permission line, as shown in the following listing:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.ebookfrenzy.webprint" >
 
    <uses-permission android:name="android.permission.INTERNET" />
             
    <application
        android:allowBackup="true"
.
.
</manifest>Code language: HTML, XML (xml)

Accessing the WebView from the Main Activity

As with the project in the chapter entitled An Android Studio RecyclerView Tutorial we need to be able to use view binding to access a component (in this case myWebView) contained in the content_main.xml file from within the MainActivity class. To access views within the content_main.xml file, we again need to assign it an id at the point it is included. Edit the activity_main.xml file and modify the include element so that it reads as follows:

.
.
   <include
        android:id="@+id/contentMain"
        layout="@layout/content_main" />
.
.Code language: HTML, XML (xml)

Loading the Web Page into the WebView

Before the web page can be printed, it must loaded into the WebView instance. For this tutorial, this will be performed by a call to the loadUrl() method of the WebView instance, which will be placed in a method named configureWebView() and called from within the onStart() method of the MainActivity class. Edit the MainActivity.kt file, therefore, and modify it as follows:

package com.ebookfrenzy.webprint
.
.
import android.webkit.WebView
import android.webkit.WebViewClient
import android.webkit.WebResourceRequest
import android.content.Context
 
class MainActivity : AppCompatActivity() {
.
.
   override fun onStart() {
        super.onStart()
        configureWebView()
    }
 
    private fun configureWebView() {
 
        binding.contentMain.myWebView.webViewClient = object : WebViewClient() {
            override fun shouldOverrideUrlLoading(
                    view: WebView, request: WebResourceRequest): Boolean {
                return super.shouldOverrideUrlLoading(
                        view, request)
            }
        }
        binding.contentMain.myWebView.loadUrl(
                "https://www.answertopia.com") 
    }
.
.
}Code language: Kotlin (kotlin)

Adding the Print Menu Option

The option to print the web page will now be added to the Overflow menu. The first requirement is a string resource to label the menu option. Within the Project tool window, locate the app -> res -> values -> strings.xml file, double-click on it to load it into the editor, and modify it to add a new string resource:

<resources>
    <string name="app_name">WebPrint</string>
    <string name="action_settings">Settings</string>
    <string name="print_string">Print</string>
.
.
</resources>Code language: HTML, XML (xml)

Next, load the app -> res -> menu -> menu_main.xml file into the menu editor, switch to Code mode, and replace the Settings menu option with the print option:

<menu xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    tools:context="com.ebookfrenzy.webprint.MainActivity" >
    <item
         android:id="@+id/action_settings"
        android:title="@string/action_settings"
        android:orderInCategory="100"
        app:showAsAction="never" />
 
    <item
        android:id="@+id/action_print"
        android:orderInCategory="100"
        app:showAsAction="never"         
        android:title="@string/print_string"/>
</menu>Code language: HTML, XML (xml)

All that remains in terms of configuring the menu option is to modify the onOptionsItemSelected() handler method within the MainActivity.kt file:

override fun onOptionsItemSelected(item: MenuItem): Boolean {
 
    if (item.itemId == R.id.action_print) {
        createWebPrintJob(binding.contentMain.myWebView)
    }
    return super.onOptionsItemSelected(item)
}Code language: Kotlin (kotlin)

With the onOptionsItemSelected() method implemented, the activity will call a method named createWebPrintJob() when the print menu option is selected from the overflow menu. The implementation of this method is identical to that used in the previous HTMLPrint project and may now be added to the MainActivity.kt file such that it reads as follows:

.
.
import android.print.PrintAttributes
import android.print.PrintManager
.
.
class MainActivity : AppCompatActivity() {
.
.
   private fun createWebPrintJob(webView: WebView?) {
 
        val printManager = this
                .getSystemService(Context.PRINT_SERVICE) as PrintManager
 
        val printAdapter = webView?.createPrintDocumentAdapter("MyDocument")
 
        val jobName = getString(R.string.app_name) + " Print Test"
 
        printAdapter?.let {
            printManager.print(
                jobName, it,
                PrintAttributes.Builder().build()
            )
        }
    }
.
.
}Code language: Kotlin (kotlin)

With the code changes complete, run the application on a physical Android device or emulator. Once successfully launched, the WebView should be visible with the designated web page loaded. Once the page has loaded, select the Print option from the Overflow menu and use the resulting print panel to print the web page to a suitable destination.

Summary

The Android Printing framework includes extensions to the WebView class that allow printing HTML-based content from within an Android application. This content can be HTML created dynamically within the application at runtime or a pre-existing web page loaded into a WebView instance. In the case of dynamically created HTML, it is important to use a WebViewClient instance to ensure that printing does not start until the HTML has been fully loaded into the WebView.

Android Printing Framework is used to print content from within Android applications. While subsequent chapters will explore in more detail the options for adding printing support to your applications, this chapter will focus on the various printing options now available in Android and the steps involved in enabling those options.

The chapter will then provide an overview of the various printing features available to Android developers to build printing support into applications.

The Android Printing Architecture

The Printing framework provides printing in Android. In basic terms, this framework consists of a Print Manager and a number of print service plugins.

It is the responsibility of the Print Manager to handle the print requests from applications on the device and to interact with the print service plugins installed on the device, thereby ensuring that print requests are fulfilled.

By default, many Android devices have print service plugins installed to enable printing using the Google Cloud Print and Google Drive services. Print Services Plugins for other printer types, if not already installed, may also be obtained from the Google Play store.

Print Service Plugins are currently available for HP, Epson, Samsung, and Canon printers, and plugins from other printer manufacturers will most likely be released in the future. However, the Google Cloud Print service plugin can print from Android to just about any printer type and model. This book will use the HP Print Services Plugin as a reference example.

The Print Service Plugins

The purpose of the Print Service plugins is to enable applications to print to compatible printers that are visible to the Android device via a local area wireless network or Bluetooth.

The presence of the Print Service Plugin on an Android device can be verified by loading the Google Play app and performing a search for “Print Service Plugin”.

Once the plugin is listed in the Play Store, and if it is not already installed, it can be installed by selecting the Install button. Figure 80-1, for example, shows the HP Print Service plugin within Google Play.

The Print Services plugins will automatically detect compatible printers on the network to which the Android device is currently connected and list them as options when printing from an application.

Google Cloud Print

Google Cloud Print is a service provided by Google that enables you to print content onto your printer over the web from anywhere with internet connectivity. Google Cloud Print supports many devices and printer models in both Cloud Ready and Classic printers. A Cloud Ready printer has technology built-in that enables printing via the web. Manufacturers that provide cloud-ready printers include Brother, Canon, Dell, Epson, HP, Kodak, and Samsung. To identify if your printer is both cloud-ready and supported by Google Cloud Print, review the list of printers at the following URL:

https://www.google.com/cloudprint/learn/printers.html

In the case of classic, non-Cloud Ready printers, Google Cloud Print provides support for cloud printing by installing software on the computer system to which the classic printer is connected (either directly or over a home or office network).

To set up Google Cloud Print, visit the following web page and log in using the same Google account ID that you use when logging in to your Android devices:

https://www.google.com/cloudprint/learn/index.html

Once printers have been added to your Google Cloud Print account, they will be listed as printer destination options when you print from within Android applications.

Printing to Google Drive

In addition to supporting physical printers, it is also possible to save printed output to your Google Drive account. When printing from a device, select the Save to Google Drive option in the printing panel. The content to be printed will then be converted to a PDF file and saved to the Google Drive cloud-based storage associated with the currently active Google Account ID on the device.

Save as PDF

The final printing option provided by Android allows the printed content to be saved locally as a PDF file on the Android device. Once selected, this option will request a name for the PDF file and a location on the device to which the document will be saved.

Both the Save as PDF and Google Drive options can be invaluable in terms of saving paper when testing the printing functionality of your own Android applications.

Printing from Android Devices

Google recommends that applications that can print content do so by placing the print option in the Overflow menu. Many applications bundled with Android now include “Print…” menu options. Figure 80-2, for example, shows the Print option accessed by selecting the “Share…” option in the Overflow menu of the Chrome browser application:

Once the print option has been selected from within an application, the standard Android print screen will appear, showing a preview of the content to be printed, as illustrated in Figure 80-3:

Tapping the panel along the top of the screen will display the full range of printing options:

The Android print panel provides standard printing options, such as paper size, color, orientation, and number of copies. Other print destination options may be accessed by tapping on the current printer or PDF output selection.

Options for Building Print Support into Android Apps

The Printing framework provides several options for incorporating print support into Android applications. These options can be categorized as follows:

Image Printing

As the name suggests, this option allows image printing to be incorporated into Android applications. When adding this feature to an application, the first step is to create a new instance of the PrintHelper class:

val imagePrinter = PrintHelper(context)Code language: Kotlin (kotlin)

Next, the scale mode for the printed image may be specified via a call to the setScaleMode() method of the PrintHelper instance. Options are as follows:

• SCALE_MODE_FIT – The image will be scaled to fit within the paper size without cropping or changes to the aspect ratio. This will typically result in white space appearing in one dimension.
• SCALE_MODE_FILL – The image will be scaled to fill the paper size with cropping performed where necessary to avoid the appearance of white space in the printed output.

Without a scale mode setting, the system will default to SCALE_MODE_FILL. The following code, for example, sets scale to fit mode on the previously declared PrintHelper instance:

imagePrinter.setScaleMode(PrintHelper.SCALE_MODE_FIT)Code language: Kotlin (kotlin)

Similarly, the color mode may also be configured to indicate whether the print output is to be in color or black and white. This is achieved by passing one of the following options through to the setColorMode() method of the PrintHelper instance:

• COLOR_MODE_COLOR – Indicates that the image is to be printed in color.
• COLOR_MODE_MONOCHROME – Indicates that the image will be printed in black and white.

The printing framework will default to color printing unless the monochrome option is specified as follows:

imagePrinter.colorMode = PrintHelper.COLOR_MODE_MONOCHROMECode language: Kotlin (kotlin)

All that is required to complete the printing operation is an image to be printed and a call to the printBitmap() method of the PrintHelper instance, passing through a string representing the name to be assigned to the print job and a reference to the image (in the form of either a Bitmap object or a Uri reference to the image):

val bitmap = BitmapFactory.decodeResource(resources,
                R.drawable.oceanscene)
imagePrinter.printBitmap("My Test Print Job", bitmap)Code language: Kotlin (kotlin)

Once the print job has been started, the Printing framework will display the print dialog and handle both the subsequent interaction with the user and the printing of the image on the user-selected print destination.

Creating and Printing HTML Content

The Android Printing framework also provides an easy way to print HTML-based content within an application. This content can either be HTML content referenced by the URL of a page hosted on a website or HTML content dynamically created within the application.

To enable HTML printing, the WebView class has been extended to include support for printing with minimal coding requirements.

When dynamically creating HTML content (as opposed to loading and printing an existing web page), the process involves the creation of a WebView object and associating with it a WebViewClient instance. The web view client is then configured to start a print job when the HTML has finished being loaded into the WebView.

With the web view client configured, the HTML is loaded into the WebView, and the print process is triggered. Consider, for example, the following code:

private fun printWebView() {
 
    val webView = WebView(this)
    webView.webViewClient = object : WebViewClient() {
 
        override fun shouldOverrideUrlLoading(view: WebView,
                             request: WebResourceRequest): Boolean {
            return false
        }
 
        override fun onPageFinished(view: WebView, url: String) {
            createWebPrintJob(view)
            myWebView = null
        }
    }
 
    val htmlDocument = "<html><body><h1>Android Print Test</h1><p>" +
            "This is some sample content.</p></body></html>"
 
    webView.loadDataWithBaseURL(null, htmlDocument,
            "text/HTML", "UTF-8", null)
 
    myWebView = webView
}Code language: Kotlin (kotlin)

The code in this method begins by declaring a variable named myWebView in which will be stored a reference to the WebView instance created in the method. Within the printContent() method, an instance of the WebView class is created to which a WebViewClient instance is assigned.

The WebViewClient assigned to the web view object is configured to indicate that the loading of the HTML content is to be handled by the WebView instance (by returning false from the shouldOverrideUrlLoading()) method. More importantly, an onPageFinished() handler method is declared and implemented to call the createWebPrintJob() method. The onPageFinished() callback method will be called automatically when all HTML content is loaded into the web view. This ensures that the print job is not started until the content is ready, ensuring that all content is printed.

Next, a string is created containing some HTML to serve as the content. This is then loaded into the web view. Once the HTML is loaded, the onPageFinished() method will trigger. Finally, the method stores a reference to the web view object. Without this vital step, there is a significant risk that the Java runtime system will assume that the application no longer needs the web view object and will discard it to free up memory (a concept referred to in Java terminology as garbage collection), resulting in the print job terminating before completion. All that remains in this example is to implement the createWebPrintJob() method as follows:

private fun createWebPrintJob(webView: WebView) {
 
    val printManager = this
            .getSystemService(Context.PRINT_SERVICE) as PrintManager
 
    val printAdapter = webView.createPrintDocumentAdapter("MyDocument")
 
    val jobName = getString(R.string.app_name) + " Document"
 
    printManager.print(jobName, printAdapter,
            PrintAttributes.Builder().build())
}Code language: Kotlin (kotlin)

This method obtains a reference to the PrintManager service and instructs the web view instance to create a print adapter. A new string is created to store the name of the print job (which, in this case, is based on the name of the application and the word “Document”).

Finally, the print job is started by calling the print() method of the print manager, passing through the job name, print adapter, and a set of default print attributes. If required, the print attributes could be customized to specify resolution (dots per inch), margin, and color options.

Printing a Web Page

The steps involved in printing a web page are similar to those outlined above, with the exception that the web view is passed the URL of the web page to be printed in place of the dynamically created HTML, for example:

myWebView?.loadUrl("https://developer.android.com/google/index.html")Code language: Kotlin (kotlin)

It is also important to note that the WebViewClient configuration is only necessary if a web page is to automatically print as soon as it has loaded. If the printing is to be initiated by the user selecting a menu option after the page has loaded, only the code in the createWebPrintJob() method outlined above needs to be included in the application code. The next chapter, An Android Studio HTML and Web Printing Example, will demonstrate such a scenario.

Printing a Custom Document

While the HTML and web printing features introduced by the Printing framework provide an easy path to printing content from within an Android application, it is clear that these options will be overly simplistic for more advanced printing requirements. The Printing framework also provides custom document printing support for more complex printing tasks. This allows content in the form of text and graphics to be drawn onto a canvas and then printed.

Unlike HTML and image printing, which can be implemented with relative ease, custom document printing is a more complex, multi-stage process which will be outlined in the An Android Studio Custom Printing Tutorial chapter of this book. These steps can be summarized as follows:

• Connect to the Android Print Manager
• Create a Custom Print Adapter sub-classed from the PrintDocumentAdapter class
• Create a PdfDocument instance to represent the document pages
• Obtain a reference to the pages of the PdfDocument instance, each of which has associated with it a Canvas instance
• Draw the content on the page canvases
• Notify the print framework that the document is ready to print

The custom print adapter outlined in the above steps must implement several methods that the Android system will call upon to perform specific tasks during printing. The most important of these are the onLayout() method, responsible for re-arranging the document layout in response to the user changing settings such as paper size or page orientation, and the onWrite() method which is responsible for rendering the pages to be printed. The chapter entitled An Android Studio Custom Printing Tutorial will cover this topic in detail.

Summary

The Android SDK can print content from within a running app. Print output can be directed to suitably configured printers, a local PDF file, or to the cloud via Google Drive. From the perspective of the Android application developer, these capabilities are available for use in applications by making use of the Printing framework. By far, the easiest printing options to implement are those involving content in the form of images and HTML. More advanced printing may, however, be implemented using the custom document printing features of the framework.