The Not-So-Distant Past

In the early days of native phone application development, developers, generally coding in low-level C or C++, needed to understand the specific hardware they were coding for, typically a single device or possibly a range of devices from a single manufacturer. The complexity inherent in this approach meant the applications written for these devices often lagged behind their hardware counterparts. As hardware technology and mobile Internet access have advanced, this closed approach has become outmoded.

The next significant advancement in mobile phone application development was the introduction of Java-hosted MIDlets. MIDlets were executed on a Java virtual machine (JVM), a process that abstracted the underlying hardware and let developers create applications that ran on many devices that supported the Java run time.

Unfortunately, this convenience came at the price of more heavily restricted access to the device hardware. Similarly, it was considered normal for third-party applications to receive different hardware access and execution rights from those given to native applications written by the phone manufacturers, with MIDlets often receiving few of either.

The introduction of Java MIDlets expanded developers’ audiences, but the lack of low-level hardware access and sandboxed execution meant that most mobile applications were regular desktop programs or websites designed to render on a smaller screen, and didn’t take advantage of the inherent mobility of the handheld platform.

Living in the Future

At its introduction, Android was part of a new wave of modern mobile operating systems designed specifically to support application development on increasingly powerful mobile hardware.

Android offers an open development platform built on an open source Linux kernel. Hardware access is available to all applications through a series of API libraries, and application interaction, while carefully controlled, is fully supported.

In Android, all applications have equal standing. Third-party and native Android applications are written with the same APIs and are executed on the same run time. Users can replace most system application with a third-party developer’s alternative; indeed, even the dialer and home screens can be replaced.

What Comes in the Box

The Android SDK includes everything you need to start developing, testing, and debugging Android applications:

• The Android API Libraries —The core of the SDK is the Android API libraries that provide developer access to the Android stack. These are the same libraries that Google uses to create native Android applications.
• Development tools —The SDK includes the Android Studio IDE and several other development tools that let you compile and debug your applications to turn Android source code into executable applications. You learn more about the developer tools in Chapter 2 , “Getting Started.”
• The Android Virtual Device Manager and Emulator —The Android Emulator is a fully interactive mobile device emulator featuring several alternative skins. The Emulator runs within an Android Virtual Device (AVD) that simulates a device hardware configuration. Using the Emulator you can see how your applications will look and behave on a real Android device. All Android applications run within ART, so the software emulator is an excellent development environment—in fact, because it’s hardware-neutral, it provides a better independent test environment than any single hardware implementation.
• Full documentation —The SDK includes extensive code-level reference information detailing exactly what’s included in each package and class and how to use them. In addition to the code documentation, Android’s reference documentation and developer guides explain how to get started, give detailed explanations of the fundamentals behind Android development, highlight best practices, and provide deep-dives into framework topics.
• Sample code —The Android SDK includes a selection of sample applications that demonstrate some of the possibilities available with Android, as well as simple programs that highlight how to use individual API features.
• Online support —Android has vibrant developer communities on most online social networks, Slack, and many developer forums. Stack Overflow ( www.stackoverflow.com/questions/tagged/android ) is a hugely popular destination for Android questions and a great place to find answers to beginner questions. Many Android engineers from Google are active on Stack Overflow and Twitter.

Understanding the Android Software Stack

The Android software stack is a Linux kernel and a collection of C/C++ libraries exposed through an application framework that provides services for, and management of, the run time and applications, as shown in Figure 1-1 .

• Linux kernel —Core services (including hardware drivers, process and memory management, security, network, and power management) are handled by a Linux kernel (the specific kernel version depends on the Android platform version and hardware platform).
• Hardware Application Layer (HAL) —The HAL provides an abstraction layer between the underlying physical device hardware and the remainder of the stack.
• Libraries —Running on top of the kernel and HAL, Android includes various C/C++ core libraries such as libc and SSL, as well as the following:
  • A media library for playback of audio and video media
  • A surface manager to provide display management
  • Graphics libraries that include SGL and OpenGL for 2D and 3D graphics
  • SQLite for native database support
  • SSL and WebKit for integrated web browser and Internet security
• Android Run Time —The run time is what makes an Android phone an Android phone rather than a mobile Linux implementation. Including the core libraries, the Android Run Time is the engine that powers your applications and forms the basis for the application framework.
• Core libraries —Although most Android application development is written using the Java or Kotlin JVM languages, ART is not a Java VM. The core Android libraries provide most of the functionality available in the core Java libraries, as well as the Android-specific libraries.
• Application framework —The application framework provides the classes used to create Android applications. It also provides a generic abstraction for hardware access and manages the user interface and application resources.
• Application layer —All applications, both native and third-party, are built on the application layer by means of the same API libraries. The application layer runs within the Android Run Time, using the classes and services made available from the application framework.

The Android Run Time

One of the key elements of Android is the Android Run Time (ART). Rather than using a traditional Java VM such as Java ME, Android uses its own custom run time designed to ensure that multiple instances run efficiently on a single device.

ART uses the device’s underlying Linux kernel to handle low-level functionality, including security, threading, and process and memory management. It’s also possible to write C/C++ applications that run closer to the underlying Linux OS. Although you can do this, in most cases there’s no reason you should need to.

If the speed and efficiency of C/C++ is required for your application, Android provides a native development kit (NDK). The NDK is designed to enable you to create C++ libraries using the libc and libm libraries, along with native access to OpenGL.

All Android hardware and system service access is managed using ART as a middle tier. By using this run time to host application execution, developers have an abstraction layer that ensures they should never have to worry about a particular hardware implementation.

ART executes Dalvik executable files ( .dex )—named after an earlier virtual machine implementation named “Dalvik”—a format optimized to ensure minimal memory footprint. You create .dex executables by transforming Java or Kotlin language compiled classes using the tools supplied within the SDK.

Android Application Architecture

Android’s architecture encourages component reuse, enabling you to publish and share Activities, Services, and data with other applications, with access managed by the security restrictions you define.

The same mechanism that enables you to produce a replacement contact manager or phone dialer can let you expose your application’s components in order to let other developers build on them by creating new UI front ends or functionality extensions.

The following application services are the architectural cornerstones of all Android applications, providing the framework you’ll be using for your own software:

• Activity Manager and Fragment Manager —Activities and Fragments are used to define the user interface of your apps. The Activity and Fragment Managers control the life cycle of your Activities and Fragments, respectively, including management of the Activity stack (described in Chapters 3 and 5 ).
• Views —Used to construct the user interfaces controls within your Activities and Fragments, as described in Chapter 5 .
• Notification Manager —Provides a consistent and nonintrusive mechanism for signaling your users, as described in Chapter 11 .
• Content Providers —Lets your applications share data, as described in Chapter 10 .
• Resource Manager —Enables non-code resources, such as strings and graphics, to be externalized, as shown in Chapter 4 .
• Intents —Provides a mechanism for transferring data between applications and their components, as described in Chapter 6 .

Android Libraries

Android offers a number of APIs for developing your applications. Rather than list them all here, check out the documentation at developer.android.com/reference/packages.html , which gives a complete list of packages included in the Android SDK.

Android is intended to target a wide range of mobile hardware, so be aware that the suitability and implementation of some of the advanced or optional APIs may vary depending on the host device.

What You Need to Begin

Because Android applications run within the Android Run Time, you can write them on any platform that supports the developer tools. Throughout this book we’ll be using Android Studio, which currently supports:

• Microsoft Windows 7/8/10 (32- or 64-bit)
• Mac OS X 10.8.5 or later
• GNOME or KDE Linux desktop (including GNU C Library 2.11 or later)

On all platforms, Android Studio requires at least 2 GB of RAM (with 8 GB strongly recommended), and 1280 x 800 minimum screen resolution.

Installing Additional Android SDK Components Using the SDK Manager

The SDK Manager ( Figure 2-1 ) is available through a shortcut on the toolbar, the Android SDK settings option, or from within the Tools Android SDK Manager menu item. It offers tabs for SDK Platforms, SDK Tools, and SDK Update Sites.

The SDK Platforms tab shows which platform SDKs you have downloaded. By default, this will include the newest Android platform SDK—in this case, Android 8.1 Oreo (API Level 27).

The SDK Tools tab shows which tools and support libraries you have installed, including the SDK, platform, and build tools—as well as the support repository, which is required to use the Android Support Library (described later in this chapter.)

By selecting the Show Package Contents Details checkbox, you can find additional details on which versions each tool have been installed.

Downloading and Installing Updates to Android Studio, the Android SDK, and Tools

Android Studio receives frequent updates that improve stability and add new features. You will be prompted with an alert tip when a new version of Android Studio is available for download, as shown in Figure 2-2 .

You will similarly be prompted when new revisions of the Android SDK, developer tools, support library, Kotlin, and other SDK packages become available.

You can force a check for a new version of Android Studio by opening the Settings dialog box and navigating to Settings Updates and clicking the “Check Now” button, as shown in Figure 2-3 , or by selecting the Help Check For Updates menu item.

Creating Your First Android Application

With Android Studio installed and the SDK downloaded you’re ready to start developing apps for Android. You’ll begin by creating a new Android project, configuring the Android Emulator, and setting up your Android Studio run and debug configurations, as described in the following sections.

Running and Debugging Your Android Application

You’ve created your first project and created an Android Virtual Device (or connected a physical device) on which to run it. Before making any changes, let’s try running and debugging the Hello World project.

From the Run menu, select “Run app” (or “Debug app”). If you haven’t already selected a default, you’ll be presented with the dialog box shown in Figure 2-15 , asking you to select your deployment target—a connected device, a running AVD, or a defined (but not yet running) AVD.

Running or debugging your application does the following behind the scenes:

• Compiles the current project source to bytecode, and converts that to an Android executable ( .dex )
• Packages the executable and your project’s resources and manifest into an Android package ( .apk )
• Starts the virtual device (if you’ve targeted one and it’s not already running)
• Deploys your APK to the target device and installs it
• Starts your application

If you’re debugging, the Android Studio debugger will then be attached, allowing you to set breakpoints and debug your code.

If everything is working correctly, you’ll see a new Activity running on the device or in the Emulator, as shown in Figure 2-16 .

@Override
protected void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);
  setContentView(R.layout.activity_main);
} 

<TextView
  android:id="@+id/myTextView"
  android:layout_width="wrap_content"
  android:layout_height="wrap_content"
  android:text="Hello World!"
  app:layout_constraintBottom_toBottomOf="parent"
  app:layout_constraintLeft_toLeftOf="parent"
  app:layout_constraintRight_toRightOf="parent"
  app:layout_constraintTop_toTopOf="parent"/> 

TextView myTextView = findViewById(R.id.myTextView); 

Getting Started Writing Android Apps Using Kotlin

Until 2017, Android app development required the use of the Java language syntax. Android Studio 3.0 added Kotlin as a fully supported language alternative.

Kotlin is a statically typed language that is fully interoperable with the existing Java language syntax and runtime used with Android. It’s considered expressive and concise, and introduces improvements including reduced language verbosity, null-pointer safety, extension functions, and infix notation.

Since Android Studio 3.0, Kotlin is an officially supported Android development language; however, at the time of this book’s writing, Java was still the default for new projects—and most existing Android projects were still written predominantly using Java syntax. It’s also very easy to convert Java syntax into Kotlin, simply by pasting Java syntax into a Kotlin source file. As a result, we have used Java syntax within the code snippets and sample projects featured within this book.

Given the advantages of Kotlin in terms of improved development time and code readability, we expect the proportion of apps written primarily in Kotlin to increase quickly, and we highly recommend that you familiarize yourself with the Kotlin language for writing Android apps. To assist, each of the code snippets and sample projects are also available in Kotlin, downloadable from the Wrox site alongside the Java syntax versions.

Your Android projects can be written from scratch in Kotlin, can include interoperable Kotlin and Java source files, or can be converted from Java source files to Kotlin during development.

To begin a new project in Kotlin, select the File New New Project… menu item, as previously described, but on the first page of the wizard, select the “Include Kotlin support” checkbox, as shown in Figure 2-18 .

Proceed through the wizard as described in the earlier section. When complete, take a look at the Kotlin source code for your Activity in the MainActivity.kt file. Kotlin files are stored alongside Java source files and can be found in the Java folder when using the Android project view:

package com.professionalandroid.apps.myapplication

import android.support.v7.app.AppCompatActivity
import android.os.Bundle

class MainActivity : AppCompatActivity() { 

  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_main)
  }
} 

Note that while the code is somewhat more concise, the syntactic changes at this point are minimal. The package and import statements are the same, the MainActivity class still extends AppCompatActivity , and the override of the onCreate method remains the same.

To add a new Kotlin file to your project, select Kotlin from the Source Language dropdown list when adding a new application component from the File New menu. Alternatively, you can select the File New Kotlin File/Class menu item to create a basic file.

Because Kotlin and Java files can coexist in the same project, it’s possible to add Kotlin source files to a project you started without ticking the Kotlin support checkbox or to add Java source files to a project started with Kotlin support.

It’s also possible to convert existing Java syntax source files into Kotlin. You can do this by opening an existing Java source file and selecting the Code Convert Java File to Kotlin File menu item. Alternatively, you can create a new Kotlin file and paste Java syntax source code into it. You will be prompted to convert the pasted code into Kotlin, as shown in Figure 2-19 .

Note that these automatic conversions may not always use idiomatic Kotlin, so the resulting code might not use Kotlin’s best language features.

Using the Android Support Library Package

The Android Support Library package (also referred to as the compatibility library or AppCompat) is a set of libraries you can include as part of your projects, to gain either convenience APIs that aren’t packaged as part of the framework (such as the View Pager), or useful APIs that are not available on all platform releases (such as Fragments).

The Support Library enables you to use framework API features that were introduced in newer Android platform releases on devices running earlier platform versions. This helps you provide a consistent user experience and greatly simplifies your development process by reducing the burden of supporting older platform versions, while taking advantage of newer features.

The Android Support Library package contains several individual libraries, each of which offers support for a specific range of Android platform versions and features.

We will introduce new libraries as required in the following chapters. To begin with, it’s good practice to include the v7 appcompat library in all new projects because it supports a wide range of Android versions—back to Android 2.3 Gingerbread (API Level 9)—and provides APIs for many recommended user interface patterns.

The application templates provided by Android Studio—including the Hello World example we created earlier—include a dependency on the v7 appcompat library by default.

To incorporate an Android Support Library package into your project, perform the following steps:

1. Use the SDK Manager to ensure you have downloaded the Android Support Repository.
2. Add a dependency to your Gradle build for the desired library, either by:
   1. 2.1 Opening your module:app build.gradle file and adding a reference to the library name and version you wish to include, within the dependency node:

      dependencies {
        [… Existing dependencies …]
        implementation 'com.android.support:appcompat-v7:27.1.1'
      } 

   2. 2.2 Or using Android Studio’s Project Structure UI, as shown in Figure 2-20 . Select the File Project Structure…, menu item and then select your app module from the list on the left before choosing the Dependencies tab. Add a new library by selecting the green “plus” symbol on the right-side toolbar and selecting the desired library.

      

Notice that we’re adding a dependency to a specific version of the support library. By design, the Android Support Library package will be updated more regularly than the Android framework SDK. By downloading new versions of the Support Libraries, and updating your dependencies to reference the newest releases, you can continue to incorporate bug fixes and improvements to your app as the Support Libraries are updated.

Hardware-Imposed Design Considerations

Small and portable, mobile devices offer exciting opportunities for software development. Their limited screen size and reduced memory, storage, and processor power are far less exciting, and instead present some unique challenges.

Compared to desktop or notebook computers, mobile devices have relatively:

• Low processing power
• Limited RAM
• Limited storage capacity
• Small screens
• High costs associated with data transfers
• Intermittent connectivity, slow data transfer rates, and high latency
• Limited battery life

Each new generation of devices improves on many of these restrictions, but the device ecosystem also caters for a wide variety of prices—which results in significant variety in hardware capabilities. This is amplified by the huge growth in smart phone adoption in emerging markets, which are significantly more price sensitive, and that in turn results in large numbers of new devices with lower specification hardware.

The expansion of Android into an increasingly diverse variety of form factors—including tablets, TVs, automotive head-units, and wearable devices further expands the range of devices on which your application may be running.

In some cases you may find your app running on hardware significantly more powerful than you expected; however it’s always good practice to design to accommodate the worst-case scenario to ensure you’re providing a great user experience to all users, no matter what their hardware platform.

Expect Low Speeds, High Latency

The ability to connect to the Internet is a big part of what has made smart phones smart, and ubiquitous. Unfortunately, mobile Internet connectivity isn’t as fast, reliable, cheap, or readily available as we would like; when you’re developing your Internet-based applications, it’s best to assume that the network connection will be slow, intermittent, expensive, and unreliable.

This is especially true in emerging markets where relative data prices are significantly higher. By designing for the worst case you can ensure that you always deliver a high-standard user experience. This also means making sure that your applications can handle losing (or not finding) a data connection.

The Android Emulator enables you to control the speed and latency of your network connection. Figure 2-21 shows the Emulator’s network connection speed and signal strength, simulating a distinctly suboptimal EDGE connection.

Experiment to ensure seamlessness and responsiveness no matter what the speed, latency, and availability of network access. Some techniques include limiting the functionality of your application, or reducing network lookups to cached bursts, when the available network connection supports only limited data transfer capabilities.

In Chapter 7 , “Using Internet Resources,” you learn how to use Internet resources in your applications.

Considering the User’s Environment

Sadly, you can’t assume that your users will consider your application the most important feature of their device.

In the case of smart phones, they are typically first and foremost a communications device, secondly a camera, thirdly a music and video player, and fourthly a games platform. The applications you write will most likely be in the fifth category of “useful stuff.”

That’s not a bad thing—they’ll be in good company with others, including Google Maps and the web browser. That said, each user’s usage model will be different; some people will never use their device to listen to music, some devices don’t support telephony, and some don’t include cameras—but the multitasking principle inherent in a device as ubiquitous as it is indispensable is an important consideration for usability design.

It’s also important to consider when and how your users will use your application. People use their mobiles all the time—on the train, walking down the street, or even while driving. You can’t make people use their phones appropriately, but you can make sure that your applications don’t distract them any more than necessary.

What does this mean in terms of software design? Make sure that your application:

• Is predictable and well behaved —There’s a fine line between a delightful moment and an unpleasant surprise. The outcome of any user interaction should be predictable and reversible, making it easy for new users to understand how to perform tasks, and minimizing any risk from experimenting.
• Switches seamlessly from the background to the foreground —With the multitasking nature of mobile devices, it’s likely that your applications will regularly move into and out of the background. It’s important that they “come to life” quickly and seamlessly. Unless users have explicitly closed your app, they shouldn’t notice a difference between restarting and resuming it; switching should be seamless, with users being shown the UI and application state they last saw.
• Is polite —Never steal focus or interrupt a user’s current Activity. Use Notifications (detailed in Chapter 11 ) to request user attention, when and as appropriate, when your application isn’t in the foreground.
• Presents an attractive and intuitive UI —Spend the time and resources necessary to produce a UI that is as attractive as it is functional, and don’t force users to interpret and relearn your application every time they open it. Using your app should be simple, easy, obvious, and delightful.
• Is responsive —Responsiveness is one of the most critical design considerations on a mobile device. You’ve no doubt experienced the frustration of a “frozen” piece of software; the multifunctional nature of mobile devices makes this even more annoying. With the possibility of delays caused by slow and unreliable data connections, it’s important that your application always remains responsive.

Developing for Android

In addition to the preceding general guidelines, the Android design philosophy demands that high-quality applications be designed for:

• Performance
• Responsiveness
• Freshness
• Security
• Seamlessness
• Accessibility

Being Responsive

Generally, 100 to 200ms is the threshold at which users perceive a delay or “jank” in an application, so you should always endeavor to respond to user input within that timeframe.

The Android Activity Manager and Window Manager also enforce a time limit beyond which the application is considered unresponsive, and the user will be given the opportunity to force-close the app. If either service detects an unresponsive application, it will display an “[Application] isn’t responding” (ANR) dialog box, as shown in Figure 2-22 .

Android monitors two conditions to determine responsiveness:

• An application must respond to any user action, such as a key press or screen touch, within 5 seconds.
• A Broadcast Receiver must return from its onReceive handler within 10 seconds.

The ANR dialog box is a last resort of usability; the generous five-second limit is a worst-case scenario, not a target. You can ensure that your application doesn’t trigger an ANR, and is as responsive as possible, in a number of ways:

• Lengthy tasks such as network or database lookups, complex processing (such as calculating game moves), and file I/O should all be moved off the main UI thread and run asynchronously.
• Show progress within your UI if there are long-running tasks happening in the background.
• If your application has a time-consuming initial setup phase, render the main view as quickly as possible, indicate that loading is in progress, and fill the information asynchronously. You could also consider showing a splash screen—but in either case, indicate that progress is being made, to avoid the user perception that the application has frozen.

Android Studio

As a developer, the Android Studio IDE is where you’ll be spending the majority of your time, so it pays to understand some of its nuances. The following sections introduce some tips for reducing build times—specifically through the use of Instant Run—as well as some shortcuts and advanced features you can use while writing and debugging your code.

  org.gradle.jvmargs=-Xmx2048m 

The Android Virtual Device Manager

The Android Virtual Device Manager is used to create and manage the virtual hardware devices that will host instances of the Emulator.

AVDs are used to simulate the hardware configurations of different physical devices. This lets you test your application on a variety of hardware platforms without needing to buy a variety of phones.

Each virtual device is configured with a name, physical device type, Android system image, screen size and resolution, ABI/CPU, memory and storage capacities, and hardware capabilities including camera and network speeds.

Different hardware settings and screen resolutions will present alternative UI skins to represent the different hardware configurations. This simulates a variety of device types including different phones and tablets, as well as TVs and Android Wear devices.

The Android Emulator

The Emulator runs within an AVD, and is available for testing and debugging your applications as an alternative to using a physical device.

