Creating the project

Most of the classes and methods that you use to write phone apps work on Android Wear apps as well. For evidence (but not proof) of this fact, follow these steps:

1. In Android Studio, start a new project and select the Wear OS option.

   You see a list of templates like the one shown in Figure 2-1.

   

2. Choose the Blank Wear Activity template and click Next.

   You see the Configure Your Project dialog box, shown in Figure 2-2. Most of the features don’t look any different from a standard app. However, notice that the minimum API level defaults to API 28: Android 9.0 (Pie). In looking at online offerings, you find that this is actually a good level to choose, despite the fact that it limits the smartphones you can pair with your app if you wanted to do so.

   The Pair with Empty Phone App option on this page lets you pair your wearable app with a phone. However, Android recommends against this and states outright at https://developer.android.com/training/wearables/apps/creating that a wear app should run independently of a phone app. The suggestion is to test your app on an actual watch by uploading the app using Wi-Fi or Bluetooth. This chapter uses the emulator just to make things easy and ensure that you can follow along, even if you don’t currently own a smartwatch (or other wearable device).

   If you check the Pair with Empty Phone App option, what you see is a dual project containing both a mobile and a wear folder.

   

3. Type 05_02_01 in the Name field, type com.allmycode.p05_02_01 in the Package Name field, and click Finish.

   Android Studio begins creating your project for you.

If you like to poke around in a new project before doing anything else, you may notice that the Component Tree shows an error for the FrameLayout, as shown in Figure 2-3, before you've touched anything. This error is tied to the app:boxedEdges="all" entry, which supposedly is missing a namespace entry, except that the namespace entry is there as part of the <androidx.wear.widget.BoxInsetLayout> element. When you see this error, you click the offending line to display a red light bulb on the left side of the editor. Click the light bulb and choose Suppress: Add tools.ignore="Missing Prefix" Attribute from the context menu.

Configuring a wearable device emulator

To run this chapter's example, the only thing you need is an Android Wear AVD. Here's how you get one:

1. In Android Studio's main menu, choose Tools ⇒   AVD Manager.

   The AVD Manager opens.

2. In the AVD Manager window, click the Create Virtual Device button.

   The Virtual Device Configuration dialog box appears. The left side of the dialog box contains a Category list, and the middle contains a list of hardware profiles.

3. In the Category list, select Wear OS.

   You see a list of devices for the Wear OS that replaces the Phone device listing you normally see, as shown in Figure 2-4. Unlike the Phone category, the Wear OS category focuses on device types rather than specific device models. All these devices have the same density and slightly varying resolutions. Otherwise, the only real difference is the shape. You have a choice of these basic shapes:

   • Square: A form commonly found for larger wearables that provides the most usable screen space.
   • Round: A circular form commonly found with moderately sized wearable displays, often oriented toward fashion.
   • Round chin: A circular form that is mostly round with a squared-off portion at the bottom. It provides a luxury look but has the least usable screen space to offer.

4. Select Android Wear Square and click Next.

   This chapter relies on a specific AVD so that it’s easier for you to compare the output from your app with the screenshots in the book. However, any of the choices would likely work fine, and if you’re really determined to see a round or a round chin display instead, feel free to select it.

   It's true. To run this chapter's example, any Android wear choice will do. But to run the emulator on your development computer, some choices might be better than others. Some AVDs consume too much memory. The Android Wear Square selection tends to work best.

   

5. Click Next.

   You see the Select a System Image dialog box, shown in Figure 2-5. Notice the tabs at the top of the table with Recommended selected by default. The recommended options will work best on most development computers, so you should select one of them unless you have a particular need. For example, if you select the Other Images tab, you see that you can choose an armeabi-v7a processor rather than an x86 processor.

   Notice that the highest available API level is 28. Because you select API level 28 in Step 2 in the “Creating the project” section, earlier in the chapter, you must choose an API level 28 device now.

   The Target column is also important for a system image in this situation. The option that will cause fewest problems when creating your app is the Android 9.0 (Wear OS) target.

   Also remember that the previous examples in this book use API level 29, so you must download the API level 28 release.

6. Click the Download link for the Android 9.0 (Wear OS) target, shown highlighted in Figure 2-5.

   You see a Component Installer dialog box appear. The progress bar shows the download process, which can take a while. It might be a good idea to read a good book or have some coffee. At some point, the download and installation process will complete.

   

7. Click Finish.

   The Component Installer dialog box goes away. You return to the Select a System Image dialog box.

8. Click Next.

   You see the Verify Configuration dialog box, shown in Figure 2-6.

9. Click Finish.

   You see the new device appear in the Android Virtual Device Manager dialog. Notice that the Type column shows a watch icon, rather than a smartphone and tablet icon.

10. Close the Android Virtual Device Manager dialog.

11. Choose Run⇒  Select device.

    A context menu appears.

12. Click the Android Wear Square API 28 entry.

    The IDE is now configured to use an appropriate device for testing.

To ensure that your configuration works, choose Run⇒  Run ‘app’. You see the default project output shown in Figure 2-7.

Other testing configurations

For the full Android Wear experience, you may want two devices — a wearable and a phone (modern wearables are far more capable than the offerings of the past). The obvious question is, are both of them emulated, or just one? Are they both real, or only one of them?

To help answer this question, the Android documentation provides a few scenarios:

• Ignore the phone and use an emulated Android Wear device.

  That's the scenario that we recommend for this chapter's example.

• Connect a real phone to your development computer and use an emulated Android Wear device.

  See the brief list of tips in this section.

• Use a real phone and a real Android Wear device.

  Again, see the brief list of tips.

The Android developer training pages have detailed instructions on setting up phones for testing with Android Wear, so this section of the chapter doesn’t dwell on the details. Instead, you get some of the highlights. These highlights might help you see the forest for the trees while you march step-by-step through the instructions on the Android developer site's pages.

The Android developer site's pages on testing with real devices are http://developer.android.com/training/wearables/apps/creating.html and http://developer.android.com/training/wearables/apps/bt-debugging.html. When you set up a phone for testing with Android Wear, you perform some or all of the following steps:

• Install the Android Wear app from the Google Play Store on your phone.
• Use the Developer options in the phone's Settings screen to enable USB debugging on the phone.
• (With an Android Wear emulator) Type the following command in your development computer's command prompt window or Terminal app:

  adb -d forward tcp:5601 tcp:5601

  This command forwards your emulator's communications to the connected phone.

• (On a real wearable device) Use the Developer options in the device's Settings screen to enable ADB debugging on the Wear device.
• In the Android Wear app on the phone, pair the phone with the emulator (or with the real wearable device).

For connecting a real wearable device, you have two options:

• Connect the device to your development computer using a USB cable. Alas! Some Android wearables don't have USB ports.
• Create a Bluetooth connection between the phone and the wearable. For this option, you have to enable the Debugging over Bluetooth option on the wearable. You also have to set up Debugging over Bluetooth in the Android Wear app on the phone and type the commands

  adb forward tcp:4444 localabstract:/adb-hub
adb connect localhost:4444

  on your development computer.

Defining the watch face project

As do most Android projects, this project begins at the main screen, where you define the project parameters. Because this project is a little different, use these steps to create your project:

1. In Android Studio, start a new project and select the Wear OS option.

   You see a list of templates like the one shown previously in Figure 2-1.

2. Highlight the Watch Face template.

   The title of this dialog box is misleading. A Watch Face isn't an activity. But the creators of Android Studio can't worry about every little detail.

   When you select Watch Face in this step, you're telling Android Studio to write a lot of code for you. In later sections, you explore some of this code. For now, just keep clicking.

3. Click Next.

   You see the Configure Your Project dialog box, shown previously in Figure 2-2. Notice that the template actually shows a watch face icon in place of the round face icon shown in Figure 2-2. Like the previous project, you should use a minimum API level of API 28: Android 9.0 (Pie).