The Emulator is an implementation of the Android Run Time, making it as valid a platform for running Android applications as any Android phone. Because it’s decoupled from any particular hardware, it’s an excellent baseline to use for testing your applications.

Full network connectivity is provided along with the ability to tweak the Internet connection speed and latency while debugging your applications. You can also simulate placing and receiving voice calls and SMS messages.

Android Studio integrates the Emulator so that it’s launched automatically within the selected AVD when you run or debug your projects.

Once running, you can use the toolbar shown in Figure 2-23 to emulate pressing the hardware power and volume buttons, software home, back, and recents buttons, rotate the display, or take screen shots. Pressing the “…” button opens the extended controls, which are also shown in Figure 2-23 , and that allow you to:

• Set the current GPS location, and simulate GPS track playback.
• Modify the simulated cellular network connectivity, including signal strength, speed, and data connection type.
• Set battery health, level, and charging status.
• Simulate incoming phone calls and SMS messages.
• Simulate the fingerprint sensor.
• Provide mock sensor data including results for accelerometer, ambient temperature, and magnetic field sensor.

Android Profiler

The Emulator enables you to see how your application will look, behave, and interact, but to actually see what’s happening under the surface, you need the Android Profiler.

The Android Profiler displays real-time profiling data for the CPU, memory, and network activity related to your app. You can perform sample-based method tracing to time your code execution, capture heap dumps, view memory allocations, and inspect the details of network-transmitted files.

To open the Android Profiler, click the Android Profiler icon in the toolbar, or navigate to the View Tool Windows Android Profiler menu item. The shared timeline window will be displayed, as shown in Figure 2-24 .

The Profiler window displays real-time graphs for CPU, memory, and network usage, as well as an event timeline that indicates changes in Activity state, user inputs, and screen rotations.

To access the detailed profiling tools for CPU, memory, or network use, click the associated graph. Depending on the resource being profiled, each detail view will allow you to do one of the following:

• Inspect CPU activity and method traces.
• Inspect the Java heap and memory allocations.
• Inspect incoming and outgoing network traffic.

The Android Debug Bridge

The Android Debug Bridge (ADB) is a client-service application that lets you connect with an Android device (virtual or actual). It’s made up of three components:

• A daemon running on the device or Emulator
• A service that runs on your development computer
• Client applications that communicate with the daemon through the service

As a communications conduit between your development hardware and the Android device/Emulator, the ADB lets you install applications, push and pull files, and run shell commands on the target device. Using the device shell, you can change logging settings and query or modify SQLite databases available on the device.

Android Studio automates and simplifies a lot of your usual interaction with the ADB, including application installation and updating, file logging, and debugging.

APK Analyzer

The APK Analyzer enables you to better understand the composition of your APK files by providing an interface to:

• View the absolute and relative size of files stored within the APK, including .DEX and resource files.
• View the final versions of .DEX files stored within the APK.
• View the final version of the AndroidManifest.xml file.
• Perform a side-by-side comparison of two APKs.

To analyze your APK, you can drag and drop an APK file directly into the editor window of Android Studio, navigate to an APK in the build output apks directory using the Project perspective and double-click the desired APK, or click the Build Analyze APK menu item and select an APK.

The APK Analyzer window, shown in Figure 2-25 , displays each file and folder stored within the APK, and allows you to navigate within each folder or to display additional details on each file.

The Raw File Size column represents the uncompressed size of each entity, while the Download Size indicates the estimated compressed size of the entity when delivered by Google Play.

By selecting the application manifest, you can view the XML form of the final manifest file packaged within your APK.

For more details on how to use the APK Analyzer, refer to developer.android.com/studio/build/apk-analyzer.html .

The Lint Tool

Android Studio provides a static code analysis tool called Lint, which helps identify and correct structural quality issues within your code, without having to run the app or write those specific tests.

The configured Lint and IDE inspections run automatically whenever you build your app, checking your source code and resource files for potential bugs and optimization improvements, including correctness, security, performance, usability, accessibility, and internationalization.

Potential problems are highlighted within the IDE with a description, severity level, and where possible a suggested remedy.

Using Lint to identify and rectify potential structural issues within your code can dramatically improve the readability, reliability, and efficiency of your code. It’s best practice to ensure all Lint warnings are dealt with as part of your development process.

Monkey, Monkey Runner, and Espresso UI Testing

UI testing helps to ensure that users don’t encounter unexpected results when interacting with your app. Android Studio includes a number of tools to assist you in creating user interface/user interaction tests.

Monkey works from within the ADB shell, sending a stream of pseudorandom, but repeatable, system and UI events to your application. It’s particularly useful to stress-test your applications to investigate edge cases you might not have anticipated through unconventional use of the UI.

Alternatively, Monkey Runner is a Python scripting API that lets you send specific UI commands to control an Emulator or device from outside the application. It’s extremely useful for performing UI, functional, and unit tests in a predictable, repeatable fashion.

The Espresso testing framework, provided through the Android Testing Support Library, provides APIs for writing UI tests to simulate specific user interactions for a specific app. Espresso detects when the main thread is idle, and runs your test commands at the appropriate time to improve test reliability. This capability also relieves you from needing to add timing workarounds, such as a sleep period, into your test code.

You can learn more about Espresso testing at developer.android.com/training/testing/espresso .

Gradle

Gradle is an advanced build system and toolkit, integrated into Android Studio, which makes it possible for you to perform custom build configurations without needing to modify your app’s source files.

The use of Gradle as Android’s build system is intended to make it easier to configure, extend and customize the build process, simplify code and resource reuse, and to more easily create multiple build variants of an application.

Gradle is plug-in–based, so integration with Android Studio is managed through the Android Plugin for Gradle, which works with the build toolkit to provide a UI within Android Studio for processes and configurable settings that are specific to building and testing Android applications.

Gradle itself, and the Android Plugin, are integrated with—but ultimately independent of—Android Studio. As a result, you can build your Android apps from within Android Studio, the command line on your machine, or on machines where Android Studio is not installed (such as continuous integration servers). The output of the build is the same whether you are building a project from the command line, on a remote machine, or using Android Studio.

Within this book, we will be building our applications within Android Studio using the Android Plugin for Gradle to manage our interactions with the build system. Full coverage of Gradle, custom builds, and Gradle build scripts is beyond the scope of this book, but you can learn more details at developer.android.com/studio/build/ .

Creating Activities

To create a new Activity, extend the Activity class—or one of its subclasses (most commonly the AppCompatActivity , as described in the next section). Within your new class you must assign a UI and implement your functionality. Listing 3-1 shows the basic skeleton code for a new Activity .

The base Activity class presents an empty screen that encapsulates the window display handling. An empty Activity isn’t particularly useful, so the first thing you’ll want to do is create the UI using Fragments, layouts, and Views.

Views are the UI widgets/controls that display data and provide user interaction. Android provides several layout classes, called View Groups , which can contain multiple Views to help you lay out your UI. Fragments—discussed later in this chapter—are also available to encapsulate segments of your UI, making it simple to create dynamic interfaces that can be rearranged to optimize your layouts for different screen sizes and orientations.

To assign a UI to an Activity, call setContentView from the onCreate method. In this next snippet, an instance of a TextView is used as the Activity’s UI:

@Override
public void onCreate(Bundle savedInstanceState) {
 super.onCreate(savedInstanceState);
 TextView textView = new TextView(this);
 setContentView(textView);
} 

There’s a good chance you’ll want to use a slightly more complex UI design. You can create a layout in code using layout View Groups, or you can use the standard Android convention of passing a resource ID for a layout defined in an external resource, as shown in the following snippet:

@Override
public void onCreate(Bundle savedInstanceState) {
 super.onCreate(savedInstanceState);
 setContentView(R.layout.main);
} 

To use an Activity in your application, you need to register it in the manifest. Add a new activity tag within the application node of the manifest; the activity tag includes attributes for metadata, such as the label, icon, required permissions, and themes used by the Activity .

<activity android:label="@string/app_name"
     android:name=".MyActivity">
</activity> 

An Activity without a corresponding activity tag can’t be used—attempting to start it will result in a runtime exception:

Within the activity tag you can add intent-filter nodes that specify the Intents that can be used to start your Activity. Each Intent Filter defines one or more actions and categories that your Activity supports. Intents and Intent Filters are covered in depth in Chapter 6 , but it’s worth noting that for an Activity to be available from the application launcher, it must include an Intent Filter listening for the MAIN action and the LAUNCHER category, as highlighted in Listing 3-2 .

Using the AppCompatActivity

As mentioned in Chapter 2 , the AppCompatActivity class is an Activity subclass available from the Android Support Library. It provides ongoing, backward compatibility for features added to the Activity class in each new platform release.

As such, it’s considered best practice to use the AppCompatActivity in preference to the Activity class, and we’ll continue to do so throughout this book, generally referring to classes that extend AppCompatActivity as Activities.

Listing 3-3 updates the code from Listing 3-1 showing the skeleton code for a new Activity that extends AppCompatActivity .

The Activity Life Cycle

A good understanding of the Activity life cycle is vital to ensure that your application provides a seamless user experience and properly manages its resources.

As explained earlier, Android applications do not control their own process lifetimes; the Android Run Time manages the process of each application, and by extension that of each Activity within it.

Although the run time handles the termination and management of an Activity’s process, the Activity’s state helps determine the priority of its parent application. The application priority, in turn, influences the likelihood that the run time will terminate it and the Activities running within it.

Activity Stacks and the Least-Recently Used (LRU) List

The state of each Activity is determined by its position on the Activity stack (or “back stack”), a last-in–first-out collection of all the currently running Activities. When a new Activity starts, it becomes active and is moved to the top of the stack. If the user navigates back using the Back button, or the foreground Activity is otherwise closed, the next Activity down on the stack moves up and becomes active. Figure 3-2 illustrates this process.

As described previously in this chapter, an application’s priority is influenced by its highest-priority Activity. When the Android memory manager is deciding which application to terminate to free resources, it uses this Activity stack to determine the priority of applications.

When none of an application’s Activities are visible, the application itself moves onto the least-recently used (LRU) list, which is used to determine the order in which applications will be terminated to free resources as described earlier.

Understanding Activity Lifetimes

To ensure that Activities can react to state changes, Android provides a series of event handlers that are fired as an Activity transitions through its full, visible, and active lifetimes. Figure 3-3 summarizes these lifetimes in terms of the Activity states described in the previous section.

Within an Activity’s full lifetime, between creation and destruction, it goes through one or more iterations of the active and visible lifetimes. Each transition triggers the method handlers previously described. The following sections provide a closer look at each of these lifetimes and the events that bracket them.

The Full Lifetime

The full lifetime of your Activity occurs between the first call to onCreate and when it is destroyed. It’s not uncommon for an Activity’s process to be terminated without the corresponding onDestroy handler being called.

Use the onCreate method to initialize your Activity: inflate the user interface, get references to Fragments, allocate references to class variables, bind data to controls, and start Services. If the Activity was terminated unexpectedly by the run time, the onCreate method is passed a Bundle object containing the state saved in the last call to onSaveInstanceState . You should use this Bundle to restore the UI to its previous state, either within the onCreate method or onRestoreInstanceState .

Override onDestroy to clean up any resources created in onCreate , and ensure that all external connections, such as network or database links, are closed.

As part of Android’s guidelines for writing efficient code, it’s recommended that you avoid repeated creation of short-term objects. The rapid creation and destruction of objects forces additional garbage collection, a process that can have a direct negative impact on the user experience. If your Activity creates the same set of objects regularly, consider creating them in the onCreate method, as it’s called only once during the Activity’s lifetime.

The Visible Lifetime

An Activity’s visible lifetimes are bounded between calls to onStart and onStop . Between these calls your Activity will be visible to the user, although it may not have focus and may be partially obscured. Activities are likely to go through several visible lifetimes during their full lifetime as they move between the foreground and background. Since Android 3.0 Honeycomb (API Level 11), you can safely assume onStop will be called before your application process is terminated.

The onStop method should be used to pause or stop animations, threads, Sensor listeners, GPS lookups, Timers, Services, or other processes that are used exclusively to update the UI. There’s little value in consuming resources (such as memory, CPU cycles, or network bandwidth) to update the UI when it isn’t visible. Use the onStart method to resume or restart these processes when the UI is visible again.

The onRestart method is called immediately prior to all but the first call to onStart . Use it to implement special processing that you want done only when the Activity restarts within its full lifetime.

The onStart / onStop methods should also be used to register and unregister Broadcast Receivers used exclusively to update the UI.

The Active Lifetime

The active lifetime starts with a call to onResume and ends with a corresponding call to onPause .

An active Activity is in the foreground and is receiving user input events. Your Activity is likely to go through many active lifetimes before it’s destroyed, as the active lifetime will end when a new Activity is displayed, the device goes to sleep, or the Activity loses focus. Try to keep code in the onPause and onResume methods fast and lightweight to ensure that your application remains responsive when moving in and out of the foreground. You can safely assume that during the active lifetime onPause will be called before the process is terminated.

Since Android 3.0 Honeycomb (API Level 11), the completion of the onStop handler marks the point beyond which an Activity may be killed without warning. This allows you to move all time-consuming operations required to save state into onStop , keeping your onPause lightweight and focused on suspending memory- or CPU-intensive operations while the Activity isn’t active. Depending on your application architecture, that may include suspending threads, processes, or Broadcast Receivers while your Activity is not in the foreground.

The corresponding onResume method should also be lightweight. You do not need to reload the UI state here, because this should handled by the onCreate and onRestoreInstanceState methods as required. Use onResume to reverse actions performed within onPause —such as allocating released resources, initializing or registering removed or unregistered components, and resuming any suspended behavior.

Responding to Memory Pressure

The Android system will terminate applications without warning in order to free resources required by any active and visible applications.

To provide the best possible user experience, Android must find a balance between killing applications to free resources and provide a responsive system, and retaining as many background apps as possible to improve the experience of switching between apps.

You can help by overriding the onTrimMemory handler, to respond to system requests that you reduce your memory usage. When killing application processes, the system will begin with empty processes before moving on to background applications—those hosting Activities that aren’t visible and that don’t have any running Services. In extreme cases, applications with visible Activities, or even foreground Services, may be terminated to free resources for the application hosting the active Activity.

The order in which applications are terminated is generally determined by the least-recently used (LRU) list—where the applications that have been unused the longest are the first killed. However, the run time does also consider the amount of memory potentially freed by killing each application, and is more likely to kill those that offer higher gains. So the less memory you consume, the less likely it is that your application will be terminated, and the better the overall system performance.

The onTrimMemory handler is available within each application component, including Activities and Services. It provides an opportunity for well-behaved applications to free additional memory when the system is running low on resources.

You should implement onTrimMemory to incrementally release memory based on current system constraints using the level parameter that provides context for the request. Note that the levels passed into onTrimMemory don’t represent a simple linear progression, but rather a series of contextual clues to help you decide how best to reduce overall system memory pressure:

• TRIM_MEMORY_RUNNING_MODERATE —Your application is running and not being considered for termination, but the system is beginning to feel memory pressure.
• TRIM_MEMORY_RUNNING_LOW —Your application is running and not being considered for termination, but the system is beginning to run significantly low on memory. Releasing memory now will improve system (and therefore your application’s) performance.
• TRIM_MEMORY_RUNNING_CRITICAL —Your application is running and not being considered for termination, but the system is running extremely low on memory. The system will now begin killing background processes if apps don’t free resources, so by releasing non-critical resources now you can prevent performance degradation and reduce the chance of other apps being terminated.
• TRIM_MEMORY_UI_HIDDEN —Your application is no longer displaying a visible UI. This is a good opportunity to release large resources that are used only by your UI. It’s considered good practice to do this here, rather than within your onStop handler, as it will avoid purging/reloading UI resources if your UI quickly switches from hidden to visible.
• TRIM_MEMORY_BACKGROUND —Your application is no longer visible and has been added to the least-recently used (LRU) list—and is therefore a low-risk candidate for termination. However, the system is running low on memory and may already be killing other apps on the LRU list. Release resources that are easy to recover now, to reduce system pressure and make your application less likely to be terminated.
• TRIM_MEMORY_MODERATE —Your application is in the middle of the LRU list and the system is running low on memory. If the system becomes further constrained for memory, there’s a good chance your process will be killed.
• TRIM_MEMORY_COMPLETE —Your application is one of the, if not the , most likely candidates for termination if the system does not recover memory immediately. You should release absolutely everything that’s not critical to resuming your application state.

Rather than compare the current level to these exact values, you should check if the level value is greater or equal to a level you are interested in, allowing for future intermediate state, as shown in Listing 3-5 .

Creating New Fragments

Extend the Fragment class to create a new Fragment, (optionally) defining the UI and implementing the functionality it encapsulates.

In most circumstances you’ll want to assign a UI to your Fragment. It is possible to create a Fragment that doesn’t include a UI but instead provides background behavior for an Activity. This is explored in more detail later in this chapter.

If your Fragment does require a UI, override the onCreateView handler to inflate and return the required View hierarchy, as shown in the Fragment skeleton code in Listing 3-6 .

You can create a layout in code using layout View Groups; however, as with Activities, the preferred way to design Fragment UI layouts is by inflating an XML resource.

Unlike Activities, Fragments don’t need to be registered in your manifest. This is because Fragments can exist only when embedded into an Activity, with their life cycles dependent on that of the Activity to which they’ve been added.

The Fragment Life Cycle

The life cycle events of a Fragment mirror those of its parent Activity; however, after the containing Activity is in its active—resumed—state, adding or removing a Fragment will affect its life cycle independently.

Fragments include a series of event handlers that mirror those in the Activity class. They are triggered as the Fragment is created, started, resumed, paused, stopped, and destroyed. Fragments also include a number of additional callbacks that indicate attaching and detaching the Fragment to and from its parent’s Context, creation (and destruction) of the Fragment’s View hierarchy, and the completion of the creation of the parent Activity.

Figure 3-4 summarizes the Fragment life cycle.

The skeleton code in Listing 3-7 shows the stubs for the life-cycle handlers available in a Fragment. Comments within each stub describe the actions you should consider taking on each state change event.

return inflater.inflate(R.layout.my_skeleton_fragment_layout, 
                        container, false); 

Introducing the Fragment Manager

Each Activity includes a Fragment Manager to manage the Fragments it contains. As we’re using the support library, we’ll access the Fragment Manager using the getSupportFragmentManager method:

FragmentManager fragmentManager = getSupportFragmentManager(); 

The Fragment Manager provides the methods used to access the Fragments currently added to the Activity, and to perform Fragment Transactions to add, remove, and replace Fragments.

Adding Fragments to Activities

The simplest way to add a Fragment to an Activity is by including it within the Activity’s layout using the fragment tag, as shown in Listing 3-8 .

Once the Fragment has been inflated, it becomes a View Group within the view hierarchy, laying out and managing its UI within the Activity.

This technique works well when you use Fragments to define a set of static layouts based on various screen sizes. If you plan to dynamically modify your layouts by adding, removing, and replacing Fragments at run time, a better approach is to create layouts that use container Views into which Fragments can be placed at run time, based on the current application state.

Listing 3-9 shows an XML snippet that you could use to support this approach.

You then need to create and add the corresponding Fragments to their appropriate parent containers within your Activity using Fragment Transactions, as described in the next section.

FragmentTransaction fragmentTransaction = fragmentManager.beginTransaction();

// Add, remove, and/or replace Fragments.
// Specify animations.
// Add to back stack if required.

fragmentTransaction.commitNow(); 

final static String MY_FRAGMENT_TAG = "detail_fragment"; 

FragmentTransaction fragmentTransaction = fragmentManager.beginTransaction();
fragmentTransaction.add(R.id.details_container, new DetailFragment(), 
            MY_FRAGMENT_TAG);
fragmentTransaction.commitNow(); 

FragmentTransaction fragmentTransaction = fragmentManager.beginTransaction();
Fragment fragment = fragmentManager.findFragmentByTag(MY_FRAGMENT_TAG);
fragmentTransaction.remove(fragment);
fragmentTransaction.commitNow(); 

FragmentTransaction fragmentTransaction = fragmentManager.beginTransaction();
fragmentTransaction.replace(R.id.details_container,
              new DetailFragment(selected_index),
              MY_FRAGMENT_TAG);
fragmentTransaction.commitNow(); 

protected void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);
  setContentView(R.layout.activity_main);

  if (savedInstanceState == null) {
    // Create and add your Fragments.
  } else {
    // Get references to Fragments that have already been restored.
  }  
} 

MyFragment myFragment =
  (MyFragment)fragmentManager.findFragmentById(R.id.MyFragment); 

DetailFragment detailFragment =
  (DetailFragment)fragmentManager.findFragmentById(R.id.details_container); 

DetailFragment detailFragment =
  (DetailFragment)fragmentManager.findFragmentByTag(MY_FRAGMENT_TAG); 

FragmentTransaction fragmentTransaction = fragmentManager.beginTransaction();

// Find and remove the list Fragment
Fragment fragment = fragmentManager.findFragmentById(R.id.ui_container);
fragmentTransaction.remove(fragment);

// Create and add the detail Fragment
fragmentTransaction.add(R.id.ui_container, new DetailFragment());

// Add the Fragment Transaction to the backstack and commit the change.
fragmentTransaction.addToBackStack(BACKSTACK_TAG);
fragmentTransaction.commit(); 

fragementTransaction.setTransition(FragmentTransaction.TRANSIT_FRAGMENT_OPEN); 

fragmentTransaction.setCustomAnimations(android.R.anim.fade_in,
                                        android.R.anim.fade_out); 

Communicating Between Fragments and Activities

When your Fragment needs to share events with its host Activity (such as signaling UI selections), it’s good practice to create a callback interface within the Fragment that a host Activity must implement.

Listing 3-12 shows a code snippet from within a Fragment class that defines a public event listener interface. The onAttach handler is overridden to obtain a reference to the host Activity, confirming that it implements the required interface. The onDetach handler sets our reference to null, and the onButtonPressed method is used as a placeholder example that calls the interface method on our parent Activity.

You can also use the getContext method within any Fragment to return a reference to the Context of the component within which it’s embedded.

Although it’s possible for Fragments to communicate with each other using the host Activity’s Fragment Manager, it’s generally considered better practice to use the Activity as an intermediary. This allows the Fragments to be as independent and loosely coupled as possible, with the responsibility for deciding how an event in one Fragment should affect the overall UI falling to the host Activity.

Fragments Without User Interfaces

In most circumstances, Fragments are used to encapsulate modular components of the UI; however, you can also create a Fragment without a UI to provide background behavior that persists across Activity restarts caused by configuration changes.

You can choose to have an active Fragment retain its current instance when its parent Activity is re-created using the setRetainInstance method. After you call this method, the Fragment’s life cycle will change.

Rather than being destroyed and re-created with its parent Activity, the same Fragment instance is retained when the Activity restarts. It will receive the onDetach event when the parent Activity is destroyed, followed by the onAttach , onCreateView , and onActivityCreated events as the new parent Activity is instantiated.

The following snippet shows the skeleton code for a Fragment without a UI:

public class WorkerFragment extends Fragment {

 public final static String MY_FRAGMENT_TAG = "my_fragment";

  @Override
  public void onAttach(Context context) {
    super.onAttach(context);

    // Get a type-safe reference to the parent context.
  }

  @Override
  public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);

    // Create ongoing threads and tasks.
  }

  @Override
  public void onActivityCreated(Bundle savedInstanceState) {
    super.onActivityCreated(savedInstanceState);

    // Initiate worker threads and tasks.
  }
} 

To add this Fragment to your Activity, create a new Fragment Transaction, specifying a tag to use to identify it. Because the Fragment has no UI, it should not be associated with a container View and must not be added to the back stack:

FragmentTransaction fragmentTransaction = fragmentManager.beginTransaction();

fragmentTransaction.add(new WorkerFragment(), WorkerFragment.MY_FRAGMENT_TAG);

fragmentTransaction.commitNow(); 

Use the findFragmentByTag from the Fragment Manager to find a reference to it later:

WorkerFragment workerFragment
  = (WorkerFragment)fragmentManager
     .findFragmentByTag(WorkerFragment.MY_FRAGMENT_TAG); 

Gradle Settings File

The settings.gradle file is located in your project’s root folder and is used to tell Gradle which modules it should include when building your application. By default, your single application module is included:

include ':app' 

If your project expands to use multiple modules, you would need to add them here.

Project Gradle Build File

The top-level project-scoped build.gradle file is located in the root project directory. It allows you to specify dependencies—and the repositories Gradle uses to search for and then download those dependencies—that apply to the project and all its modules.

The buildscript node is used to indicate the repositories and dependencies that are used by Gradle itself—not for your application.

For example, the default dependencies block includes the Android Plugin for Gradle, because that’s necessary for Gradle to build Android application modules, and the repositories block pre-configures JCenter and Google as repositories Gradle should use to look for it:

buildscript {
  repositories {
    google()
    jcenter()
  }
  dependencies {
    classpath 'com.android.tools.build:gradle:3.1.3'
  }
} 

Note that this is not where you indicate your application dependencies; they belong in the relevant module build.gradle file for your application module, as described in the next section.

Use the allprojects block to specify repositories and dependencies used by all modules in your project, though for projects with a single module it’s common practice to include its dependencies in the module-level build.gradle file.

For new projects, Android Studio adds JCenter and Google as default repositories.

allprojects {
  repositories {
    google()
    jcenter()
  }
} 

Android Studio also defines a new project task— clean —that deletes the contents of your project’s build folder:

task clean(type: Delete) {
  delete rootProject.buildDir
} 

Module Gradle Build Files

The module-level build.gradle file, located in each of your project’s module directories, is used to configure build settings for the corresponding module, including required dependencies, minimum and targeted platform versions, your application’s version information, and different build types and product flavors.

The first line in the build configuration applies the Android Plugin for Gradle to this build, which makes it possible to use the android block to specify Android-specific build options:

apply plugin: 'com.android.application' 

Within the top level of the android block you specify the Android application configuration options, such as the version of the SDK with which to compile your application. Be sure to update these values when you download a new SDK release:

android {
  compileSdkVersion 27

  defaultConfig {…}
  buildTypes {…}
  productFlavors {…}
  splits {…}
} 

defaultConfig {
  applicationId 'com.professionalandroid.apps.helloworld'

  minSdkVersion 16
  targetSdkVersion 27

  versionCode 1
  versionName "1.0"
} 

buildTypes {
  release {
    minifyEnabled true
    proguardFiles getDefaultProguardFile('proguard-android.txt'), 
                                         'proguard-rules.pro'
  }
} 

Product Flavors and Flavor Dimensions

The flavorDimensions and productFlavors blocks are optional nodes, not included by default, which allows you to override any of the values you defined in the defaultConfig block to support different versions (flavors) of your application using the same codebase. Each product flavor should specify its own unique application ID so that each can be distributed and installed independently:

productFlavors {
  freeversion {
    applicationId 'com.professionalandroid.apps.helloworld.free'
    versionName "1.0 Free" 
  }

  paidversion {
    applicationId 'com.professionalandroid.apps.helloworld.paid'
    versionName "1.0 Full"
  }
} 

Flavor dimensions allow you to create groups of product flavors that can be combined to create a final build variant. This allows you to specify build changes along multiple dimensions—for example, changes based on free versus paid builds—as well as changes based on minimum API level:

flavorDimensions "apilevel", "paylevel"

productFlavors {
    freeversion {
      applicationId 'com.professionalandroid.apps.helloworld.free'
      versionName "1.0 Free" 
      dimension "paylevel"
  }

    paidversion {
applicationId 'com.professionalandroid.apps.helloworld.paid'
      versionName "1.0 Full"
      dimension "paylevel"
  }

    minApi24 {
      dimension "apilevel"
      minSdkVersion 24
      versionCode 24000 + android.defaultConfig.versionCode
      versionNameSuffix "-minApi24"
  }

    minApi23 {
      dimension "apilevel"
      minSdkVersion 16
      versionCode 16000 + android.defaultConfig.versionCode
      versionNameSuffix "-minApi23"
  }
  }
} 

When building your application, Gradle will combine the product flavors along each dimension, along with a build type configuration, to create the final build variant. Gradle does not combine product flavors that belong to the same flavor dimension.

Note that Gradle determines the priority of flavor dimensions based on the order in which they are specified, where the first dimension will override values assigned along the second dimension and so on.

Since Gradle 3.0.0, in order to define flavors, you must define at least one product dimension. Each flavor must have an associated product dimension, though if you have only one dimension defined, it will be used by default by each flavor.

You can detect the current product flavor at run time, and modify your product behavior accordingly, using this code snippet:

if (BuildConfig.FLAVOR == "orangesherbert") {
  // Do groovy things
} else {
  // Enable paid features
} 

Alternatively, you can create a new set of classes and resources—a new source-set—for your application to use for each flavor, by creating an additional directory structure parallel to the default “main” source path.

For classes, you’ll need to create the folders manually, whereas for resources, you can choose the source-set a new resource should belong to, as shown in the New Resource File dialog box in Figure 4-2 .

Within Android Studio, you can select the build you wish to build and run using the Build Select Build Variant menu item and selecting it from the drop-down displayed in the Build Variant window.

dependencies {
  implementation fileTree(dir: 'libs', include: ['*.jar'])
  implementation 'com.android.support:appcompat-v7:27.1.1'
  implementation 'com.android.support.constraint:constraint-layout:1.1.2'
  testImplementation 'junit:junit:4.12'
  androidTestImplementation 'com.android.support.test:runner:1.0.2'
  androidTestImplementation 'com.android.support.test.espresso:espresso-core:3.0.2'
} 

Creating Resources

Application resources are stored under the res folder in your project hierarchy. Each of the available resource types is stored in subfolders, grouped by resource type.

If you create a new project using the Android Studio New Project Wizard, it creates a res folder that contains subfolders for the values , mipmap , and layout resources that contain the default values for string, dimensions, color, and style resource, as well as an application icon and the default layout, as shown in Figure 4-3 .

When your application is built, these resources will be compressed as efficiently as possible and packaged into your APK.

The build process also generates an R class file that contains references to each of the resources included in your project. This enables you to reference resources from your code, with the advantage of design-time syntax checking.

The following sections describe many of the specific resource types available and how to create them for your applications.

In all cases, the resource filenames should contain only lowercase letters, numbers, and the period (.) and underscore ( _ ) symbols.

<string name="stop_message">Stop.</string> 

<string name="quoting_myself">
Escape \"Apostrophes (\') and double-quotes (\") with a backslash (\\)\"
</string> 

<string name="stop_message"><b>Stop.</b></string> 

<string name="stop_message"><b>Stop</b>. %1$s</string> 

String rString = getString(R.string.stop_message);
String fString = String.format(rString, "Collaborate and listen.");
CharSequence styledString = Html.fromHtml(fString, FROM_HTML_MODE_LEGACY); 

<plurals name="unicorn_count">
  <item quantity="one">One unicorn</item>
  <item quantity="other">%d unicorns</item>
</plurals> 

Resources resources = getResources();
String unicornStr = resources.getQuantityString(
  R.plurals.unicorn_count, unicornCount, unicornCount); 

<color name="android_green">#A4C639</color>
<color name="transparent_blue">#770000FF</color> 

<dimen name="large_font_size">16sp</dimen>
<dimen name="activity_horizontal_margin">16dp</dimen> 

<style name="base_text">
  <item name="android:textSize">14sp</item>
  <item name="android:textColor">#111</item>
</style> 

<style name="AppTheme" parent="Theme.AppCompat.Light.DarkActionBar">
  <item name="colorPrimary">@color/colorPrimary</item>
  <item name="colorPrimaryDark">@color/colorPrimaryDark</item>
  <item name="colorAccent">@color/colorAccent</item>
</style> 

<?xml version="1.0" encoding="utf-8"?>
<objectAnimator xmlns_android="http://schemas.android.com/apk/res/android"
   android:propertyName="alpha"
   android:duration="1000"
   android:valueFrom="0f"
   android:valueTo="1f"
/> 

<?xml version="1.0" encoding="utf-8"?>
<set xmlns_android="http://schemas.android.com/apk/res/android"
     android:ordering="sequentially">
  <set>
    <objectAnimator
      android:propertyName="x"
      android:duration="200"
      android:valueTo="0"
      android:valueType="intType"/>
    <objectAnimator
      android:propertyName="y"
      android:duration="200"
      android:valueTo="0"
      android:valueType="intType"/>
  </set>
  <objectAnimator
    android:propertyName="alpha"
    android:duration="1000"
    android:valueTo="1f"/>
</set> 

<?xml version="1.0" encoding="utf-8"?>
<set xmlns_android="http://schemas.android.com/apk/res/android"
     android:interpolator="@android:anim/accelerate_interpolator">
  <rotate
    android:fromDegrees="0"
    android:toDegrees="360"
    android:pivotX="50%"
    android:pivotY="50%"
    android:startOffset="500"
    android:duration="1000" />
  <scale
    android:fromXScale="1.0"
    android:toXScale="0.0"
    android:fromYScale="1.0"
    android:toYScale="0.0"
    android:pivotX="50%"
    android:pivotY="50%"
    android:startOffset="500"
    android:duration="500" />
  <alpha
    android:fromAlpha="1.0"
    android:toAlpha="0.0"
    android:startOffset="500"
    android:duration="500" />
</set> 

<animation-list
  xmlns_android="http://schemas.android.com/apk/res/android"
  android:oneshot="false">
  <item android:drawable="@drawable/android1" android:duration="500" />
  <item android:drawable="@drawable/android2" android:duration="500" />
  <item android:drawable="@drawable/android3" android:duration="500" />
</animation-list> 

ImageView androidIV = findViewById(R.id.iv_android);
androidIV.setBackgroundResource(R.drawable.android_anim);

AnimationDrawable androidAnimation =
  (AnimationDrawable)androidIV.getBackground();

androidAnimation.start(); 

Using Resources

In addition to the resources you supply, the Android platform includes several system resources that you can use in your applications. All resources can be used within your application code, and can also be referenced from within other resources. For example, a dimension or string resource might be referenced in a layout definition.

Later in this chapter you learn how to define alternative resource values for different languages, locations, and hardware. It’s important to note that when using resources, you don’t choose a particular alternative; Android automatically selects the correct value for a given resource identifier based on the current hardware, device, and language configurations.

// Inflate a layout resource.
setContentView(R.layout.main);
// Display a transient dialog box that displays the
// app name string resource.
Toast.makeText(this, R.string.app_name, Toast.LENGTH_LONG).show(); 

Resources myRes = getResources(); 

CharSequence styledText = myRes.getText(R.string.stop_message);

float borderWidth = myRes.getDimension(R.dimen.standard_border);

Animation tranOut;
tranOut = AnimationUtils.loadAnimation(this, R.anim.spin_shrink_fade);

ObjectAnimator animator =
  (ObjectAnimator)AnimatorInflater.loadAnimator(this,
  R.animator.my_animator);

String[] stringArray;
stringArray = myRes.getStringArray(R.array.string_array);

int[] intArray = myRes.getIntArray(R.array.integer_array); 

Drawable img = ResourcesCompat.getDrawable(myRes,
  R.drawable.an_image, myTheme);
int opaqueBlue = ResourcesCompat.getColor(myRes, 
                                          R.color.opaque_blue, myTheme); 

AnimationDrawable androidAnimation;
androidAnimation =
  (AnimationDrawable)ResourcesCompat.getDrawable(R.myRes,
                                                 drawable.frame_by_frame,
                                                 myTheme); 

attribute="@[packagename:]resourcetype/resourceidentifier" 

CharSequence httpError = getString(android.R.string.httpErrorBadUrl); 

<EditText
  android:id="@+id/myEditText"
  android:layout_width="match_parent"
  android:layout_height="wrap_content"
 android:text="@android:string/httpErrorBadUrl"
 android:textColor="@android:color/darker_gray"
/> 

<EditText
  android:id="@+id/myEditText"
  android:layout_width="match_parent"
  android:layout_height="wrap_content"
  android:text="@android:string/httpErrorBadUrl"
 android:textColor="?android:textColor"
/> 

Creating Resources for Different Languages and Hardware

You can create different resource values for specific languages, locations, and hardware configurations using a parallel directory structure within the res folder.

A hyphen ( - ) is used to separate qualifiers that specify the conditions for which you are providing alternatives. Android chooses from among these values dynamically at run time using its dynamic resource-selection mechanism.

The following example hierarchy shows a folder structure that features default string values, with French language and French Canadian location variations:

Project/
  res/
    values/
      strings.xml
    values-fr/
      strings.xml
    values-fr-rCA/
      strings.xml 

If you’re using Android Studio, these parallel folders are represented as shown in Figure 4-4 —a folder with the name of the file, that contains each version, followed by the qualifier in parentheses.

You can construct these qualified folders manually or, using Android Studio, you can create new folders as required when creating the alternative files they’ll contain.

To do so, either right-click the parent folder (for example, res/values ) and select “New [Values] resource file,” or select the parent folder and select File New [Values] resource file. This displays the New Resource File dialog box as shown in Figure 4-5 , which provides all the optional qualifier categories, and available options, before creating the folder and placing your new file within it. Note that not every available qualifier is available in the Android Studio dialog; in this case you’ll have to create the folder manually.

The following list gives the qualifiers you can use to customize your resource values:

• Mobile Country Code and Mobile Network Code (MCC/MNC) —The country, and optionally the network, associated with the SIM currently used in the device. The MCC is specified by mcc followed by the three-digit country code. You can optionally add the MNC using mnc and the two- or three-digit network code (for example, mcc234-mnc20 or mcc310 ). You can find a list of MCC/MNC codes on Wikipedia at en.wikipedia.org/wiki/Mobile_country_code .
• Language and Region —Language specified by the lowercase two-letter ISO 639-1 language code, followed optionally by a region specified by a lowercase r followed by the uppercase two-letter ISO 3166-1-alpha-2 language code (for example, en , en - rUS , or en-rGB ). Available under “locale” within the Android Studio “New Resource File” dialog.
• Layout Direction —The layout direction of your user interface where ldrtl represents right-to-left, and ldltr left-to-right (the default value). Use this modifier to provide a different layout (or any other resource) to better support right-to-left languages.
• Smallest Screen Width —The lowest of the device’s screen dimensions (height and width) specified in the form sw<Dimension value>dp (for example, sw600dp , sw320dp , or sw720dp ). This is generally used when providing multiple layouts, where the value specified should be the smallest screen width that your layout requires in order to render correctly. Where you supply multiple directories with different smallest screen width qualifiers, Android selects the largest value that doesn’t exceed the smallest dimension available on the device.
• Available Screen Width —The minimum screen width required to use the contained resources, specified in the form w<Dimension value>dp (for example, w600dp , w320dp , or w720dp ). Also used to supply multiple layouts alternatives, but unlike smallest screen width, the available screen width changes to reflect the current screen width when the device orientation changes. Android selects the largest value that doesn’t exceed the currently available screen width.
• Available Screen Height —The minimum screen height required to use the contained resources, specified in the form h<Dimension value>dp (for example, h720dp , h480dp , or h1280dp ). Like available screen width, the available screen height changes when the device orientation changes to reflect the current screen height. Android selects the largest value that doesn’t exceed the currently available screen height.
• Screen Size —One of small (smaller than HVGA), normal (at least HVGA and typically smaller than VGA), large (VGA or larger), or xlarge (significantly larger than HVGA). Because each of these screen categories can include devices with significantly different screen sizes (particularly tablets), it’s good practice to use the more specific smallest screen size, and available screen width and height whenever possible. Because they precede this screen size qualifier, where both are specified, the more specific qualifiers will be used in preference where supported.
• Screen Aspect Ratio —Specify long or notlong for resources designed specifically for wide screen. (For example, WVGA is long ; QVGA is notlong .)
• Screen Shape —Specify round or notround for resources designed specifically for round screens (such as watches) or rectangular screens (such as phones or tablets), respectively.
• Screen Color Gamut —Specify widecg for resources designed for displays capable of displaying a wide color gamut such as Display P3 or AdobeRGB, or nowidecg for displays with a narrow color gamut such as sRGB.
• Screen Dynamic Range —Either highdr for displays that support a high-dynamic range (HDR) or lowdr for displays with a normal dynamic range.
• Screen Orientation: One of port (portrait) or land (landscape).
• UI Mode —Indicate resources (typically layouts) designed specifically for one of car (car dock), desk (desk dock), television (10 foot lean-back experience), appliance (no visible UI), watch (wrist mounted display), or vrheadset (virtual reality headset.
• Night Mode —One of night (night mode) or notnight (day mode). Used in combination with the UI mode qualifier, this provides a simple way to change the theme and/or color scheme of an application to make it more suitable for use at night.
• Screen Pixel Density —Pixel density in dots per inch (dpi). Best practice is to supply ldpi , mdpi , hdpi , xhdpi , and xxhdpi Drawable resources to include low (120 dpi), medium (160 dpi), high (240 dpi), extra high (320 dpi), and extra extra high (480 dpi) pixel density assets, to ensure crisp assets on all devices. For launcher icons, it’s good practice to also supply an xxxhdpi resource for launchers that may choose to display a larger icon. You can specify nodpi for bitmap resources you don’t want scaled to support an exact screen density, and anydpi for scalable vector graphics. To better support applications targeting televisions running Android, you can also use the tvdpi qualifier for assets of approximately 213dpi. This is generally unnecessary for most applications, where including medium- and high-resolution assets is sufficient for a good user experience. Unlike with other resource types, Android does not require an exact match to select a resource. When selecting the appropriate folder, it chooses the nearest match to the device’s pixel density and scales the resulting Drawables accordingly.
• Touchscreen Type —Either notouch or finger , allowing you to provide layouts or dimensions optimized for the availability of touch screen input.
• Keyboard Availability —One of keysexposed , keyshidden , or keyssoft , representing a device that currently has a hardware keyboard available, a hardware keyboard that’s not currently available, or uses a software keyboard (visible or not), respectively.
• Keyboard Input Type —One of nokeys , qwerty , or 12key representing no physical keyboard, a full qwerty keyboard, or 12-key physical keyboard, respectively—whether the keyboard is currently available or not.
• Navigation Key Availability —One of navexposed or navhidden .
• UI Navigation Type —One of nonav , dpad , trackball , or wheel .
• Platform Version —The target API level, specified in the form v<API Level> (for example, v7 ). Used for resources restricted to devices running at the specified API level or higher.

You can specify multiple qualifiers for any resource type, separating each qualifier with a hyphen. Any combination is supported; however, they must be used in the order given in the preceding list, and no more than one value can be used per qualifier.

The following example shows valid and invalid directory names for alternative layout resources:

 
Valid

    layout-large-land
    layout-xlarge-port-keyshidden
    layout-long-land-notouch-nokeys 

 
Invalid

    values-rUS-en (out of order)
    values-rUS-rUK (multiple values for a single qualifier) 

When Android retrieves a resource at run time, it finds the best match from the available alternatives. Starting with a list of all the folders in which the required value exists, it selects the one with the greatest number of matching qualifiers. If two folders are an equal match, the tiebreaker is based on the order of the matched qualifiers in the preceding list.

Runtime Configuration Changes

Android handles runtime changes to the language, location, and hardware by terminating and restarting the active Activity. This forces the resource resolution for the Activity to be reevaluated and the most appropriate resource values for the new configuration to be selected.

In some special cases this default behavior may be inconvenient, particularly for applications that don’t want to alter UI based on screen orientation changes. You can customize your application’s response to such changes by detecting and reacting to them yourself.

To have an Activity listen for runtime configuration changes, add an android:configChanges attribute to its manifest node, specifying the configuration changes you want to handle.

The following list describes some of the configuration changes you can specify:

• mcc and mnc —A SIM has been detected and the mobile country or network code (respectively) has changed.
• locale —The user has changed the device’s language settings.
• keyboardHidden —The keyboard, d-pad, or other input mechanism has been exposed or hidden.
• keyboard —The type of keyboard has changed; for example, the phone may have a 12-key keypad that flips out to reveal a full keyboard, or an external keyboard might have been plugged in.
• fontScale —The user has changed the preferred font size.
• uiMode —The global UI mode has changed. This typically occurs if you switch between car mode, day or night mode, and so on.
• orientation —The screen has been rotated between portrait and landscape.
• screenLayout —The screen layout has changed; typically occurs if a different screen has been activated.
• screenSize —Occurs when the available screen size has changed; for example, a change in orientation between landscape and portrait or with multi-window mode.
• smallestScreenSize —Occurs when the physical screen size has changed, such as when a device has been connected to an external display.
• layoutDirection —The screen/text layout direction has changed; for example, switching between left-to-right and right-to-left (RTL).

In certain circumstances multiple events will be triggered simultaneously. For example, when the user slides out a keyboard, most devices fire both the keyboardHidden and orientation events, and connecting an external display is likely to trigger orientation , screenLayout , screenSize , and smallestScreenSize events.

You can select multiple events you want to handle yourself by separating the values with a pipe ( | ), as shown in Listing 4-4 , which shows an Activity node declaring that it will handle changes in screen size and orientation, and access to a physical keyboard.

Adding an android:configChanges attribute suppresses the restart for the specified configuration changes, instead triggering the onConfigurationChanged handler in the associated Activity. Override this method to handle the configuration changes yourself, using the passed-in Configuration object to determine the new configuration values, as shown in Listing 4-5 . Be sure to call back to the superclass and reload any resource values that the Activity uses, in case they’ve changed.

When onConfigurationChanged is called, the Activity’s Resource variables have already been updated with the new values, so they’ll be safe to use.

Any configuration change that you don’t explicitly flag as being handled by your application will cause your Activity to restart, without a call to onConfigurationChanged .

Assigning User Interfaces to Activities

A new Activity starts with an invitingly empty screen, onto which you can place your UI. To do so, call setContentView , passing in the View instance, or layout resource, to display.

An empty screen lacks the visceral appeal required by today’s savvy users, so you’ll almost always use setContentView to assign an Activity’s UI when overriding its onCreate handler. Because the setContentView method accepts either a layout’s resource ID or a single View instance at the root of your view hierarchy, you can define your UI either in code or using the best-practice technique of external layout resources:

@Override
public void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);
 setContentView(R.layout.main);
} 