4. Type 05_02_02 in the Name field, type com.allmycode.p05_02_02 in the Package Name field, and click Finish.

   Android Studio begins creating your project for you.

Testing the watch face app

The first thing you want to do after creating this project is to see it run. The following steps help you test the new app. However, you’ll find that this app runs differently from those you may have worked with in the past.

1. Choose Run⇒  Edit Configurations.

   You see the Run/Debug Configurations dialog box, shown in Figure 2-8.

   

2. Choose Nothing in the Launch field, as shown in Figure 2-8, and click OK.

   You’re launching a service, not an activity. This project is affecting the emulator wallpaper.

3. Choose Run⇒  Select Device and choose Android Wear Square API 28 from the context menu that appears.

   For help with AVDs, refer to the “Setting Up Your Testing Environment” section, earlier in this chapter.

4. Choose Run ⇒   Run 'app'.

   When you do, the wheels start churning. When the emulator appears, you see the normal watch face, but no app. However, you’re not running an app; you’re changing the watch face.

5. Click the lightning-bolt icon on the emulator and drag down.

   You see a list of configuration items.

6. Click the sprocket.

   The Settings menu appears, as shown in Figure 2-9.

   

7. Click Display.

   You see the Display settings. Notice that the top item is Change Watch Face.

8. Click Change Watch Face.

   The display shows two items. The first is the current watch file and the second is an option to see more watch faces, as shown in Figure 2-10.

9. Click Change Watch Faces.

   One of the options in the list is My Analog. It normally appears at the bottom of the list, as shown in Figure 2-11.

10. Click My Analog.

    The new watch face appears onscreen, as shown in Figure 2-12.

Dissecting the skeletal watch face project

Many interesting things lurk inside a typical watch face project's code. This section describes a few of them. As you read this section, you can follow along by examining the code that Android Studio creates in the previous set of steps.

Enhancing the skeletal watch face project

Android Studio creates the skeletal app that's described in the previous section. You get the skeletal app for free simply by clicking buttons when you create a new project. Of course, freebies have disadvantages. For one thing, they seldom do exactly what you want your app to do. For another, looking at canned code isn't as satisfying as writing your own code. Here's how to add the date to the watch face (and you can use this approach for your own additions):

1. Add the following two new import statements to the beginning of MyWatchFace.kt.

   import java.time.LocalDateTime
import java.time.format.DateTimeFormatter

2. Create a new function for drawing the time, like this one:

   private fun drawDate(canvas: Canvas) {
val paint = Paint()
paint.setColor(Color.WHITE)
paint.style = Paint.Style.FILL
canvas.drawRect(90f, 160f, 190f, 190f, paint)

paint.setColor(Color.BLACK)
paint.textSize = 20f
val localDate = LocalDateTime.now()
canvas.drawText(
localDate.format(
DateTimeFormatter.ofPattern("M/d/y")),
95f, 180f, paint)
}

   This function performs two tasks. First, it draws a white square on the background. Second, it adds the current time in black.

   You obtain the current time using LocalDateTime.now(). However, this time is unformatted. To format the time, you use localDate.format(), with a formatter, which is DateTimeFormatter.ofPattern("M/d/y")) in this case. The article at https://developer.android.com/reference/java/time/format/DateTimeFormatter tells you more about using patterns to format both time and date.

3. Add drawDate() to onDraw() using the following code in bold:

   override fun onDraw(canvas: Canvas, bounds: Rect) {
val now = System.currentTimeMillis()
mCalendar.timeInMillis = now

drawBackground(canvas)
drawDate(canvas)
drawWatchFace(canvas)
}

   The order in which you draw the watch face elements is important. If you were to draw the date after the watch face, the hour and minute hands would disappear behind the data, which would look quite odd indeed!

That’s it! You're done! When you run the app, you see a display like the one in Figure 2-13.