Using layout resources allows you to decouple the presentation layer from the application logic, providing the flexibility to change the presentation without changing code. This makes it possible to specify different layouts optimized for different hardware configurations, even changing them at run time based on hardware changes (such as screen orientation changes).

Once the layout has been set, you can obtain a reference to each of the Views within it using the findViewById method:

TextView myTextView = findViewById(R.id.myTextView); 

If you’re using Fragments to encapsulate portions of your Activity’s UI, the View set within your Activity’s onCreate handler will be a layout that describes the relative position of each of your Fragments (or their containers). The UI used for each Fragment is defined in its own layout and inflated within the Fragment itself and should, in almost all cases, be handled solely by that Fragment.

Defining Layouts

The preferred way to define a layout is by using XML external resources, either by manually writing the XML or using the Constraint Layout’s visual layout editor to create it for you.

Each layout XML must contain a single root element, which can contain as many nested layouts and Views as necessary to construct an arbitrarily complex UI.

The following snippet shows a simple layout that places a TextView above an EditText control using a vertical LinearLayout that covers the full screen height and width:

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns_android="http://schemas.android.com/apk/res/android"
  android:layout_width="match_parent"
  android:layout_height="match_parent"
  android:orientation="vertical">
  <TextView
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:text="Enter Text Below" />
  <EditText
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:text="Text Goes Here!" />
</LinearLayout> 

For each of the layout elements, the constants wrap_content and match_parent are used rather than specifying an exact height or width in pixels (or dp). These constants, combined with layouts that scale (such as the Linear Layout, Relative Layout, and Constraint Layout) offer the simplest, and most powerful, technique for ensuring your layouts are screen-size and resolution independent.

The wrap_content constant sets the size of a View to the minimum required to contain the contents it displays (such as the height required to display a wrapped text string). The match_parent constant expands the View to match the available space within the parent View, Fragment, or Activity.

Later in this chapter you’ll learn how these constants are used when creating your own controls, as well as further best practices for resolution independence.

Implementing layouts in XML decouples the presentation layer from the View, Fragment, and Activity controller code and business logic. It also lets you create hardware configuration–specific variations that are dynamically loaded without requiring code changes.

When preferred, or required, you can implement layouts in code. When assigning Views to layouts in code, it’s important to apply LayoutParameters using the setLayoutParams method, or by passing them into the addView call:

LinearLayout ll = new LinearLayout(this);
ll.setOrientation(LinearLayout.VERTICAL);

TextView myTextView = new TextView(this);
EditText myEditText = new EditText(this);

myTextView.setText("Enter Text Below");
myEditText.setText("Text Goes Here!");

int lHeight = LinearLayout.LayoutParams.MATCH_PARENT;
int lWidth = LinearLayout.LayoutParams.WRAP_CONTENT;

ll.addView(myTextView, new LinearLayout.LayoutParams(lWidth, lHeight));
ll.addView(myEditText, new LinearLayout.LayoutParams(lWidth, lHeight));

setContentView(ll); 

Using Layouts to Create Device-Independent User Interfaces

A defining feature of the layout classes is their ability to scale and adapt to a range of screen sizes, resolutions, and orientations.

The variety of Android devices is a critical part of the platform’s success, but for us as application developers, it introduces a challenge in designing UIs that offer the best possible experience for users, regardless of which Android device they own.

Using a Constraint Layout

The Constraint Layout provides the most flexibility of any of the Layout Managers, offering the advantage of both a visual layout editor, and a flat view hierarchy without the nesting shown in the previous examples.

It’s available as part of the Android Support Library, and must be included as a dependency to your project’s module-level build.gradle file:

dependencies {
  [… Existing dependencies …]
  implementation 'com.android.support.constraint:constraint-layout:1.1.2'
} 

As the name suggests, the Constraint Layout positions its child Views through the specification of constraints that define the relationship between a View and elements such as boundaries, other views, and custom guidelines.

While it’s possible to define a Constraint Layout in XML manually, it’s much simpler (and less error prone) to use the visual layout editor. Figure 5-2 shows the Layout Editor used to create the same UI as the previous example using a Constraint Layout.

Listing 5-3 shows the XML produced by the visual editor in Figure 5-2 .

Notice in particular that this layout removes the need to nest a second layout within the parent Constraint Layout. Flattening our hierarchy reduces the number of measure and layout passes required to render it on screen, making it more efficient as described in more detail in the following section.

Optimizing Layouts

Inflating layouts is an expensive process; each additional nested layout and included View directly impacts on the performance and responsiveness of your application. This is one of the reasons why Constraint Layout, with its ability to flatten the View hierarchy, is strongly recommended.

To keep your applications smooth and responsive, it’s important to keep your layouts as simple as possible, and to avoid inflating entirely new layouts for relatively small UI changes.

<?xml version="1.0" encoding="utf-8"?>
<FrameLayout
  xmlns_android="http://schemas.android.com/apk/res/android"
  android:layout_width="match_parent"
  android:layout_height="match_parent">
  <ImageView
    android:id="@+id/myImageView"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:src="@drawable/myimage"
  />
  <TextView
    android:id="@+id/myTextView"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:text="@string/hello"
    android:gravity="center_horizontal"
    android:layout_gravity="bottom"
  />
</FrameLayout> 

<?xml version="1.0" encoding="utf-8"?>
<merge
  xmlns_android="http://schemas.android.com/apk/res/android">
  <ImageView
    android:id="@+id/myImageView"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:src="@drawable/myimage"
  />
  <TextView
    android:id="@+id/myTextView"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:text="@string/hello"
    android:gravity="center_horizontal"
    android:layout_gravity="bottom"
  />
</merge> 

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout
  xmlns_android="http://schemas.android.com/apk/res/android"
  android:orientation="vertical"
  android:layout_width="match_parent"
  android:layout_height="match_parent">
  <include android:id="@+id/my_action_bar"
               layout="@layout/actionbar"/>
  <include android:id="@+id/my_image_text_layout"
               layout="@layout/image_text_layout"/>
</LinearLayout> 

// Find the stub
View stub = findViewById(R.id.download_progress_panel_stub);
// Make it visible, causing it to inflate the child layout
stub.setVisibility(View.VISIBLE);

// Find the root node of the inflated stub layout
View downloadProgressPanel = findViewById(R.id.download_progress_panel); 

<?xml version="1.0" encoding="utf-8"?>
<FrameLayout "xmlns_android=http://schemas.android.com/apk/res/android"
  android:layout_width="match_parent"
  android:layout_height="match_parent">
  <ListView
    android:id="@+id/myListView"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
  />
  <ViewStub
    android:id="@+id/download_progress_panel_stub"

    android:layout="@layout/progress_overlay_panel"
    android:inflatedId="@+id/download_progress_panel"

    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:layout_gravity="bottom"
  />
</FrameLayout> 

Using Lint to Analyze Your Layouts

To assist you in optimizing your layout hierarchies, the Android SDK includes lint —a powerful tool that you can use to detect problems within your application, including layout performance issues.

The Lint tool is available within Android Studio through the Inspect Code option in the Analyze menu as shown in Figure 5-3 , or as a command-line tool.

In addition to using Lint to detect each optimization issue described previously in this section, you can also use Lint to detect missing translations, unused resources, inconsistent array sizes, accessibility and internationalization problems, missing or duplicated image assets, usability problems, and manifest errors.

Lint is a constantly evolving tool, with new rules added regularly. You can find a full list of the tests performed by the Lint tool at http://tools.android.com/tips/lint-checks .

Recycler View and Layout Managers

The RecyclerView itself doesn’t control how each item is displayed; that responsibility belongs to the associated RecyclerView.LayoutManager . This separation of duties allows you to substitute Layout Manager classes, without affecting other parts of your application.

A number of Layout Managers are available, as shown in Figure 5-4 , and described here:

• LinearLayoutManager —Lays out items in a single vertical or horizontal list.
• GridLayoutManager —Similar to the Linear Layout Manager, but displays a grid. When laid out vertically, each row can include multiple items, where each is the same height. For horizontal orientation each item in a given column must be the same width.
• StaggeredGridLayoutManager —Similar to the Grid Layout Manager but creates a “staggered” grid, where each grid cell can have a different height or width, with cells staggered to eliminate gaps.

The Layout Manager operates in the same way as a standard layout—responsible for laying out the Views representing each item in your dataset.

The Recycler View gets its name from the way it supports scrolling. Rather than creating a view for each item upfront, or continually creating them when they’re scrolled into view, the Recycler View is able to “recycle” existing Views that are no longer visible—changing their content and position to represent newly visible items.

To support this behavior, the Layout Manager is also responsible for determining when a View can safely be recycled. In most cases, this allows the Recycler View to support a nearly infinite (2 ²⁶ ) list of items, while creating just enough Views to fill a single screen.

The Layout Manager for a Recycler View can be set either in XML or programmatically.

For example, the following snippet lays out a vertically aligned Recycler View with a Grid Layout Manager that features two columns:

<android.support.v7.widget.RecyclerView
  xmlns_android:"http://schemas.android.com/apk/res/android"
  xmlns_app="http://schemas.android.com/apk/res-auto"
  android:id="@+id/recycler_view"
  android:layout_width="match_parent"
  android:layout_height="match_parent"
  android:orientation="vertical"
  app:layoutManager="GridLayoutManager"
  app:spanCount="2" 
/> 

To assign the same Layout Manager in code, for an existing Recycler View, you would use the following snippet:

RecyclerView recyclerView = findViewById(R.id.recycler_view);
GridLayoutManager gridLayoutManager = new GridLayoutManager(2);
recyclerView.setLayoutManager(gridLayoutManager); 

Introducing Adapters

Layout Managers aren’t particularly useful until you have data for them to display; that data is provided by the RecyclerView.Adapter . The Adapter has two important roles:

• The initial creation of the Views to display, including inflating the appropriate layout
• The creation of the View Holders you’ll use to “bind” the View elements to the underlying data source

A View Holder stores the View to be displayed, and also allows the Adapter to store additional metadata and View references to simplify data binding, as shown later. This typically includes finding references to any child Views within an item layout (ensuring that work is only done once).

The Adapter’s onCreateViewHolder method is called to get a new RecyclerView.ViewHolder instance whenever the Layout Manager doesn’t have an unused View to reuse—typically only enough views to fill the screen.

Listing 5-4 shows a simple Adapter implementation that uses a single Text View to display a data stored in an array of strings.

Notice that the View Holder itself doesn’t assign values from the underlying data to the Views it contains—its role is to make the elements within the View’s layout available for the adapter to bind data to them.

Every time an item needs to be displayed, the Layout Manager will call the Adapter’s onBindViewHolder method, providing you a previously created ViewHolder and the position in the dataset requested. This binding phase runs very frequently when scrolling through a list (once for every element that scrolls into view) so it should be as lightweight as possible.

@Override
public void onBindViewHolder(ViewHolder holder, int position) {
  holder.textView.setText(mData[position]);
} 

To assign your Adapter to a Recycler View, use the setAdapter method:

RecyclerView recyclerView = findViewById(R.id.recycler_view);
SimpleAdapter adapter = 
  new SimpleAdapter(new String[] {"Sample", "Sample 2"});

recyclerView.setAdapter(adapter); 

Static datasets like this example are fun, but in reality we’re rarely that lucky. In most cases the underlying data will change when new data is loaded from the server, if the user adds or deletes an item, or even if the sort order is changed.

When you update an Adapter with new or changed data, you must call one of the Adapter’s notify methods to inform the Layout Manager that something has changed. The RecyclerView will then animate a transition between the previous and updated states (cross fading changed items, collapsing and removing removed items, and animating in new items).

You can customize the animations used for each state change by assigning a RecyclerView.ItemAnimator using the setItemAnimator method.

There are different methods for notifying the change, insertion, move, or removal of a single item, and for a range of items. You can use the DiffUtil class to understand which changes should be applied to transition from one dataset to another, as shown in Listing 5-5 .

Returning to the Earthquake Viewer Application

With the newfound knowledge of layouts and Views, we can improve the Earthquake Viewer built in Chapter 3 , replacing the simple TextView with a more complicated layout that better displays the data in the Earthquake class:

1. Replace the list_item_earthquake.xml layout resource with a new layout that uses a Constraint Layout to display the magnitude, date, and details in separate Text Views:

   <?xml version="1.0" encoding="utf-8"?>
   <android.support.constraint.ConstraintLayout
     xmlns_android="http://schemas.android.com/apk/res/android"
     xmlns_app="http://schemas.android.com/apk/res-auto"
     android:layout_width="match_parent"
     android:layout_height="wrap_content"
     android:paddingLeft="@dimen/activity_vertical_margin"
     android:paddingRight="@dimen/activity_vertical_margin">
     <TextView
       android:id="@+id/magnitude"
       android:layout_width="wrap_content"
       android:layout_height="0dp"
       android:gravity="center_vertical"
       app:layout_constraintRight_toRightOf="parent"
       app:layout_constraintTop_toTopOf="parent"
       app:layout_constraintBottom_toBottomOf="parent"
       android:textAppearance="?attr/textAppearanceListItem"/>
     <TextView
       android:id="@+id/date"
       android:layout_width="0dp"
       android:layout_height="wrap_content"
       android:layout_marginTop="@dimen/text_margin"
       app:layout_constraintLeft_toLeftOf="parent"
       app:layout_constraintTop_toTopOf="parent"
       app:layout_constraintRight_toLeftOf="@id/magnitude"/>
     <TextView
       android:id="@+id/details"
       android:layout_width="0dp"
       android:layout_height="wrap_content"
       android:layout_marginBottom="@dimen/text_margin"
       app:layout_constraintLeft_toLeftOf="parent"
       app:layout_constraintBottom_toBottomOf="parent"
       app:layout_constraintRight_toLeftOf="@id/magnitude"
       app:layout_constraintTop_toBottomOf="@id/date"/>
   </android.support.constraint.ConstraintLayout> 

2. Update the EarthquakeRecyclerViewAdapter to cache the new Views elements added in Step 1 within the View Holder constructor, and then bind those Views to each Earthquake item within the onBindViewHolder by using java.text.SimpleDateFormat :

   private static final SimpleDateFormat TIME_FORMAT =
       new SimpleDateFormat("HH:mm", Locale.US);
   private static final NumberFormat MAGNITUDE_FORMAT =
       new DecimalFormat("0.0");
   
   public static class ViewHolder extends RecyclerView.ViewHolder {
     public final TextView date;
     public final TextView details;
     public final TextView magnitude;
   
     public ViewHolder(View view) {
       super(view);
       date = (TextView) view.findViewById(R.id.date);
       details = (TextView) view.findViewById(R.id.details);
       magnitude = (TextView) view.findViewById(R.id.magnitude);
     }
   }
   
   @Override
   public void onBindViewHolder(ViewHolder holder, int position) {
     Earthquake earthquake = mEarthquakes.get(position);
     
     holder.date.setText(TIME_FORMAT.format(earthquake.getDate()));
     holder.details.setText(earthquake.getDetails());
     holder.magnitude.setText(
         MAGNITUDE_FORMAT.format(earthquake.getMagnitude()));
   } 

Enabling Data Binding

Data Binding is an optional library, so before you can take advantage of it you must enable it in your application module’s build.gradle file:

android {
  [… Existing Android Node …]
  dataBinding.enabled = true
}

dependencies {
  [… Existing dependencies element …]
  implementation 'com.android.support:support-v4:27.1.1'
} 

Once enabled, you can apply Data Binding to any layout by wrapping the elements of a layout file in a new <layout> element, as seen in Listing 5-6 :

This triggers Data Binding to generate a Binding class based on the name of the modified layout file. For example, for a layout defined in profile_activity.xml , the generated Binding class would be named ProfileActivityBinding .

You create an instance of a Binding class using DataBindingUtil , and use its setContentView method in place of the Activity’s setContentView :

ProfileActivityBinding binding =
    DataBindingUtil.setContentView(this, R.layout.profile_activity); 

For inflating the View associated with a Fragment or Recycler View item, you would use the Binding class’s inflate method:

ProfileActivityBinding binding =
    ProfileActivityBinding.inflate(layoutInflater, viewGroup, false); 

Alternatively, you can create a Data Binding class from an existing View:

ProfileActivityBinding binding =
    (ProfileActivityBinding) DataBindingUtil.bind(view); 

The Binding class automatically calls findViewById on each View with an ID within the associated layout, so instead of keeping a reference to every View in your layout or having to call findViewById yourself, you can reference the View through the Binding class:

binding.userName.setText("professionalandroid");
binding.email.setText("example@example.com"); 

Variables in Data Binding

The power of this fully operational Data Binding is its ability to simplify the process of dynamically binding your underlying data to the layout. You do this by adding a <data> element and declaring variables that can be used within the layout using the @{name.classvariable} syntax as shown in Listing 5-7 .

By declaring a variable named user , of the class User , our Binding class will generate a setUser method.

Calling this method will set all of the properties referencing that class using the @{} syntax. Data Binding will look for public variables, getter methods of the style get<Variable> or is<Variable> (for example, getEmail or isValid ), or the exact method name when resolving expressions:

User user = new User("professionalandroid", "example@example.com");
binding.setUser(user); 

This allows you to keep all of the View-specific logic in the layout file itself while your code can focus on only providing the appropriate data to the Binding class.

You’ll note that the android:id attributes were removed in the preceding example because Data Binding does not require IDs to evaluate variable expressions.

In addition to specifying variables, you can use almost all Java language syntax within these expressions. For example, you can use the null-coalescing operator ?? to shorten simple ternary expressions:

android:text='@{user.email ?? "No email"}' 

By default, any variables binding you apply is done after the next frame redraw. This can cause a visible flicker when used in scrollable views such as Recycler View. To avoid this, call executePendingBindings after setting your variables, causing the binding to be done immediately:

User user = userList.get(position);
binding.setUser(user);
binding.executePendingBindings(); 

Data Binding for the Earthquake Viewer Application

Data Binding enables us to simplify the Earthquake Viewer’s RecyclerView.Adapter by binding each Earthquake to the layout for each row:

1. Update the build.gradle file to enable data binding:

   android {
     [… Existing android element …]
     dataBinding.enabled = true
   }
   
   dependencies {
     [… Existing dependencies element …]
     implementation 'com.android.support:support-v4:27.1.1'
   } 

2. Update the list_item_earthquake.xml layout resource to take advantage of Data Binding:

   <?xml version="1.0" encoding="utf-8"?>
   <layout
     xmlns_android="http://schemas.android.com/apk/res/android"
     xmlns_app="http://schemas.android.com/apk/res-auto">
     <data>
       <variable name="timeformat" type="java.text.DateFormat" />
       <variable name="magnitudeformat" type="java.text.NumberFormat" />
       <variable name="earthquake"
         type="com.professionalandroid.apps.earthquake.Earthquake" />
    </data>
     <android.support.constraint.ConstraintLayout
       android:layout_width="match_parent"
       android:layout_height="wrap_content"
       android:paddingLeft="@dimen/activity_vertical_margin"
       android:paddingRight="@dimen/activity_vertical_margin">
       <TextView
         android:id="@+id/magnitude"
         android:layout_width="wrap_content"
         android:layout_height="0dp"
         android:gravity="center_vertical"
         app:layout_constraintRight_toRightOf="parent"
         app:layout_constraintTop_toTopOf="parent"
         app:layout_constraintBottom_toBottomOf="parent"
         android:textAppearance="?attr/textAppearanceListItem"
         android:text="@{magnitudeformat.format(earthquake.magnitude)}"/>
       <TextView
         android:id="@+id/date"
         android:layout_width="0dp"
         android:layout_height="wrap_content"
         android:layout_marginTop="@dimen/text_margin"
         app:layout_constraintLeft_toLeftOf="parent"
         app:layout_constraintTop_toTopOf="parent"
         app:layout_constraintRight_toLeftOf="@id/magnitude"
         android:text="@{timeformat.format(earthquake.date)}"/>
       <TextView
         android:layout_width="0dp"
         android:layout_height="wrap_content"
         android:layout_marginBottom="@dimen/text_margin"
         app:layout_constraintLeft_toLeftOf="parent"
         app:layout_constraintBottom_toBottomOf="parent"
         app:layout_constraintRight_toLeftOf="@id/magnitude"
         app:layout_constraintTop_toBottomOf="@id/date"
         android:text="@{earthquake.details}"/>
     </android.support.constraint.ConstraintLayout>
   </layout> 

3. Generate the Binding class by rebuilding the project. You can trigger this manually via the Build Make Project menu item.
4. Update the EarthquakeRecyclerViewAdapter.ViewHolder to receive the Binding class as the input and do the one-time initialization of setting the time and magnitude format variables:

   public static class ViewHolder extends RecyclerView.ViewHolder {
    public final ListItemEarthquakeBinding binding;
   
    public ViewHolder(ListItemEarthquakeBinding binding) {
     super(binding.getRoot());
     this.binding = binding;
     binding.setTimeformat(TIME_FORMAT);
     binding.setMagnitudeformat(MAGNITUDE_FORMAT);
    }
   } 

5. Update the EarthquakeRecyclerViewAdapter to create the Binding class in onCreateViewHolder and simplify onBindViewHolder :

   @Override
   public ViewHolder onCreateViewHolder(ViewGroup parent, int viewType) {
    ListItemEarthquakeBinding binding = ListItemEarthquakeBinding.inflate(
       LayoutInflater.from(parent.getContext()), parent, false);
    return new ViewHolder(binding);
   }
   
   @Override
   public void onBindViewHolder(ViewHolder holder, int position) {
     Earthquake earthquake = mEarthquakes.get(position);
     holder.binding.setEarthquake(earthquake);
     holder.binding.executePendingBindings();
   } 

Modifying Existing Views

The Android widget toolbox includes Views that provide many common UI requirements, but the controls are necessarily generic. By customizing these basic Views, you avoid re-implementing existing behavior while still tailoring the UI, and functionality, to your application’s needs.

To create a new View based on an existing control, create a new class that extends it, as shown with the TextView derived class shown in Listing 5-8 . In this example you extend the Text View to customize its appearance and behavior.

If you are building a reusable View, it is strongly recommended to override all three of these constructors to ensure that your View can be created in code and inflated in XML files just like all of the Views included in the Android SDK.

To override the appearance or behavior of your new View, override and extend the event handlers associated with the behavior you want to change.

In the following extension of the Listing 5-8 code, the onDraw method is overridden to modify the View’s appearance, and the onKeyDown handler is overridden to allow custom key-press handling:

public class MyTextView extends TextView {

  public MyTextView(Context context) {
    this(context, null);
  }

  public MyTextView(Context context, AttributeSet attrs) {
    this(context, attrs, 0);
  }

  public MyTextView(Context context, AttributeSet attrs, int defStyleAttr) {
    super(context, attrs, defStyleAttr);
  }

 @Override
 public void onDraw(Canvas canvas) {
  [ … Draw things on the canvas under the text … ]

    // Render the text as usual using the TextView base class.
  super.onDraw(canvas);

    [ … Draw things on the canvas over the text … ]
 }

  @Override
 public boolean onKeyDown(int keyCode, KeyEvent keyEvent) {
  [ … Perform some special processing … ]
  [ … based on a particular key press … ]

    // Use the existing functionality implemented by
  // the base class to respond to a key press event.
  return super.onKeyDown(keyCode, keyEvent);
 }
} 

The event handlers available within Views are covered in more detail later in this chapter.

public class PriceTextView extends TextView {
  private static NumberFormat CURRENCY_FORMAT =
    NumberFormat.getCurrencyInstance();

  private float mPrice;

  // These three constructors are required for all Views
  public PriceTextView(Context context) {
    this(context, null);
  }

  public PriceTextView(Context context, AttributeSet attrs) {
    this(context, attrs, 0);
  }

  // Constructor used when inflating the View from XML when it has a
  // style attribute
  public MyTextView(Context context, AttributeSet attrs, int defStyleAttr) {
    super(context, attrs, defStyleAttr);
  }

  public void setPrice(float price) {
    mPrice = price;
    setText(CURRENCY_FORMAT.format(price));
  }

  public float getPrice() {
    return mPrice;
  }
} 

<resources>
  <declare-styleable name="PriceTextView">
    <attr name="price" format="reference|float" />
  </declare-styleable>
</resources> 

<PriceTextView
    xmlns_android:"http://schemas.android.com/apk/res/android"
    xmlns_app="http://schemas.android.com/apk/res-auto"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    app:price="1999.99" /> 

// Constructor used when inflating the View from XML when it has a
// style attribute
public MyTextView(Context context, AttributeSet attrs, int defStyleAttr) {
  super(context, attrs, defStyleAttr);
  
  final TypedArray a = context.obtainStyledAttributes(attrs,
    R.styleable.PriceTextView, // The <declare-styleable> name
    defStyleAttr,
    0); // An optional R.style to use for default values

  if (a.hasValue(R.styleable.PriceTextView_price)) {
    setPrice(a.getFloat(R.styleable.PriceTextView_price,
    0)); // default value
  }
  a.recycle();
} 

Creating Compound Controls

Compound controls are atomic, self-contained View Groups that contain multiple child Views laid out and connected together.

When you create a compound control, you define the layout, appearance, and interaction of the Views it contains. You create compound controls by extending a ViewGroup (usually a layout). To create a new compound control, choose the layout class that’s most suitable for positioning the child controls and extend it:

public class MyCompoundView extends LinearLayout {
  public MyCompoundView(Context context) {
    this(context, null);
  }

  public MyCompoundView(Context context, AttributeSet attrs) {
    this(context, attrs, 0);
  }

  public MyCompoundView(Context context, AttributeSet attrs,
                        int defStyleAttr) {
    super(context, attrs, defStyleAttr);
  }
} 

As with Activities, the preferred way to design compound View UI layouts is by using an external resource.

Listing 5-9 shows the XML layout definition for a simple compound control consisting of an Edit Text for text entry, with a “Clear” Button beneath it.

To use this layout in your new compound View, override its constructor to inflate the layout resource using the inflate method from the LayoutInflate system service. The inflate method takes the layout resource and returns the inflated View.

For circumstances such as this, in which the returned View should be the class you’re creating, you can pass in the parent View and attach the result to it automatically.

Listing 5-10 demonstrates this using the ClearableEditText class. Within the constructor it inflates the layout resource from Listing 5-9 and then finds a reference to the Edit Text and Button Views it contains. It also makes a call to hookupButton that will later be used to hook up the plumbing that will implement the clear text functionality.

If you prefer to construct your layout in code, you can do so just as you would for an Activity:

public ClearableEditText(Context context, AttributeSet attrs,
                         int defStyleAttr) {
  super(context, attrs, defStyleAttr);

  // Set orientation of layout to vertical
  setOrientation(LinearLayout.VERTICAL);

  // Create the child controls.
  editText = new EditText(getContext());
  clearButton = new Button(getContext());
  clearButton.setText("Clear");

  // Lay them out in the compound control.
  int lHeight = LinearLayout.LayoutParams.WRAP_CONTENT;
  int lWidth = LinearLayout.LayoutParams.MATCH_PARENT;

   addView(editText, new LinearLayout.LayoutParams(lWidth, lHeight));
  addView(clearButton, new LinearLayout.LayoutParams(lWidth, lHeight));

  // Hook up the functionality
  hookupButton();
} 

After constructing the View layout, you can hook up the event handlers for each child control to provide the functionality you need. In Listing 5-11 , the hookupButton method is filled in to clear the Edit Text when the button is pressed.

Creating Simple Compound Controls as a Layout

It’s often sufficient, and more flexible, to define the layout and appearance of a set of Views without hard-wiring their interactions.

You can create a reusable layout by creating an XML resource that encapsulates the UI pattern you want to reuse. You can then import these layout patterns when creating the UI for Activities or Fragments by using the include tag within their layout resource definitions:

<include layout="@layout/clearable_edit_text"/> 

The include tag also enables you to override the id and layout parameters of the root node of the included layout:

<include 
  layout="@layout/clearable_edit_text"
  android:id="@+id/add_new_entry_input"
  android:layout_width="match_parent"
  android:layout_height="wrap_content"
  android:layout_gravity="top"
/> 

Creating Custom Views

Creating new Views gives you the power to fundamentally shape the way your applications look and feel. By creating your own controls, you can create UIs that are uniquely suited to your needs.

To create new controls from a blank canvas, you extend either the View or SurfaceView class. The View class provides a Canvas object with a series of draw methods and Paint classes. Use them to create a visual interface with bitmaps and raster graphics. You can then override user events, including screen touches or key presses to provide interactivity.

In situations in which extremely rapid repaints and 3D graphics aren’t required, the View base class offers a powerful lightweight solution.

The SurfaceView class provides a Surface object that supports drawing from a background thread and optionally using OpenGL to implement your graphics. This is an excellent option for graphics-heavy controls that are frequently updated (such as live video) or that display complex graphical information (particularly, games and 3D visualizations).

@Override
protected void onMeasure(int widthMeasureSpec, int heightMeasureSpec) {

  int measuredHeight = measureHeight(heightMeasureSpec);
  int measuredWidth = measureWidth(widthMeasureSpec);

  setMeasuredDimension(measuredHeight, measuredWidth);
}

private int measureHeight(int measureSpec) {
  // Return measured widget height.
}

private int measureWidth(int measureSpec) {
  // Return measured widget width.
} 

int specMode = MeasureSpec.getMode(measureSpec);
int specSize = MeasureSpec.getSize(measureSpec); 

Creating a Compass View Example

In the following example you’ll create a new Compass View by extending the View class. This View will display a traditional compass rose to indicate a heading/orientation. When complete, it should appear as in Figure 5-5 .

A compass is an example of a UI control that requires a radically different visual display from the Text Views and Buttons available in the SDK toolbox, making it an excellent candidate for building from scratch.

Start by creating a new Compass project that will contain your new CompassView , and create an initially empty CompassActivity within which to display it:

1. Create a new CompassView class that extends View and add constructors that will allow the View to be instantiated, either in code or through inflation from a resource layout. Add setFocusable(true) to the final constructor to allow a user using a D-pad to select and focus the compass (this will allow them to receive accessibility events from the View):

   package com.professionalandroid.apps.compass;
   
   import android.content.Context;
   import android.content.res.Resources;
   import android.content.res.TypedArray;
   import android.graphics.Canvas;
   import android.graphics.Paint;
   import android.support.v4.content.ContextCompat;
   import android.util.AttributeSet;
   import android.view.View;
   import android.view.accessibility.AccessibilityEvent;
   
   public class CompassView extends View {
     public CompassView(Context context) {
       this(context, null);
     }
   
     public CompassView(Context context, AttributeSet attrs) {
       this(context, attrs, 0);
     }
   
     public CompassView(Context context, AttributeSet attrs, int defStyleAttr) {
       super(context, attrs, defStyleAttr);
   
       setFocusable(true);
     }
   } 

2. The Compass View should always be a perfect circle that takes up as much of the canvas as this restriction allows. Override the onMeasure method to calculate the length of the shortest side, and use setMeasuredDimension to set the height and width using this value:

   @Override
   protected void onMeasure(int widthMeasureSpec, int heightMeasureSpec) {
     // The compass is a circle that fills as much space as possible.
     // Set the measured dimensions by figuring out the shortest boundary,
     // height or width.
     int measuredWidth = measure(widthMeasureSpec);
     int measuredHeight = measure(heightMeasureSpec);
   
     int d = Math.min(measuredWidth, measuredHeight);
   
     setMeasuredDimension(d, d);
   }
   
   private int measure(int measureSpec) {
     int result = 0;
   
     // Decode the measurement specifications.
     int specMode = MeasureSpec.getMode(measureSpec);
     int specSize = MeasureSpec.getSize(measureSpec);
   
     if (specMode == MeasureSpec.UNSPECIFIED) {
       // Return a default size of 200 if no bounds are specified.
       result = 200;
     } else {
       // As you want to fill the available space
       // always return the full available bounds.
       result = specSize;
     }
     return result;
   }
    

3. Modify the activity_compass.xml layout resource and replace it with a Frame Layout containing your new CompassView :

   <?xml version="1.0" encoding="utf-8"?>
   <FrameLayout xmlns_android="http://schemas.android.com/apk/res/android"
     android:orientation="vertical"
     android:layout_width="match_parent"
     android:layout_height="match_parent">
     <com.professionalandroid.apps.compass.CompassView
      android:id="@+id/compassView"
      android:layout_width="match_parent"
      android:layout_height="match_parent"
    />
   </FrameLayout>
    

4. Use resource files to store the colors and text strings you’ll use to draw the compass.
   1. 4.1. Create the text string resources by replacing the res/values/strings.xml file with the following:

      <?xml version="1.0" encoding="utf-8"?>
      <resources>
        <string name="app_name">Compass</string>
        <string name="cardinal_north">N</string>
        <string name="cardinal_east">E</string>
        <string name="cardinal_south">S</string>
        <string name="cardinal_west">W</string>
      </resources> 

   2. 4.2. Add the following color resources to res/values/colors.xml :

      <?xml version="1.0" encoding="utf-8"?>
      <resources>
      
        <color name="colorPrimary">#3F51B5</color>
        <color name="colorPrimaryDark">#303F9F</color>
        <color name="colorAccent">#FF4081</color>
        <color name="background_color">#F555</color>
        <color name="marker_color">#AFFF</color>
        <color name="text_color">#AFFF</color>
      </resources> 

5. Return to the CompassView class. Add a new property to store the displayed bearing, and create get and set methods for it. Call invalidate in the set method to ensure that the View is repainted when the bearing changes:

   private float mBearing;
   
   public void setBearing(float bearing) {
     mBearing = bearing;
     invalidate();
   }
   
   public float getBearing() {
     return mBearing;
   } 

6. Create a custom attribute for setting the bearing in XML.
   1. 6.1. Create the custom attribute in the res/values/attrs.xml file:

      <?xml version="1.0" encoding="utf-8"?>
      <resources>
        <declare-styleable name="CompassView">
          <attr name="bearing" format="reference|float" />
        </declare-styleable>
      </resources> 

   2. 6.2. Update the constructor to read the bearing from the XML attribute:

      public CompassView(Context context, AttributeSet attrs, 
                         int defStyleAttr) {
        super(context, attrs, defStyleAttr);
        setFocusable(true);
        final TypedArray a = context.obtainStyledAttributes(attrs,
          R.styleable.CompassView, defStyleAttr, 0);
        if (a.hasValue(R.styleable.CompassView_bearing)) {
          setBearing(a.getFloat(R.styleable.CompassView_bearing, 0));
        }
        a.recycle();
      } 

7. In the constructor, get references to each resource created in Step 4. Store the string values as instance variables, and use the color values to create new class-scoped Paint objects. You’ll use these objects in the next step to draw the compass face.

   private Paint markerPaint;
   private Paint textPaint;
   private Paint circlePaint;
   private String northString;
   private String eastString;
   private String southString;
   private String westString;
   private int textHeight;
   
   public CompassView(Context context, AttributeSet attrs, int defStyleAttr) {
     super(context, attrs, defStyleAttr);
   
     setFocusable(true);
     final TypedArray a = context.obtainStyledAttributes(attrs,
       R.styleable.CompassView, defStyleAttr, 0);
     if (a.hasValue(R.styleable.CompassView_bearing)) {
       setBearing(a.getFloat(R.styleable.CompassView_bearing, 0));
     }
     a.recycle();
   
    Context c = this.getContext();
    Resources r = this.getResources();
   
    circlePaint = new Paint(Paint.ANTI_ALIAS_FLAG);
    circlePaint.setColor(ContextCompat.getColor(c, R.color.background_color));
    circlePaint.setStrokeWidth(1);
    circlePaint.setStyle(Paint.Style.FILL_AND_STROKE);
   
    northString = r.getString(R.string.cardinal_north);
    eastString = r.getString(R.string.cardinal_east);
    southString = r.getString(R.string.cardinal_south);
    westString = r.getString(R.string.cardinal_west);
   
    textPaint = new Paint(Paint.ANTI_ALIAS_FLAG);
    textPaint.setColor(ContextCompat.getColor(c, R.color.text_color));
   
    textHeight = (int)textPaint.measureText("yY");
   
    markerPaint = new Paint(Paint.ANTI_ALIAS_FLAG);
    markerPaint.setColor(ContextCompat.getColor(c, R.color.marker_color));
   } 

8. The next step is to draw the compass face using the String and Paint objects you created in Step 7. The following code snippet is presented with only limited commentary. You can find more detail about drawing on the Canvas and using advanced Paint effects in Chapter 14 .
   1. 8.1. Start by overriding the onDraw method in the CompassView class:

      @Override
      protected void onDraw(Canvas canvas) { 

   2. 8.2. Find the center of the control, and store the length of the smallest side as the Compass’s radius:

        int mMeasuredWidth = getMeasuredWidth();
        int mMeasuredHeight = getMeasuredHeight();
      
        int px = mMeasuredWidth / 2;
        int py = mMeasuredHeight / 2 ;
      
        int radius = Math.min(px, py); 

   3. 8.3. Draw the outer boundary, and color the background of the Compass face using the drawCircle method. Use the circlePaint object you created in Step 7:

         // Draw the background
        canvas.drawCircle(px, py, radius, circlePaint); 

      1. 8.4. This Compass displays the current heading by rotating the face so that the current direction is always at the top of the device. To achieve this, rotate the canvas in the opposite direction to the current heading:

        // Rotate our perspective so that the 'top' is
        // facing the current bearing.
        canvas.save();
        canvas.rotate(-mBearing, px, py); 

   4. 8.5. All that’s left is to draw the markings. Rotate the canvas through a full rotation, drawing markings every 15 degrees and the abbreviated direction string every 45 degrees:

        int textWidth = (int)textPaint.measureText("W");
        int cardinalX = px-textWidth/2;
        int cardinalY = py-radius+textHeight;
      
        // Draw the marker every 15 degrees and text every 45.
        for (int i = 0; i < 24; i++) {
          // Draw a marker.
          canvas.drawLine(px, py-radius, px, py-radius+10, markerPaint);
      
          canvas.save();
          canvas.translate(0, textHeight);
      
          // Draw the cardinal points
          if (i % 6 == 0) {
            String dirString = "";
            switch (i) {
              case(0)  : {
                           dirString = northString;
                           int arrowY = 2*textHeight;
                           canvas.drawLine(px, arrowY, px-5, 3*textHeight,
                                           markerPaint);
                           canvas.drawLine(px, arrowY, px+5, 3*textHeight,
                                           markerPaint);
                           break;
                         }
              case(6)  : dirString = eastString; break;
              case(12) : dirString = southString; break;
              case(18) : dirString = westString; break;
            }
            canvas.drawText(dirString, cardinalX, cardinalY, textPaint);
          }
      
          else if (i % 3 == 0) {
            // Draw the text every alternate 45deg
            String angle = String.valueOf(i*15);
            float angleTextWidth = textPaint.measureText(angle);
      
            int angleTextX = (int)(px-angleTextWidth/2);
            int angleTextY = py-radius+textHeight;
            canvas.drawText(angle, angleTextX, angleTextY, textPaint);
          }
          canvas.restore();
      
          canvas.rotate(15, px, py);
        }
        canvas.restore();
      } 

9. The next step is to add accessibility support. The Compass View presents a heading visually, so to make it accessible you need to broadcast an Accessibility Event signifying that the “text” (in this case, content) has changed when the bearing changes. Do this by modifying the setBearing method:

    public void setBearing(float bearing) {
     mBearing = bearing;
     invalidate();
    sendAccessibilityEvent(AccessibilityEvent.TYPE_VIEW_TEXT_CHANGED);
   } 

10. Override the dispatchPopulateAccessibilityEvent to use the current heading as the content value to be used for accessibility events:

    @Override
    public boolean dispatchPopulateAccessibilityEvent(
                     final AccessibilityEvent event) {
      super.dispatchPopulateAccessibilityEvent(event);
      if (isShown()) {
        String bearingStr = String.valueOf(mBearing);
        event.getText().add(bearingStr);
        return true;
      }
      else
        return false;
    } 

Run the Activity, and you should see the CompassView displayed. See Chapter 16 , “Hardware Sensors,” to learn how to bind the CompassView to the device’s compass sensor.

Using Custom Controls

Having created your own custom Views, you can use them within code and layouts as you would any other View. Note that you must specify the fully qualified class name when you add a node for your new View in the layout definition:

<com.professionalandroid.apps.compass.CompassView
  android:id="@+id/compassView"
  android:layout_width="match_parent"
  android:layout_height="match_parent"
  app:bearing="45" /> 

You can inflate the layout and get a reference to the CompassView , as usual, using the following code:

@Override
public void onCreate(Bundle savedInstanceState) {
 super.onCreate(savedInstanceState);
 setContentView(R.layout.main);
 CompassView cv = findViewById(R.id.compassView);
  // Update the bearing by calling setBearing as needed
} 

You can also add your new View to a layout in code:

@Override
public void onCreate(Bundle savedInstanceState) {
 super.onCreate(savedInstanceState);
 CompassView cv = new CompassView(this);
 setContentView(cv);
 cv.setBearing(45);
} 

Custom Views are a powerful way to provide distinct functionality to your application. Once created, they can be used in the same way as any Android framework View.

Explicitly Starting New Activities

You learned in Chapter 3 , “Applications and Activities and Fragments, Oh My!” that applications consist of a number of interrelated screens—Activities—that must be included in the application manifest.

To transition between them, you can explicitly indicate an Activity to start by creating a new Intent, specifying the current Activity’s Context and the class of the Activity to launch. Once defined, pass this Intent into startActivity as shown in Listing 6-1 to launch the new Activity.

After startActivity is called, the new Activity (in this example, MyOtherActivity ) will be created, started, and resumed—replacing MyActivity at the top of the Activity stack.

Calling finish on the new Activity, or pressing the hardware back button, closes it and removes it from the stack. Alternatively, you can continue to navigate to other Activities using startActivity .

Note that each time you call startActivity , a new Activity will be added to the stack. Pressing back (or calling finish ) will remove each of these Activities, in turn; if an Activity is not closed in this way it will remain on the stack while the application is running. As a result, it’s possible to have multiple instances of the same Activity on your Activity stack.

Implicit Intents and Late Runtime Binding

An implicit Intent is used to ask the system to find and start an Activity that can perform a particular action , without you knowing exactly which application, or Activity, will be started.

For example, to let users make calls from your application, you could implement a new dialer, or (if you don’t hate yourself), you could use an implicit Intent that requests the action (dialing) be performed on a phone number (represented as a URI):

if (somethingWeird && itDontLookGood) {
 Intent intent =
  new Intent(Intent.ACTION_DIAL, Uri.parse("tel:555-2368"));

  startActivity(intent);
} 

Android resolves this Intent by finding, and then starting, an Activity that can perform the dial action on a telephone number URI—in this case, typically the bundled phone dialer application.

When constructing a new implicit Intent, you specify an action to perform and the URI of the data on which to perform that action. You can send additional data to the target Activity by adding extras to the Intent.

Extras are a mechanism used to attach primitive values to an Intent. You can use the overloaded putExtra method on any Intent to attach a new name/value pair (NVP):

intent.putExtra("STRING_EXTRA", "Beverly Hills");
intent.putExtra("INT_EXTRA", 90210); 

The extras are stored within the Intent as a Bundle object, available from within the started Activity using the getExtras method. You can extract each extra value directly from the Intent using the corresponding get[type]Extra method:

Intent intent = getIntent();
String myStringExtra = intent.getStringExtra("STRING_EXTRA");
int myIntExtra = intent.getIntExtra("INT_EXTRA", DEFAULT_INT_VALUE); 

When you use an implicit Intent to start an Activity, Android will—at run time—resolve it into the Activity class best suited to performing the required action on the type of data specified. This means you can create projects that use functionality from other applications without knowing exactly which application you’re borrowing functionality from ahead of time.

In circumstances where multiple Activities can potentially perform a given action, the user is presented with a choice. The process of Intent resolution is determined through an analysis of the Activities’ Intent Filters, which are described in detail later in this chapter.

Various native applications provide Activities capable of performing actions against specific data. Third-party applications, including your own, can be registered to support new actions or to provide an alternative provider of native actions. You are introduced to some of the native actions, as well as how to register your own Activities to support them, later in this chapter.

Determining If an Intent Will Resolve

Incorporating the Activities and Services of a third-party application into your own is incredibly powerful; however, there is no guarantee that any particular application will be installed on a device, or even that any installed application is capable of handling your request.

As a result, it’s good practice to check if your implicit Intent will resolve to an Activity before passing it to startActivity .

You can use the Package Manager to query which, if any, Activity will be launched in response to a specific Intent by calling resolveActivity on your Intent object, passing in the Package Manager, as shown in Listing 6-2 .

If no Activity is found, you can choose to either disable the related functionality (and associated user interface controls) or direct users to an appropriate application in the Google Play Store. Note that Google Play is not available on all devices, so it’s good practice to check for that as well.

Returning Results from Activities

An Activity started via startActivity is independent of the calling Activity, and will not provide any feedback when it closes.

Where feedback is required, you can start an Activity as a sub-Activity that can pass results back to its parent. Sub-Activities are really just Activities opened in a different way; as such, you must still register them in the application manifest in the same way as any other Activity.

Any manifest-registered Activity can be opened as a sub-Activity, including those provided by the system or third-party applications.

When a sub-Activity is finished, it triggers the onActivityResult event handler within the calling parent Activity. Sub-Activities are particularly useful in situations where one Activity is providing data input for another, such as a user filling in a form or selecting an item from a list.

Using Platform-Native Actions to Launch Activities

Applications distributed as part of the Android platform also use Intents to launch Activities and sub-Activities.

The following (non-comprehensive) list shows some of the native actions available as static string constants in the Intent class. When creating implicit Intents, you can use these actions, known as Activity Intents , to start Activities and sub-Activities within your own applications.

• ACTION_DELETE —Starts an Activity that lets you delete the data specified at the Intent’s data URI.
• ACTION_DIAL —Brings up a dialer application with the number to dial pre-populated from the Intent’s data URI. By default, this is handled by the native Android phone dialer. The dialer can normalize most number schemas—for example, tel:555-1234 and tel:(212) 555 1212 are both valid numbers.
• ACTION_EDIT —Requests an Activity that can edit the data at the Intent’s data URI.
• ACTION_INSERT —Opens an Activity capable of inserting new items into the Cursor specified in the Intent’s data URI. When called as a sub-Activity, it should return a URI to the newly inserted item.
• ACTION_PICK —Launches a sub-Activity that lets you pick an item from the Content Provider specified by the Intent’s data URI. When closed, it should return a URI to the item that was picked. The Activity launched depends on the data being picked—for example, passing content://contacts/people will invoke the native contacts list.
• ACTION_SEARCH —Typically used to launch a specific search Activity. When it’s fired without a specific Activity, the user will be prompted to select from all applications that support search. Supply the search term as a string in the Intent’s extras using SearchManager.QUERY as the key.
• ACTION_SENDTO —Launches an Activity to send data to the contact specified by the Intent’s data URI.
• ACTION_SEND —Launches an Activity that sends the data specified in the Intent. The recipient contact needs to be selected by the resolved Activity. Use setType to set the MIME type of the transmitted data. The data itself should be stored as an extra by means of the key EXTRA_TEXT or EXTRA_STREAM , depending on the type. In the case of email, the native Android applications will also accept extras via the EXTRA_EMAIL , EXTRA_CC , EXTRA_BCC , and EXTRA_SUBJECT keys. Use the ACTION_SEND action only to send data to a remote recipient (not to another application on the device).
• ACTION_VIEW —This is the most common generic action. View asks that the data supplied in the Intent’s data URI be viewed in the most reasonable manner. Different applications will handle view requests depending on the URI schema of the data supplied. Natively http: addresses will open in the browser; tel: addresses will open the dialer to call the number; geo: addresses will be displayed in the Google Maps application; and contact content will be displayed in the Contact Manager.
• ACTION_WEB_SEARCH —Opens the Browser to perform a web search based on the query supplied using the SearchManager.QUERY key.

Defining an Intent Filter

Using Intent Filters, Activities can declare the actions and data they are able to support.

To register an Activity as a potential Intent handler, add an intent-filter tag to its manifest node using the following tags (and associated attributes):

• action —Uses the android:name attribute to specify the name of the action that can be performed. Each Intent Filter must have at least one action tag, and actions should be unique strings that are self-describing. You can define your own actions (best practice is to use a naming system based on the Java package naming conventions) or use one of the system actions provided by Android.
• category —Uses the android:name attribute to specify under which circumstances the action can be performed. Each Intent Filter tag can include multiple category tags. You can specify your own categories or use one of the standard values provided by Android.
• data —The data tag enables you to specify which data types your component can act on; you can include several data tags as appropriate. You can use any combination of the following attributes to specify the data your component supports:
  • android:host —Specifies a valid hostname (for example, google.com ).
  • android:mimetype —Specifies the type of data your component is capable of handling. For example, vnd.android.cursor.dir/* would match any Android cursor.
  • android:path —Specifies valid path values for the URI (for example, /transport/boats/ ).
  • android:port —Specifies valid ports for the specified host.
  • android:scheme —Requires a particular scheme (for example, content or http ).

The following snippet shows an Intent Filter for an Activity that can perform the SHOW_DAMAGE action as either a primary or an alternative action based on its Earthquake cursor mime type:

<intent-filter>
  <action
    android:name="com.paad.earthquake.intent.action.SHOW_DAMAGE"/>
  <category
    android:name="android.intent.category.DEFAULT"/>
  <category
    android:name="android.intent.category.SELECTED_ALTERNATIVE"/>
  <data android:mimeType=
    "vnd.android.cursor.item/vnd.com.professionalandroid.provider.earthquake"
  />
</intent-filter> 

You may have noticed that clicking a link to a YouTube video or Google Maps location on an Android device prompts you to use YouTube or Google Maps, respectively, rather than a web browser. This is achieved by specifying the scheme, host, and path attributes within the data tag of an Intent Filter, as shown in Listing 6-7 . In this example, any link of the form that begins http://blog.radioactiveyak.com can be serviced by this Activity.

Note that you must include the browsable category in order for links clicked within the browser to trigger this behavior.

@Override
public void onNewIntent(Intent newIntent) {
  // TODO React to the new Intent
  setIntent(newIntent);
  super.onNewIntent(newIntent);
} 

Selecting a Star Sign Example

In this example, you create a new Activity that services ACTION_PICK for a list of star signs. The picker application displays a list of star signs, and lets the user select one before closing and returning the selected sign to the calling Activity.

1. Create a new StarSignPicker project that includes a StarSignPicker Activity based on the Empty Activity template and using the App Compatibility library. Add an EXTRA_SIGN_NAME string constant that will be used to store an extra in our return Intent to indicate the star sign selected by user:

   public class StarSignPicker extends AppCompatActivity {
   
     public static final String EXTRA_SIGN_NAME = "SIGN_NAME";
     
     @Override
     protected void onCreate(Bundle savedInstanceState) {
       super.onCreate(savedInstanceState);
       setContentView(R.layout.activity_star_sign_picker);
     }
   } 

2. Modify the activity_star_sign_picker.xml layout resource to include a single RecyclerView control. This control will be used to display the contacts:

   <?xml version="1.0" encoding="utf-8"?>
   <android.support.v7.widget.RecyclerView
     xmlns_android="http://schemas.android.com/apk/res/android"
     xmlns_app="http://schemas.android.com/apk/res-auto"
     android:id="@+id/recycler_view"
     android:layout_width="match_parent"
     android:layout_height="match_parent"
     android:orientation="vertical"
     app:layoutManager="LinearLayoutManager"
   /> 

3. Create a new list_item_layout.xml layout resource based on a FrameLayout that includes a single TextView control. This control will be used to display each star sign in the Recycler View:

   <?xml version="1.0" encoding="utf-8"?>
   <FrameLayout xmlns_android="http://schemas.android.com/apk/res/android"
     android:layout_width="match_parent"
     android:layout_height="wrap_content">
     <TextView
       android:id="@+id/itemTextView"
       android:layout_width="match_parent"
       android:layout_height="wrap_content"
       android:layout_margin="8dp"
       android:textAppearance="?attr/textAppearanceListItem"/>
   </FrameLayout> 

4. Add the Recycler View library to your app module Gradle build file:

   dependencies {
     [… Existing dependencies …]
     implementation 'com.android.support:recyclerview-v7:27.1.1'
   } 

5. Create a new StarSignPickerAdapter class that extends RecyclerView.Adapter , and which contains a string array of star signs:

   public class StarSignPickerAdapter
     extends RecyclerView.Adapter<StarSignPickerAdapter.ViewHolder> {
   
     private String[] mStarSigns = {"Aries", "Taurus", "Gemini", "Cancer",
                                    "Leo", "Virgo", "Libra", "Scorpio",
                                    "Sagittarius", "Capricorn", "Aquarius", 
                                    "Pisces" };
   
     public StarSignPickerAdapter() {
     }
   
     @Override
     public int getItemCount() {
       return mStarSigns == null ? 0 : mStarSigns.length;
     }
   } 

   1. 5.1 Within the Adapter created in Step 5, create a new ViewHolder class that extends RecyclerView.ViewHolder and implements an OnClickListener . It should expose a TextView and an OnClickListener :

      
      public static class ViewHolder extends RecyclerView.ViewHolder
                                     implements View.OnClickListener {
        public TextView textView;
        public View.OnClickListener mListener;
      
        public ViewHolder(View v, View.OnClickListener listener) {
          super(v);
          mListener = listener;
          textView = v.findViewById(R.id.itemTextView);
          v.setOnClickListener(this);
        }
      
        @Override
        public void onClick(View v) {
          if (mListener != null)
            mListener.onClick(v);
        }
      } 

   2. 5.2 Still within the Adapter, override onCreateViewHolder using the ViewHolder created in Step 5.1, inflating the list_item_layout created in Step 3:

      @Override
      public StarSignPickerAdapter.ViewHolder
        onCreateViewHolder(ViewGroup parent, int viewType) {
        // Create the new View
        View v = LayoutInflater.from(parent.getContext())
                   .inflate(R.layout.list_item_layout, parent, false);
      
        return new ViewHolder(v, null);
      } 

   3. 5.3 Create a new Interface that contains an onItemClicked method that takes a String argument; add a setOnAdapterItemClick method to the Adapter to store a reference to this event handler. We will use this handler notify the parent Activity which list item has been selected:

      public interface IAdapterItemClick {
        void onItemClicked(String selectedItem);
      }
      
      IAdapterItemClick mAdapterItemClickListener;
      
      public void setOnAdapterItemClick(
        IAdapterItemClick adapterItemClickHandler) {
        mAdapterItemClickListener = adapterItemClickHandler;
      } 

   4. 5.4 Finally, override the Adapter’s onBindViewHolder method, assigning a star sign to the Text View defined in our View Holder. Take this opportunity to implement the onClickListener for each View Holder, which will call the IAdapterItemClick handler from Step 5.3 if an item in our list is clicked:

      @Override
      public void onBindViewHolder(ViewHolder holder, final int position) {
        holder.textView.setText(mStarSigns[position]);
        holder.mListener = new View.OnClickListener() {
          @Override
          public void onClick(View v) {
            if (mAdapterItemClickListener != null)
              mAdapterItemClickListener.onItemClicked(mStarSigns[position]);
          }
        };
      } 

6. Return to the StarSignPicker Activity and modify the onCreate method. It currently begins like this:

   @Override
   protected void onCreate(Bundle savedInstanceState) {
     super.onCreate(savedInstanceState);
     setContentView(R.layout.activity_starsign_picker);  

   1. 6.1 Now, still within onCreate , instantiate the StarSignPickerAdapter you created in Step 5:

      StarSignPickerAdapter adapter = new StarSignPickerAdapter(); 

   2. 6.2 Create a new IAdapterItemClick handler and assign it to the Adapter using the setOnAdapterItemClick method. When an item is clicked, create a new result Intent and use the EXTRA_SIGN_NAME string to assign an extra that contains the selected star sign. Assign the new Intent as this Activity’s result using setResult and call finish to close the Activity and return to the caller:

      adapter.setOnAdapterItemClick(
        new StarSignPickerAdapter.IAdapterItemClick() {
        @Override
        public void onItemClicked(String selectedItem) {
          // Construct the result URI.
          Intent outData = new Intent();
          outData.putExtra(EXTRA_SIGN_NAME, selectedItem);
          setResult(Activity.RESULT_OK, outData);
          finish();
        }
      }); 

   3. 6.3 Assign the adapter to the Recycler View using setAdapter :

      RecyclerView rv = findViewById(R.id.recycler_view);
      rv.setAdapter(adapter); 

   4. 6.4 Close off the onCreate method:

      } 

7. Modify the application manifest and replace the intent-filter tag of the Activity to add support for the ACTION_PICK action on star signs:

   <activity android:name=".StarSignPicker">
     <intent-filter>
       <action android:name="android.intent.action.PICK" />
       <category android:name="android.intent.category.DEFAULT"/>
       <data android:scheme="starsigns" />
     </intent-filter>
   </activity> 

8. This completes the sub-Activity. To test it, create a new test harness StarSignPickerTester launcher Activity with an activity_star_sign_picker_tester.xml layout file. Update the layout to include a TextView to display the selected star sign, and a Button to start the sub-Activity:

   <?xml version="1.0" encoding="utf-8"?>
   <LinearLayout xmlns_android="http://schemas.android.com/apk/res/android"
     android:orientation="vertical"
     android:layout_width="match_parent"
     android:layout_height="match_parent">
     <TextView
       android:id="@+id/selected_starsign_textview"
       android:layout_width="match_parent"
       android:layout_height="wrap_content"
       android:textAppearance="?attr/textAppearanceListItem"
       android:layout_margin="8dp"
     />
     <Button
       android:id="@+id/pick_starsign_button"
       android:layout_width="match_parent"
       android:layout_height="wrap_content"
       android:text="Pick Star Sign"
     />
   </LinearLayout> 

9. Override the onCreate method of the StarSignPickerTester to add a click listener to the Button so that it implicitly starts a new sub-Activity by specifying the ACTION_PICK and starsign as the data scheme:

   public class StarSignPickerTester extends AppCompatActivity {
   
     public static final int PICK_STARSIGN = 1;
   
     @Override
     public void onCreate(Bundle savedInstanceState) {
       super.onCreate(savedInstanceState);
       setContentView(R.layout.activity_star_sign_picker_tester);
   
       Button button = findViewById(R.id.pick_starsign_button);
   
       button.setOnClickListener(new View.OnClickListener() {
         @Override
         public void onClick(View _view) {
           Intent intent = new Intent(Intent.ACTION_PICK,
                                      Uri.parse("starsigns://"));
           startActivityForResult(intent, PICK_STARSIGN);
         }1
       });
     }
   } 

10. When the sub-Activity returns, use the result to populate the Text View with the selected star sign:

    @Override
    public void onActivityResult(int reqCode, int resCode, Intent data) {
      super.onActivityResult(reqCode, resCode, data);
    
      switch(reqCode) {
        case (PICK_STARSIGN) : {
          if (resCode == Activity.RESULT_OK) {
            String selectedSign =
              data.getStringExtra(StarSignPicker.EXTRA_SIGN_NAME);
            TextView tv = findViewById(R.id.selected_starsign_textview);
            tv.setText(selectedSign);
          }
          break;
        }
        default: break;
      }
    } 

When your test Activity is running, press the “pick star sign” button. The star sign picker Activity should appear, as shown in Figure 6-1 .

After you select

Figure 6-2 a star sign, the parent Activity should return to the foreground with the selection displayed (see Figure 6-2 ).

Using Intent Filters for Plug-Ins and Extensibility

Having used Intent Filters to declare the actions your Activities can perform on different types of data, it stands to reason that applications can also query to find which actions are available to be performed on a particular piece of data.

Android provides a plug-in model that lets your applications take advantage of functionality, provided anonymously from your own or third-party application components you haven’t yet conceived of, without your having to modify or recompile your projects.

Intent intent = new Intent();
intent.setData(MyProvider.CONTENT_URI);
intent.addCategory(Intent.CATEGORY_ALTERNATIVE); 

Intent intent = new Intent();
intent.setData(MyProvider.CONTENT_URI);
intent.addCategory(Intent.CATEGORY_ALTERNATIVE); 

Native Linkify Link Types

The Linkify class has presets that can detect and linkify web URLs, email addresses, map addresses, and phone numbers. To apply a preset, use the static Linkify.addLinks method, passing in a View to Linkify and a bitmask of one or more of the following self-describing Linkify class constants: WEB_URLS , EMAIL_ADDRESSES , PHONE_NUMBERS , MAP_ADDRESSES , and ALL .

TextView textView = findViewById(R.id.myTextView);
Linkify.addLinks(textView, Linkify.WEB_URLS|Linkify.EMAIL_ADDRESSES); 

You can also linkify Views directly within a layout using the android:autoLink attribute. It supports one or more of the following values: none , web , email , phone , map , and all .

<TextView
  android:layout_width="match_parent"
  android:layout_height="match_parent"
  android:text="@string/linkify_me"
 android:autoLink="phone|email"
/> 

Creating Custom Link Strings

To linkify your own data, you need to define your own linkify strings. Do this by creating a new RegEx pattern that matches the text you want to display as hyperlinks.

As with the native types, you can linkify the target Text View by calling Linkify.addLinks ; however, rather than passing in one of the preset constants, pass in your RegEx pattern. You can also pass in a prefix that will be prepended to the target URI when a link is clicked.

Listing 6-12 shows a View being linkified to support earthquake data provided by an Android Content Provider. Note that rather than include the entire schema, the specified RegEx matches any text that starts with “quake” and is followed by a number, with optional whitespace. The full schema is then prepended to the URI before the Intent is fired.

Note that in this example, including whitespace between “quake” and a number will return a match, but the resulting URI won’t be valid. You can implement and specify one or both of a TransformFilter and MatchFilter interface to resolve this problem. These interfaces, defined in detail in the following section, offer additional control over the target URI structure and the definition of matching strings, and are used as in the following skeleton code:

Linkify.addLinks(myTextView, p, baseUri,
         new MyMatchFilter(), new MyTransformFilter()); 

Using the Match Filter

To add additional conditions to RegEx pattern matches, implement the acceptMatch method in a Match Filter. When a potential match is found, acceptMatch is triggered, with the match start and end index (along with the full text being searched) passed in as parameters.

Listing 6-13 shows a MatchFilter implementation that cancels any match immediately preceded by an exclamation mark.

Using the Transform Filter

The Transform Filter lets you modify the implicit URI generated by matching link text. Decoupling the link text from the target URI gives you more freedom in how you display data strings to your users.

To use the Transform Filter, implement the transformUrl method in your Transform Filter. When Linkify finds a successful match, it calls transformUrl , passing in the RegEx pattern used and the matched text string (before the base URI is prepended). You can modify the matched string and return it such that it can be appended to the base string as the data for a View Intent.

As shown in Listing 6-14 , the TransformFilter implementation transforms the matched text into a lowercase URI, having also removed any whitespace characters.

Broadcasting Events with Intents

Within your application, construct the Intent you want to broadcast and use the sendBroadcast method to send it.

As with Intents used to start Activities, you can broadcast either an explicit or implicit Intent. Explicit Intents indicate the class of the Broadcast Receiver you want to trigger, whereas implicit Intents specify the action, data, and category of your Intent in a way that lets potential Broadcast Receivers accurately determine their interest.

Implicit Intent broadcasts are particularly useful where you have multiple Receivers that are potential targets for a broadcast.

For implicit Intents, the action string is used to identify the type of event being broadcast, so it should be a unique string that identifies the event type. By convention, action strings are constructed using the same form as Java package names:

public static final String NEW_LIFEFORM_ACTION =	
  "com.professionalandroid.alien.action.NEW_LIFEFORM_ACTION"; 

If you want to include data within the Intent, you can specify a URI using the Intent’s data property. You can also include extras to add additional primitive values. Considered in terms of an event-driven paradigm, the extras equate to optional parameters passed into an event handler.

Listing 6-15 shows the basic creation of explicit and implicit broadcast Intents, the latter using the action defined previously with additional event information stored as extras.

The explicit Intent will be received only by the MyBroadcastReceiver class indicated, whereas the implicit Intent could potentially be received by multiple Receivers.

Listening for Intent Broadcasts with Broadcast Receivers

Broadcast Receivers (commonly referred to as Receivers ) are used to listen for broadcast Intents. For a Receiver to receive broadcasts, it must be registered, either in code or within the application manifest—the latter case is referred to as a manifest Receiver .

To create a new Broadcast Receiver, extend the BroadcastReceiver class and override the onReceive event handler:

import android.content.BroadcastReceiver;
import android.content.Context;
import android.content.Intent;

public class MyBroadcastReceiver extends BroadcastReceiver {
  @Override
  public void onReceive(Context context, Intent intent) {
    //TODO: React to the Intent received.
  }
} 

When a broadcast Intent is started, the onReceive method will be executed on the main application Thread. Any non-trivial work should be performed asynchronously after calling goAsync —as described in Chapter 11 , “Working in the Background.”

In any case, all processing within the Broadcast Receiver must complete within 10 seconds or the system will consider it unresponsive, and attempt to terminate it.

To avoid this, Broadcast Receivers will typically schedule a background job or launch a bound Service to initiate potentially long-running tasks, or it can update the containing parent Activity UI or trigger a Notification to notify the user of received changes.

Listing 6-16 shows how to implement a Broadcast Receiver that extracts the data and several extras from the broadcast Intent and uses them to trigger a Notification. In the following sections you learn how to register it in code or in your application manifest.

Registering Broadcast Receivers in Code

Broadcast Receivers that respond to broadcasts sent from your own application, and those that alter the UI of an Activity, are typically registered dynamically in code. A Receiver registered programmatically can respond to broadcast Intents only when the application component it is registered within is running.

This is useful when the Receiver behavior is tightly bound to a particular component—for example, one that updates the UI elements of an Activity. In this case, it’s good practice to register the Receiver within the onStart handler and unregister it during onStop .

Listing 6-17 shows how to register and unregister a Broadcast Receiver in code using the IntentFilter class that defines an action associated with an implicit broadcast Intent the Receiver should respond to.

Registering Broadcast Receivers in Your Application Manifest

Broadcast Receivers registered statically in your application manifest are always active, and will receive Broadcast Intents even when your application has been killed or hasn’t been started; your application will be started automatically when a matching Intent is broadcast.

To include a Broadcast Receiver in the application manifest, add a receiver tag within the application node, specifying the class name of the Broadcast Receiver to register:

<receiver android:name=".LifeformDetectedReceiver"/> 

Prior to Android 8.0 Oreo (API Level 26), it was possible for manifest Receivers to include an intent-filter tag that specified an action to support listening for implicit broadcasts:

<receiver android:name=".LifeformDetectedReceiver">
  <intent-filter>
    <action android:name=
      "com.professionalandroid.alien.action.NEW_LIFEFORM_ACTION"
    />
  </intent-filter>
</receiver> 

Manifest Receivers let you create event-driven applications that will respond to broadcast events even after your application has been closed or killed—however, it also introduces associated resource use risks. If an Intent is broadcast frequently it could cause your application to wake repeatedly, potentially resulting in significant battery drain.

To minimize this risk, Android 8.0 no longer supports manifest Receivers for arbitrary implicit Intents.

Apps can continue to register for explicit broadcasts in their manifests, and you can register Receivers at runtime for any broadcast, both implicit or explicit—but only a limited number of broadcast system actions can be used to register an implicit Intent within your manifest. The supported actions are described later in this chapter in the section, “Monitoring Device State Changes through Broadcast Intents.”

Managing Manifest Receivers at Run Time

Using the Package Manager, you can enable and disable any of your application’s manifest Receivers at run time using the setComponentEnabledSetting method. You can use this technique to enable or disable any application component (including Activities and Services), but it is particularly useful for manifest Receivers.

To minimize the potential battery drain caused by your application, it’s good practice to disable manifest Receivers that listen for system events when your application doesn’t need to respond to those events.

Listing 6-18 shows how to enable and disable a manifest Receiver at run time.

Monitoring Device State Changes Through Broadcast Intents

Many of the system Services broadcast Intents to signal changes in device state. You can monitor these broadcasts to add functionality to your own projects based on events such as the completion of device booting, time-zone changes, changes in dock state, and battery status.

A comprehensive list of the broadcast actions used and transmitted natively by Android is available at developer.android.com/reference/android/content/Intent.html . Due to the restrictions on registering implicit manifest Broadcast Receivers introduced in Android 8.0, only a subset of the system broadcast Intents can be registered in the manifest. You can find the list of implicit broadcast exceptions at developer.android.com/guide/components/broadcast-exceptions.html .

The following sections examine how to create Intent Filters to register Broadcast Receivers that can react to some of these system events, and how to extract the device state information accordingly.

<action android:name="android.intent.action.ACTION_DOCK_EVENT"/> 

Why Build a Native Internet App?

Given that a web browser is available on most smart devices, you might ask if there’s any reason to create native Internet-based applications when you could make a web-based version instead.

While mobile web browsers are becoming increasingly powerful, there are still a number of benefits to creating thick- and thin-client native applications rather than relying on entirely web-based solutions:

• Bandwidth —Static resources such as images, layouts, and sounds can be expensive on devices with bandwidth restraints. By creating a native application, you can limit the bandwidth requirements to changed data only.
• Offline availability —With a browser-based solution, a patchy Internet connection can result in intermittent application availability. A native application can cache data and user actions to provide as much functionality as possible without a live connection, and synchronize with the cloud when a connection is reestablished.
• Latency and UX —By building a native application, you can take advantage of lower user-interaction latency as well as ensure the user experience is consistent with the OS and other first- and third-party apps.
• Reducing battery drain —Each time your application opens a connection to a server, the wireless radio will be turned on (or kept on). A native application can bundle its connections, minimizing the number of connections initiated. The longer the period between network requests, the longer the wireless radio can be left off and the lower the impact on battery life.
• Native features —Android devices are more than simple platforms for running a browser. They include location-based services, Notifications, widgets, cameras, Bluetooth radios, background Services, and hardware sensors. By creating a native application, you can combine the data available online with the hardware features available on the device to provide a richer user experience.

Connecting to an Internet Resource

Before you can access Internet resources, you need to add an INTERNET uses-permission node to your application manifest, as shown in the following XML snippet:

<uses-permission android:name="android.permission.INTERNET"/> 

Listing 7-1 shows the basic pattern for opening an Internet data connection and receiving a stream of data from a data feed.

Android includes several classes to help you handle network communications. They are available in the java.net.* and android.net.* packages.

Performing Network Operations on Background Threads Using View Models, Live Data, and Asynchronous Tasks

It’s always good practice to perform potentially time-consuming tasks such as network operations on a background thread. Doing so ensures you’re not blocking the UI thread, which would make your application janky or unresponsive. On Android, this best practice is enforced for network operations through the NetworkOnMainThreadException , which is triggered whenever a network operation is attempted on the main UI thread.

Within your Activity you can create and run a new Thread as shown in the following code. When you’re ready to post to the UI thread, call runOnUIThread and apply your UI changes within another Runnable:

Thread t = new Thread(new Runnable() {
  public void run() {
    // Perform Network operations and processing.
    final MyDataClass result = loadInBackground();
    // Synchronize with the UI thread to post changes.
    runOnUiThread(new Runnable() {
      @Override
      public void run() {
        deliverResult(result);
      }
    });
  }
});
t.start(); 

Alternatively, you can take advantage of the AsyncTask class, which encapsulates this process for you. An Async Task lets you define an operation to be performed in the background and provides event handlers that enable you to monitor progress and post the results on the GUI Thread.

Async Task handles all the Thread creation, management, and synchronization, enabling you to create an asynchronous task consisting of processing to be done in the background, and UI updates to be performed both during the processing and once it’s complete.

To create a new asynchronous task, extend the AsyncTask class, specifying the parameter types to use, as shown in this skeleton code:

private class MyAsyncTask extends AsyncTask<String, Integer, String> {
  @Override
  protected String doInBackground(String… parameter) {
    // Moved to a background thread.
    String result = "";
    int myProgress = 0;
    int inputLength = parameter[0].length();
    // Perform background processing task, update myProgress
    for (int i = 1; i <= inputLength; i++) {
      myProgress = i;
      result = result + parameter[0].charAt(inputLength-i);
      try {
        Thread.sleep(100);
      } catch (InterruptedException e) { }
      // Send progress to onProgressUpdate handler
      publishProgress(myProgress);
    }
    // Return the value to be passed to onPostExecute
    return result; 
  }

  @Override
  protected void onProgressUpdate(Integer… progress) {
    // Synchronized to UI thread.
    // Update progress bar, Notification, or other UI elements
  }

  @Override
  protected void onPostExecute(String result) {
    // Synchronized to UI thread.
    // Report results via UI update, Dialog, or notifications
  }
} 

After you’ve implemented an Asynchronous Task, execute it by creating a new instance and calling execute , passing in any parameters as required:

String input = "redrum … redrum";
new MyAsyncTask().execute(input); 

Each Async Task instance can be executed only once. If you attempt to call execute a second time, an exception will be thrown.

These approaches have several significant limitations stemming from the Activity life cycle described in Chapter 3 . As you know, an Activity (and its Fragments) may be destroyed and re-created whenever the device configuration changes. As a result a user rotating the screen may interrupt your running network Thread or Async Task, which will be destroyed along with its parent Activity.

For Threads that are started through user action, this will effectively cancel the operation. For Threads initiated within the Activity’s lifecycle handlers—such as onCreate or onStart —they will be re-created and rerun when the Activity is re-created—potentially executing the same network operation multiple times. This can result in duplicative data transfers and a shorter battery life.

A better approach is to use the ViewModel and LiveData classes provided as part of the Android Architecture Components. Any View Models associated with an Activity or Fragment are designed specifically to persist across configuration changes, effectively providing caching for the data they store. The data within a View Model is typically returned as Live Data.

Live Data is a lifecycle-aware class used to store, and provide observable updates for, application data. Lifecycle-awareness means that Live Data only sends updates to Observers within app components that are in an active lifecycle state.

To use View Models and Live Data, you must first add Android Architecture Components to your app module’s Gradle Build file:

dependencies {
  [… Existing dependencies nodes …]
  implementation "android.arch.lifecycle:extensions:1.1.1"
} 

Listing 7-2 shows a simple View Model implementation that takes advantage of the standard MutableLiveData class. It uses an AsyncTask to download and parse an Internet resource in the background, and returns the result as a Live Data representing a List of Strings.

To use a View Model within your application, you must first create a new (or return the existing) instance of your View Model within the Activity or Fragment that will be observing the Live Data.

Use the ViewModelProviders class’s static of method—passing in the current application component—to retrieve the View Models available, and use the get method to specify the View Model you wish to use:

MyViewModel myViewModel = ViewModelProviders.of(this)
                                            .get(MyViewModel.class); 

Once you have a reference to your View Model, you must add an Observer in order to receive the Live Data it contains. Call getData on the View Model, then use the observe method to add an Observer implementation whose onChanged handler will be triggered whenever the underlying data changes:

myViewModel.getData()
           .observe(this, new Observer<List<String>>() {
  @Override
  public void onChanged(@Nullable List<String> data) {
    // TODO When new View Model data is received, update the UI.
  }
}); 

The full process of obtaining a View Model for your Activity, requesting the Live Data, and observing it for changes is shown in Listing 7-3 .

Because your View Model lifecycle is based on your application—rather than the parent Activity or Fragment—the View Model’s Live Data’s loading function won’t be interrupted by a device configuration change.

Similarly, your results are implicitly cached across device configuration changes. After a rotation, when observe is called on the View Model’s data, it will immediately return the last result set via the onChanged handler—without the View Model’s loadData method being called. This saves significant time and battery power by eliminating duplicative network downloads and the associated processing.

In Chapter 11 you are introduced to more powerful APIs for scheduling background network operations, which take into account timing and device state to improve the efficiency of your network transfers.

Parsing XML Using the XML Pull Parser

Although detailed instructions for parsing XML and interacting with specific web services are outside the scope of this book, it’s important to understand the available technologies.

This section provides a brief overview of the XML Pull Parser, and the following sections demonstrate the use of the DOM parser and JSON Reader to retrieve earthquake details from the United States Geological Survey (USGS).

The XML Pull Parser API is available from the following libraries:

org.xmlpull.v1.XmlPullParser;
org.xmlpull.v1.XmlPullParserException;
org.xmlpull.v1.XmlPullParserFactory; 

It enables you to parse an XML document in a single pass. Unlike the DOM parser, the Pull Parser presents the elements of your document in a sequential series of events and tags.

Your location within the document is represented by the current event. You can determine the current event by calling getEventType . Each document begins at the START_DOCUMENT event and ends at END_DOCUMENT .

To proceed through the tags, simply call next , which causes you to progress through a series of matched (and often nested) START_TAG and END_TAG events. You can extract the name of each tag by calling getName and extract the text between each set of tags using getNextText .

Listing 7-4 demonstrates how to use the XML Pull Parser to extract details from the points of interest list returned by the Google Places API.

Connecting the Earthquake Viewer to the Internet

In this example you extend the Earthquake Viewer you began in Chapter 3 and improved in Chapter 5 . You’ll replace the dummy Array List of Earthquakes with a real list, by connecting to an earthquake feed, downloading, and parsing it so it can be displayed in your List Fragment.

The earthquake feed XML is parsed here by the DOM parser. Several alternatives exist, including the XML Pull Parser described in the previous section. Alternatively, you could parse the JSON feed using the JsonReader class, as shown in the following section

1. For this example, the feed used is the one-day USGS Atom feed for earthquakes with a magnitude greater than 2.5 on the Richter scale. Add the location of your feed as an external string resource within the Strings.xml resource file in the res/values folder. This lets you potentially specify a different feed based on a user’s locale:

   <resources>
     <string name="app_name">Earthquake</string>
     <string name="earthquake_feed">
     https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/2.5_day.atom
     </string>
   </resources> 

2. Before you can access this feed, your application needs to request permission for Internet access. Add the Internet uses-permission to the top of your manifest file:

   <?xml version="1.0" encoding="utf-8"?>
   <manifest xmlns_android="http://schemas.android.com/apk/res/android"
             package="com.professionalandroid.apps.earthquake">
   
     <uses-permission android:name="android.permission.INTERNET"/>
     
     [… Application Node …]
   
   </manifest> 

3. Our Internet access must happen on a background thread, and the results should persist on device configuration changes. Use a View Model and Live Data for this. Start by adding a dependency to the Android Architecture Components lifecycle extensions to your app module Gradle build file:

   dependencies {
     [… Existing dependencies nodes …]
     implementation "android.arch.lifecycle:extensions:1.1.1"
   } 

4. Create a new EarthquakeViewModel that extends AndroidViewModel and includes a MutableLiveData variable that represents a List of Earthquakes. This View Model will be cached and maintained across configuration changes. Create a getEarthquakes method that will check if our Earthquake List Live Data has been populated already, and if not, will load the Earthquakes from the feed:

   public class EarthquakeViewModel extends AndroidViewModel {
     private static final String TAG = "EarthquakeUpdate";
   
     private MutableLiveData<List<Earthquake>> earthquakes;
   
     public EarthquakeViewModel(Application application) {
       super(application);
     }
   
     public LiveData<List<Earthquake>> getEarthquakes() {
       if (earthquakes == null) {
         earthquakes = new MutableLiveData<List<Earthquake>>();
         loadEarthquakes();
       }
       return earthquakes;
     }
   
     // Asynchronously load the Earthquakes from the feed.
     public void loadEarthquakes() {
     }
   } 

5. Update the loadEarthquakes method to download and parse the earthquake feed. This must be done on a background thread, so implement an AyncTask to simplify this process. In the background, extract each earthquake and parse the details to obtain the ID, date, magnitude, link, and location. Once the feed has been parsed, update the onPostExecute handler to set the value of the Mutable Live Data that represents our List of Earthquakes. This will alert any registered Observers, passing them the updated list:

   public void loadEarthquakes() {
     new AsyncTask<Void, Void, List<Earthquake>>() {
       @Override
       protected List<Earthquake> doInBackground(Void… voids) {
         // Result ArrayList of parsed earthquakes.
         ArrayList<Earthquake> earthquakes = new ArrayList<>(0);
   
         // Get the XML
         URL url;
         try {
           String quakeFeed = 
             getApplication().getString(R.string.earthquake_feed);
           url = new URL(quakeFeed);
   
           URLConnection connection;
           connection = url.openConnection();
   
           HttpURLConnection httpConnection = (HttpURLConnection)connection;
           int responseCode = httpConnection.getResponseCode();
   
           if (responseCode == HttpURLConnection.HTTP_OK) {
             InputStream in = httpConnection.getInputStream();
   
             DocumentBuilderFactory dbf =
               DocumentBuilderFactory.newInstance();
             DocumentBuilder db = dbf.newDocumentBuilder();
   
             // Parse the earthquake feed.
             Document dom = db.parse(in);
             Element docEle = dom.getDocumentElement();
   
             // Get a list of each earthquake entry.
             NodeList nl = docEle.getElementsByTagName("entry");
             if (nl != null && nl.getLength() > 0) {
               for (int i = 0 ; i < nl.getLength(); i++) {
                 // Check to see if our loading has been cancelled, in which
                 // case return what we have so far.
                 if (isCancelled()) {
                   Log.d(TAG, "Loading Cancelled");
                   return earthquakes;
                 }
                 Element entry = 
                   (Element)nl.item(i);
                 Element id = 
                   (Element)entry.getElementsByTagName("id").item(0);
                 Element title =
                   (Element)entry.getElementsByTagName("title").item(0);
                 Element g =
                   (Element)entry.getElementsByTagName("georss:point")
                                 .item(0);
                 Element when =
                   (Element)entry.getElementsByTagName("updated").item(0);
                 Element link =
                   (Element)entry.getElementsByTagName("link").item(0);
   
                 String idString = id.getFirstChild().getNodeValue();
                 String details = title.getFirstChild().getNodeValue();
                 String hostname = "http://earthquake.usgs.gov";
                 String linkString = hostname + link.getAttribute("href");
   
                 String point = g.getFirstChild().getNodeValue();
                 String dt = when.getFirstChild().getNodeValue();
                 SimpleDateFormat sdf =
                   new SimpleDateFormat("yyyy-MM-dd'T'hh:mm:ss.SSS'Z'");
                 Date qdate = new GregorianCalendar(0,0,0).getTime();
                 try {
                   qdate = sdf.parse(dt);
                 } catch (ParseException e) {
                   Log.e(TAG, "Date parsing exception.", e);
                 }
   
                 String[] location = point.split(" ");
                 Location l = new Location("dummyGPS");
                 l.setLatitude(Double.parseDouble(location[0]));
                 l.setLongitude(Double.parseDouble(location[1]));
   
                 String magnitudeString = details.split(" ")[1];
                 int end =  magnitudeString.length()-1;
                 double magnitude =
                   Double.parseDouble(magnitudeString.substring(0, end));
   
                 if (details.contains("-"))
                   details = details.split("-")[1].trim();
                 else
                   details = "";
   
                 final Earthquake earthquake = new Earthquake(idString,
                                                              qdate,
                                                              details, l,
                                                              magnitude, 
                                                              linkString);
   
                 // Add the new earthquake to our result array.
                 earthquakes.add(earthquake);
               }
             }
           }
           httpConnection.disconnect();
         } catch (MalformedURLException e) {
           Log.e(TAG, "MalformedURLException", e);
         } catch (IOException e) {
           Log.e(TAG, "IOException", e);
         } catch (ParserConfigurationException e) {
           Log.e(TAG, "Parser Configuration Exception", e);
         } catch (SAXException e) {
           Log.e(TAG, "SAX Exception", e);
         }
         // Return our result array.
         return earthquakes;
       }
   
       @Override
       protected void onPostExecute(List<Earthquake> data) {
         // Update the Live Data with the new list.
         earthquakes.setValue(data);
       }
     }.execute();
   } 

6. Update your Earthquake Main Activity to remove the dummy data and update the Earthquake List Fragment to use your new EarthquakeViewModel .
   1. 6.1. Start by updating the Activity’s onCreate handler, removing the dummy data

      EarthquakeViewModel earthquakeViewModel;

      
      @Override
      protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_earthquake_main);
      
        FragmentManager fm = getSupportFragmentManager();
      
        // Android will automatically re-add any Fragments that
        // have previously been added after a configuration change,
        // so only add it if this is an automatic restart.
        if (savedInstanceState == null) {
          FragmentTransaction ft = fm.beginTransaction();
          mEarthquakeListFragment = new EarthquakeListFragment();
          ft.add(R.id.main_activity_frame, mEarthquakeListFragment,
                 TAG_LIST_FRAGMENT);
          ft.commitNow();
        } else {
          mEarthquakeListFragment = 
            (EarthquakeListFragment)fm.findFragmentByTag(TAG_LIST_FRAGMENT);
        }
      
        // Retrieve the Earthquake View Model for this Activity.
        earthquakeViewModel = ViewModelProviders.of(this)
                                .get(EarthquakeViewModel.class);
      } 

   2. 6.2. Within the Earthquake List Fragment, update the onActivityCreated handler. Using the View Model Provider’s static of method to retrieve the current instance of your Earthquake View Model. Add an Observer to the Live Data returned from your View Model—it will set the Earthquake List Fragment Earthquake List when your Activity is created, and again whenever the list of parsed Earthquakes is updated:

      protected EarthquakeViewModel earthquakeViewModel;
      
      @Override
      public void onActivityCreated(@Nullable Bundle savedInstanceState) {
        super.onActivityCreated(savedInstanceState);
      
        // Retrieve the Earthquake View Model for the parent Activity.
        earthquakeViewModel = ViewModelProviders.of(getActivity())
                                .get(EarthquakeViewModel.class);
      
        // Get the data from the View Model, and observe any changes.
        earthquakeViewModel.getEarthquakes()
          .observe(this, new Observer<List<Earthquake>>() {
            @Override
            public void onChanged(@Nullable List<Earthquake> earthquakes) {
              // When the View Model changes, update the List
              if (earthquakes != null)
                setEarthquakes(earthquakes);
            }
          });
      } 

7. When you run your project, you should see a Recycler View that features the earthquakes from the last 24 hours with a magnitude greater than 2.5 ( Figure 7-1 ).

   

8. The earthquake data is cached by the View Model, so it will persist across device configuration changes, and only refresh when the app is restarted. Let’s update the app to let users refresh the earthquake list using the swipe-to-refresh pattern. Update the fragment_earthquake_list.xml layout resource to include a SwipeRefreshLayout as the parent of the RecyclerView :

   <?xml version="1.0" encoding="utf-8"?>
   <android.support.v4.widget.SwipeRefreshLayout
     xmlns_android="http://schemas.android.com/apk/res/android"
     android:id="@+id/swiperefresh"
     android:layout_width="match_parent"
     android:layout_height="match_parent">
     <android.support.v7.widget.RecyclerView
       xmlns_android="http://schemas.android.com/apk/res/android"
       xmlns_app="http://schemas.android.com/apk/res-auto"
       android:id="@+id/list"
       android:layout_width="match_parent"
       android:layout_height="match_parent"
       android:layout_marginLeft="16dp"
       android:layout_marginRight="16dp"
       app:layoutManager="LinearLayoutManager"
     />
   </android.support.v4.widget.SwipeRefreshLayout> 

9. Update onCreateView within the Earthquake List Fragment to get a reference to the Swipe Refresh Layout added in Step 8, and update onViewCreated to assign a refresh listener to the Swipe Refresh Layout that calls a new updateEarthquakes method when the swipe to refresh action is made:

   private SwipeRefreshLayout mSwipeToRefreshView;
   
   @Override
   public View onCreateView(LayoutInflater inflater, ViewGroup container,
                            Bundle savedInstanceState) {
     View view = inflater.inflate(R.layout.fragment_earthquake_list, 
                                  container, false);
   
     mRecyclerView = (RecyclerView) view.findViewById(R.id.list);
     mSwipeToRefreshView = view.findViewById(R.id.swiperefresh);
     return view;
   }
   
   @Override
   public void onViewCreated(View view, Bundle savedInstanceState) {
     super.onViewCreated(view, savedInstanceState);
   
     // Set the Recycler View adapter
     Context context = view.getContext();
     mRecyclerView.setLayoutManager(new LinearLayoutManager(context));
     mRecyclerView.setAdapter(mEarthquakeAdapter);
   
     // Setup the Swipe to Refresh view
     mSwipeToRefreshView.setOnRefreshListener(new 
       SwipeRefreshLayout.OnRefreshListener() {
       @Override
       public void onRefresh() {
         updateEarthquakes();
       }
     });
   }
   
   protected void updateEarthquakes() {
   } 

10. Update the setEarthquakes method to disable the “refreshing” visual indicator when an update has been received:

    public void setEarthquakes(List<Earthquake> earthquakes) {
      mEarthquakes.clear();
      mEarthquakeAdapter.notifyDataSetChanged();
      for (Earthquake earthquake: earthquakes) {
        if (!mEarthquakes.contains(earthquake)) {
          mEarthquakes.add(earthquake);
          mEarthquakeAdapter.notifyItemInserted(
            mEarthquakes.indexOf(earthquake));
        }
      }
      mSwipeToRefreshView.setRefreshing(false);
    }  

11. The update itself will be performed by the Earthquake View Model, which we communicate with through the parent Activity. Define a new OnListFragmentInteractionListener within the Earthquake List Fragment; it should include an onListFragmentRefreshRequested method that’s called when we request a refresh via the updateEarthquakes method added in Step 9:

    public interface OnListFragmentInteractionListener {
      void onListFragmentRefreshRequested();
    }
    
    private OnListFragmentInteractionListener mListener;
    
    @Override
    public void onAttach(Context context) {
      super.onAttach(context);
      mListener = (OnListFragmentInteractionListener) context;
    }
    
    @Override
    public void onDetach() {
      super.onDetach();
      mListener = null;
    }
    
    protected void updateEarthquakes() {
      if (mListener != null)
        mListener.onListFragmentRefreshRequested();
    } 

12. Return to the Earthquake Main Activity and have it implement the Interface defined in Step 11, and use the Earthquake View Model to force a refresh when requested:

    public class EarthquakeMainActivity extends AppCompatActivity implements 
      EarthquakeListFragment.OnListFragmentInteractionListener {
    
      @Override
      public void onListFragmentRefreshRequested() {
        updateEarthquakes();
      }
    
      private void updateEarthquakes() {
        // Request the View Model update the earthquakes from the USGS feed.
        earthquakeViewModel.loadEarthquakes();
      }
      
      [… Existing Class Definition …]
    } 

13. You should also add a refresh action as a menu item or on your app’s action bar to support users who may not be able to perform a swipe gesture (for example, users with accessibility issues can trigger action bar actions using external devices, such as keyboards and D-pads). We show how to do this in Chapter 13 , “Implementing a Modern Android User Experience.”

Parsing JSON Using the JSON Parser

This section provides a brief overview of the JsonParser , demonstrating how it can be used to parse earthquake details from the JSON feed from the United States Geological Survey (USGS) found at earthquake.usgs.gov/earthquakes/feed/v1.0/summary/2.5_day.geojson .

As with XML parsing in the earlier sections, detailed instructions for parsing JSON are outside the scope of this book; however, with many APIs now providing JSON feeds it’s important to introduce the concepts.

Like the pull parser, the JSON Parser enables you to parse a document in a single pass, presenting the elements of your document in a sequential series of objects, arrays, and values.

To create a recursive parser, you must first create an entry point method that takes an Input Stream and creates a new JSON Reader:

private List<Earthquake> parseJson(InputStream in) throws IOException {

  // Create a new Json Reader to parse the input.
  JsonReader reader = 
    new JsonReader(new InputStreamReader(in, "UTF-8"));
    // TODO: Parse the InputStream
} 

Data within each JSON feed are stored as names and values, structured using objects and arrays. JSON objects are used similarly to code objects—grouping together values that are semantically related. JSON also supports arrays to group multiple values or objects together.

For example, the USGS feed contains a type value, and metadata and bounding box objects at the root level, as well as an array of multiple feature objects representing each earthquake. Each feature object then contains values for type and ID, and objects to group earthquake properties and geometry details. The geometry object in turn includes a value for the geometry type, and an array of values representing the latitude, longitude, and depth of each earthquake. This structure is illustrated in part in Figure 7-2 .

To parse these structures, create handler methods that will parse each object, and array, within the JSON text.

For the object structure handler methods, begin by calling your JSON Reader object’s beginObject method to consume the opening brace. Then use the hasNext method to control a while loop within which you can extract values, or further objects (or arrays). Use the endObject method to read the object’s closing brace when the object has been fully read:

private MyObject readMyObject(JsonReader reader) throws IOException {
  // Create variables for the return values.
  String myValue = null;

  // Consume the opening brace.
  reader.beginObject();
  
  // Traverse the values, objects, and arrays within this object. 
  while (reader.hasNext()) {
    // Find the next name.
    String name = reader.nextName();

    // Extract each of the values based on name matches.
    if (name.equals("my_value")) {
      myValue = reader.nextString();

    // Skip any unexpected (or purposefully ignored) values.
    } else {
      reader.skipValue();
    }
  }

  // Consume closing brace.
  reader.endObject();

  // Return parsed object.
  return new MyObject(myValue);
}
 

Arrays are handled similarly, using the beginArray and endArray methods to consume the opening and closing brackets respectively. The values within an array are homogenous, allowing you to simply add each value to a list:

public List<Double> readDoublesArray(JsonReader reader) 
  throws IOException {

  List<Double> doubles = new ArrayList<Double>();

  reader.beginArray();

  while (reader.hasNext()) {
    doubles.add(reader.nextDouble());
  }

  reader.endArray();
  return doubles;
} 

As you traverse each object or array, if a nested object or array is found, simply pass the JSON Reader object to the corresponding parsing method.

If an unknown name is encountered, you can choose to call skipValue to recursively skip the value’s nested tokens

Listing 7-5 demonstrates how to use the JSON Parser to extract details from the JSON feed of magnitude 2.5+ earthquake over the past day supplied by the USGS.

Downloading Files

To request a download, create a new DownloadManager.Request , specifying the URI of the file to download and passing it in to the Download Manager’s enqueue method, as shown in Listing 7-6 .

You can use the returned reference value to perform future actions or query the download, including checking its status or canceling it.

You can add an HTTP header to your request, or override the mime type returned by the server, by calling addRequestHeader and setMimeType , respectively, on your Request object.

You can also specify the connectivity conditions under which to execute the download. The setAllowedNetworkTypes method enables you to restrict downloads to either Wi-Fi or mobile networks. The setAllowedOverRoaming and setAllowedOverMetered methods allow you to prevent downloads while the phone is roaming or over a metered (paid) connection.

The following snippet shows how to ensure a large file is downloaded only when connected to Wi-Fi:

request.setAllowedNetworkTypes(Request.NETWORK_WIFI); 

After calling enqueue , the download begins as soon as suitable connectivity is available, and the Download Manager is free.

By default, ongoing and completed downloads are indicated as Notifications. You should create a Broadcast Receiver that listens for the ACTION_NOTIFICATION_CLICKED action, which will be broadcast whenever a user selects a download from the Notification tray or the Downloads app. It will include an EXTRA_NOTIFICATION_CLICK_DOWNLOAD_IDS extra that contains the reference ID of the download that was selected.

When the download is complete, the Download Manager will broadcast the ACTION_DOWNLOAD_COMPLETE action, with an EXTRA_DOWNLOAD_ID extra indicating the reference ID of the completed file download, as shown in Listing 7-7 .

The Download Manager will continue downloading your files between user sessions of your app, as well as phone reboots. As a result, it’s important for you to store the download reference numbers to ensure your app remembers them.

For the same reason you should register your Broadcast Receivers for Notification clicks and download completions within the manifest, as shown in Listing 7-8 , because there is no guarantee your app will be running when a user selects a download notification, or the download is completed.

Once the download has completed, you can use Download Manager’s openDownloadedFile method to receive a Parcel File Descriptor to your file, or use the ID to query the Download Manager and obtain metadata details.

You learn more about file handling in Chapter 8 , “Saving State, User Preferences, and Using and Sharing Files.”

Customizing Download Manager Notifications

By default, ongoing Notifications will be displayed for each file while it’s being downloaded by the Download Manager. Each Notification will show the current download progress and the filename ( Figure 7-3 ).

The Download Manager enables you to customize the Notification displayed for each download request, including hiding it completely. The following snippet shows how to use the setTitle and setDescription methods to customize the text displayed in the file download Notification. Figure 7-4 shows the result.

request.setTitle("Hive Husks");
request.setDescription("Downloading Splines for Reticulation");
 

The setNotificationVisibility method lets you control when, and if, a Notification should be displayed for your download using one of the following flags:

• Request.VISIBILITY_VISIBLE —An ongoing Notification will be visible for the duration that the download is in progress. It will be removed when the download is complete. This is the default option.
• Request.VISIBILITY_VISIBLE_NOTIFY_COMPLETED —An ongoing Notification will be displayed during the download and will continue to be displayed once the download has completed, until it is selected or dismissed.
• Request.VISIBILITY_VISIBLE_NOTIFY_ONLY_COMPLETION —Useable only when using addCompletedDownload to add an already downloaded file to the downloads database system. When selected, a notification will be displayed after the file has been added.
• Request.VISIBILITY_HIDDEN —No Notification will be displayed for this download. In order to set this flag, your application must have the DOWNLOAD_WITHOUT_NOTIFICATION permission specified in its manifest:

  <uses-permission 
    android:name="android.permission.DOWNLOAD_WITHOUT_NOTIFICATION"/> 

Specifying a Download Location

By default, all Download Manager downloads are saved to the shared download cache using system-generated filenames, where they may be deleted automatically by the system, or manually by users.

Alternatively, a download Request can indicate a URI to a specific download location. In that case, the location must be on external storage, and accordingly your app must have the WRITE_EXTERNAL_STORAGE permission defined in its manifest:

<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/> 

The following code snippet shows how to specify an arbitrary path on external storage:

request.setDestinationUri(Uri.fromFile(f)); 

If the downloaded file is specific to your application, you may want to place it in your application’s external storage folder. Note that access control is not applied to this folder, and other applications will be able to access it. If your application is uninstalled, files stored in these folders will also be removed.

The following snippet specifies storing a file in your application’s external downloads folder:

request.setDestinationInExternalFilesDir(this,
  Environment.DIRECTORY_DOWNLOADS, "bugdroid.png"); 

For files that can or should be shared with other applications—particularly those you want to scan with the Media Scanner—you can specify a location within the public folder on the external storage. The following snippet requests a file be stored in the public music folder:

request.setDestinationInExternalPublicDir(Environment.DIRECTORY_MUSIC,
  "android_anthem.mp3"); 

It’s important to note that by default, files downloaded by the Download Manager are not scanned by Media Scanner, so they might not appear in apps such as photo galleries and music players.

To make downloaded files scannable, call allowScanningByMediaScanner on the Request object before it is enqueued by the Download Manager:

request.allowScanningByMediaScanner(); 

By default, your files will be visible and manageable by the system’s Downloads app. If you’d prefer they not be, you can call setVisibleInDownloadsUi , passing in false :

request.setVisibleInDownloadsUi(false); 

Canceling and Removing Downloads

The Download Manager’s remove method lets you cancel a pending download, abort a download in progress, or delete a completed download.

As shown in the following code snippet, the remove method accepts download IDs as optional arguments, enabling you to specify one or many downloads to cancel:

downloadManager.remove(fileRef1, fileRef2, fileRef3); 

It returns the number of downloads successfully canceled. If a download is canceled, all associated files—both partial and complete—are removed.

Querying the Download Manager

You can query the Download Manager to find the status, progress, and details of your download requests by using the query method, which returns a Cursor to the list of downloads.

The query method takes a DownloadManager.Query object as a parameter. Use the setFilterById method on a Query object to specify a sequence of download reference IDs, or use the setFilterByStatus method to filter on a download status using one of the DownloadManager.STATUS_* constants to specify running, paused, failed, or successful downloads.

The Download Manager includes a number of COLUMN_ static String constants that you can use to query the result Cursor. You can find details for each download, including the status, files size, bytes downloaded so far, title, description, URI, media type, and Media Provider download URI.

In addition, the Download Manager includes the getUriForDownloadedFile and openDownloadedFile methods. Listing 7-9 expands on Listing 7-7 to demonstrate how to find the Uri, or Parcel File Descriptor of completed downloads from within a Broadcast Receiver registered to listen for download completions.

For downloads that are either paused or have failed, you can query the COLUMN_REASON column to find the cause represented as an integer.

In the case of STATUS_PAUSED downloads, you can interpret the reason code by using one of the DownloadManager.PAUSED_ static constants to determine if the download has been paused while waiting for network connectivity, a Wi-Fi connection, or pending a retry.

For STATUS_FAILED downloads, you can determine the cause of failure using the DownloadManager.ERROR_ codes. Possible error codes include lack of a storage device, insufficient free space, duplicate filenames, or HTTP errors.

Listing 7-10 shows how to find a list of the currently paused downloads, extracting the reason the download was paused, the filename, its title, and the current progress.

View Models and Live Data

View Models and Live Data were introduced in Chapter 7 as part of a way to perform network operations on background Threads. They are the recommended best practice technique for persisting state across device configurations.

View Models are designed specifically to store and manage UI-related data such that it’s persisted across configuration changes. View Models provide a simple way to separate the data being displayed from the UI controller logic that belongs in the Fragment or Activity. As a result, it’s good practice to move all your data, business logic, and any code not directly related to UI elements out of your Activity or Fragment, and into a View Model.

Because View Models are retained during configuration changes, data they hold is immediately available to a newly re-created Activity or Fragment instance.

The data stored within a View Model is typically returned as LiveData , a class specifically designed to hold individual data fields for View Models.

Live Data is a lifecycle-aware class used to provide observable updates for application data. Lifecycle-awareness means that Live Data only sends updates to Observers within app components that are in an active lifecycle state. It’s sometimes useful to create your own Live Data class; however, in most instances the MutableLiveData class is sufficient.

Each Mutable Live Data instance can be declared to represent a particular data type:

private final MutableLiveData<List<String>> data; 

Within your View Model, you can modify the value stored by your Live Data using the setValue method while on the main UI Thread:

data.setValue(data); 

Alternatively, you can use postValue to update the UI from a background Thread, which will post a Task to a main Thread to perform the update.

Whenever the value of a Live Data object is changed, the new value will be dispatched to any active Observers as described later in this section.

An Observer added by an Activity or Fragment will automatically be removed when the corresponding Activity or Fragment is destroyed, ensuring they can safely observe Live Data without worrying about memory leaks.

The ViewModel and related LiveData classes are available as part of the Android Architecture Components library, so to use them you first need to add a dependency to your app module’s Gradle Build file:

dependencies {
  [… Existing dependencies nodes …]
  implementation "android.arch.lifecycle:extensions:1.1.1"
} 

The following snippet shows the skeleton code for a simple View Model implementation using a standard Mutable Live Data object to store UI-related data. It also uses an AsyncTask to encapsulate the background Threading needed to load the associated data:

public class MyViewModel extends AndroidViewModel {
  private static final String TAG = "MyViewModel";

  private MutableLiveData<List<String>> data = null;

  public MyViewModel(Application application) {
    super(application);
  }

  public LiveData<List<String>> getData() {
    if (data == null) {
      data = new MutableLiveData<List<String>>();
      loadData();
    }
    return data;
  }

  // Asynchronously load / update the data represented
  // by the Live Data object.
  public void loadData() {
    new AsyncTask<Void, Void, List<String>>() {
      @Override
      protected List<String> doInBackground(Void… voids) {
        ArrayList<String> result = new ArrayList<>(0);
        // TODO Load the data from this background thread.
        return result;
      }

      @Override
      protected void onPostExecute(List<String> resultData) {
        // Update the Live Data data value.
        data.setValue(resultData);
      }
    }.execute();
  }
} 

Once defined, to use a View Model within your application you must first create a new (or return the existing) instance of your View Model from within an Activity or Fragment.

The ViewModelProviders class includes a static of method that can be used to retrieve all the View Models associated with a given Context:

ViewModelProvider providers = ViewModelProviders.of(this); 

Then use the get method to specify the View Model you wish to use:

MyViewModel myViewModel = providers.get(MyViewModel.class); 

Once you have a reference to your View Model, access any of the Live Data fields it contains and use the observe method to add an Observer that will receive updates (via the onChanged handler) when the Observer is added, and again whenever the underlying data changes. This is typically done within the onCreate handler of your Activity or Fragment:

myViewModel.getData().observe(this, 
  new Observer<List<String>>() {
    @Override
    public void onChanged(@Nullable List<String> data) {
      // TODO When new View Model data is received, update the UI.
    }
  }
); 

Because your View Model lifecycle is based on your application—rather than the corresponding Activity or Fragment—the View Model’s loading function won’t be interrupted by a device configuration change.

Similarly, your results are implicitly cached across device configuration changes. After a rotation, when observe is called on the View Model’s data, it will immediately return the last result set via the onChanged handler—without the View Model’s loadData method being called.

Headless Fragments

Prior to the availability of View Models through the Android Architecture Components, headless Fragments were useful mechanisms for retaining instance state across device configuration changes.

Fragments are not required to contain a UI—a “headless” Fragment can be created by returning null within its onCreateView method (this is the default implementation). Headless Fragments that are retained across Activity restarts can be used to encapsulate self-contained operations that need access to lifecycle methods, or that should not be terminated and restarted along with the Activity after a configuration change.

You can request that your Fragment instance be retained across configuration changes by calling setRetainInstance within a Fragment’s onCreate handler. This will disconnect the Fragment instance’s re-creation lifecycle from its parent Activity, meaning it will not be killed and restarted along with its parent Activity:

@Override
public void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);

  // Retain this fragment across configuration changes.
  setRetainInstance(true);
}

@Override
public View onCreateView (LayoutInflater inflater, 
                          ViewGroup container, 
                          Bundle savedInstanceState){
  return null;
}