Android Wear is about choice. From the beginning, users could choose the style they wanted, including watches with circular screens. With Android Wear API 23, we have enabled even better developer support so that you can code delightful experiences backed by beautiful code. The key component of this is the new round resource identifier which helps you separate resource files such as layouts, dimens between round and square devices. In this blog post, I will lay out the options that developers have and why you should consider dimens.xml! In addition, I will outline how best to deal with devices which have a chin.

Getting started? Consider BoxInsetLayout!

If all your content can fit into a single square screen, use the BoxInsetLayout. This class has been included in the Wearable Support Library from the start and helps you put all the content into the middle square area of the circular screen and is ignored by square screens. For details on how to use the BoxInsetLayout, refer to the Use a Shape-Aware Layout section in our developer guide.

Without BoxInsetLayout	With BoxInsetLayout

Goodbye WatchViewStub, Hello layout-round!

Developers have been able to specify different layouts for square and round watches using WatchViewStub from the beginning. With Android Wear API 23, this has become even easier. Developers can put different layouts into layout-round and layout folders. Previously with WatchViewStub, developers needed to wait until the layout was inflated before attaching view elements, this added significant complexity to the code. This is eliminated using the -round identifier:

 <?xml version="1.0" encoding="utf-8"?>  
 <android.support.wearable.view.WatchViewStub    
     xmlns:android="http://schemas.android.com/apk/res/android"  
     xmlns:app="http://schemas.android.com/apk/res-auto"  
     xmlns:tools="http://schemas.android.com/tools"  
     android:id="@+id/watch_view_stub"  
     android:layout_width="match_parent"  
     android:layout_height="match_parent"  
     app:rectLayout="@layout/rect_activity_main"  
     app:roundLayout="@layout/round_activity_main"  
     tools:context="com.android.example.watchviewstub.MainActivity"  
     tools:deviceIds="wear"></android.support.wearable.view.WatchViewStub>

  
 protected void onCreate(Bundle savedInstanceState) {  
   super.onCreate(savedInstanceState);  
   setContentView(R.layout.activity_main);  
   final WatchViewStub stub = (WatchViewStub) findViewById(R.id.watch_view_stub);  
   stub.setOnLayoutInflatedListener(new WatchViewStub.OnLayoutInflatedListener() {  
     @Override  
     public void onLayoutInflated(WatchViewStub stub) {  
       mTextView = (TextView) stub.findViewById(R.id.text);  
     }  
   });  
 }  

 protected void onCreate(Bundle savedInstanceState) {  
     super.onCreate(savedInstanceState);  
     setContentView(R.layout.activity_main);  
     mTextView = (TextView) findViewById(R.id.text);    
 }  

That said, since WatchViewStub is part of the Android Wear Support Library, if your current code uses it, it is not a breaking change and you can refactor your code at your convenience. In addition to the -round identifier, developers also use the -notround idenifier to separate resources. So why would you want to use it in place of the default layout? It’s a matter of style. If you have a mixture of layouts, you might consider organising layouts in this way:

• layout/ - Layouts which works for both circular and square watches
• layout-round/ and layout-notround/ - Screen shape specific layouts

An even better way to develop for round - values-round/dimens.xml

Maintaining multiple layout files is potentially painful. Each time you add a screen element, you need to go to all the layout files and add this. With mobile devices, you will usually only do this to specify different layouts for phones and tablets and rarely for different phone resolutions. For watches, unless your screen layout is significantly different between round and square (which is rare based on the applications I have seen thus far), you should consider using different dimens.xml instead.

As I experimented with the -round identifier, I found that the easiest way to build for round and square watches is actually by specifying values/dimens.xml and values-round/dimens.xml. By specifying different padding settings, I am able to create the following layout with the same layout.xml file and two dimens files - one for square and one for round. The values used suits this layout, you should experiment with different values to see what works best:

values-round/dimens.xml	values/dimens.xml
<dimen name="header_start_padding">36dp</dimen>    <dimen name="header_end_padding">22dp</dimen>    <dimen name="list_start_padding">36dp</dimen>    <dimen name="list_end_padding">22dp</dimen>	<dimen name="header_start_padding">16dp</dimen>    <dimen name="header_end_padding">16dp</dimen>    <dimen name="list_start_padding">10dp</dimen>    <dimen name="list_end_padding">10dp</dimen>

Before API 23, to do the same would have involved a significant amount of boilerplate code manually specifying the different dimensions for all elements on the screen. With the -round identifier, this is now easy to do in API 23 and is my favourite way to build round / square layouts.

Don’t forget the chin!

Some watches have an inset (also know as a “chin”) in an otherwise circular screen. So how should you can you build a beautiful layout while keeping your code elegant? Consider this design:

activity_main.xml  <FrameLayout      ...>      <android.support.wearable.view.CircledImageView        android:id="@+id/androidbtn"        android:src="@drawable/ic_android"        .../>      <ImageButton        android:id="@+id/lovebtn"        android:src="@drawable/ic_favourite"        android:paddingTop="5dp"        android:paddingBottom="5dp"        android:layout_gravity="bottom"        .../>    </FrameLayout>

If we are to do nothing, the heart shape button will disappear into the chin. Luckily, there’s an easy way to fix this with fitsSystemWindows:

 <ImageButton  
     android:id="@+id/lovebtn"  
     android:src="@drawable/ic_favourite"  
     android:paddingTop="5dp"  
     android:paddingBottom="5dp"  
    android:fitsSystemWindows="true"  
     .../>  

For the eagle-eyed (middle image of the screen shown below under “fitsSystemWindows=”true””), you might noticed that the top and bottom padding that we have put in is lost. This is one of the main side effect of using fitsSystemWindows. This is because fitsSystemWindows works by overriding the padding to make it fits the system window. So how do we fix this? We can replace padding with InsetDrawables:

 <inset  
   xmlns:android="http://schemas.android.com/apk/res/android"  
   android:drawable="@drawable/ic_favourite" 
   android:insetTop="5dp"  
   android:insetBottom="5dp" />  

 <ImageButton  
     android:id="@+id/lovebtn"  
     android:src="@drawable/inset_favourite"  
     android:paddingTop="5dp"  
     android:paddingBottom="5dp"  
     android:fitsSystemWindows="true"  
     .../>  

Although the padding setting in the layout will be ignored, the code is tidier if we remove this redundant code.

Do nothing	fitsSystemWindows=”true”	fitsSystemWindows=”true” and use InsetDrawable

If you require more control than what is possible declaratively using xml, you can also programmatically adjust your layout. To obtain the size of the chin you should attach a View.OnApplyWindowInsetsListener to the outermost view of your layout. Also don’t forget to call v.onApplyWindowInsets(insets). Otherwise, the new listener will consume the inset and inner elements which react to insets may not react.

 private int mChinSize;  
 protected void onCreate(Bundle savedInstanceState) {  
     super.onCreate(savedInstanceState);  
     setContentView(R.layout.activity_main);  
     // find the outermost element  
     final View container = findViewById(R.id.outer_container);  
     // attach a View.OnApplyWindowInsetsListener  
     container.setOnApplyWindowInsetsListener(new View.OnApplyWindowInsetsListener() {  
         @Override  
         public WindowInsets onApplyWindowInsets(View v, WindowInsets insets) {  
             mChinSize = insets.getSystemWindowInsetBottom();  
             // The following line is important for inner elements which react to insets  
             v.onApplyWindowInsets(insets); 
             return insets;  
     }  
   });  
 }  

Last but not least, remember to test your code! Since last year, we have included several device images for Android Wear devices with a chin to make testing easier and faster:

Square peg in a round hole no more!

Android Wear has always been about empowering users to wear what they want. A major part in enabling this is the round screen. With API 23 and the -round resource identifier, it is easier than ever to build for both round and square watches - delightful experiences backed by beautiful code!

Additional Resources

Why would I want to fitsSystemWindows? by Ian Lake - Best practice for using this powerful tool including its limitations. ScreenInfo Utility by Wayne Piekarski - Get useful information for your display including DPI, chin size, etc.

If you’re an Android Wear developer, we wanted to let you know of a change you might need to make to your app to improve the performance of your user’s devices. If your app is using BIND_LISTENER intent filters in your manifest, it is important that you are aware that this API has been deprecated on all Android versions. The new replacement API introduced in Google Play Services 8.2 is more efficient for Android devices, so developers are encouraged to migrate to this as soon as possible to ensure the best user experience. It is important that all Android Wear developers are aware of this change and update their apps as soon as possible.

Limitations of BIND_LISTENER API

When Android Wear introduced the WearableListenerService, it allowed you to listen to changes via the BIND_LISTENER intent filter in the AndroidManifest.xml. These changes included data item changes, message arrivals, capability changes, and peer connects/disconnects.

The WearableListenerService starts whenever any of these events occur, even if the app is only interested in one type. When a phone has a large number of apps using WearableListenerService and BIND_LISTENER, a watch appearing or disappearing can cause many services to start up. This applies memory pressure to the device, causing other activities and services to be shut down, and generates unnecessary work.

Fine-grained intent filter API

In Google Play Services 8.2, we introduced a new fine-grained intent filter mechanism that allows developers to specify exactly what events they are interested in. For example, if you have multiple listener services, use a path prefix to filter only those data items and messages meant for the service, with syntax like this:

 <service android:name=".FirstExampleService">  
   <intent-filter>  
       <action android:name="com.google.android.gms.wearable.DATA_CHANGED" />  
       <action android:name="com.google.android.gms.wearable.MESSAGE_RECEIVED" />  
       <data android:scheme="wear" android:host="*" android:pathPrefix="/FirstExample" />  
   </intent-filter>  
 </service>  

There are intent filters for DATA_CHANGED, MESSAGE_RECEIVED, CHANNEL_EVENT, and CAPABILITY_CHANGED. You can specify multiple elements, and if any of them match, it will call your service and filter out anything else. If you do not include a element, all events will be filtered out and your service will never be called, so make sure to include at least one. You should be aware that registering in an AndroidManifest.xml for CAPABILITY_CHANGED will cause your service to be called any time a device advertising this capability appears or disappears, so you should use this only if there is a compelling reason.

Live listeners

If you only need these events when an Activity or Service is running, then there is no need to register a listener in AndroidManifest.xml at all. Instead, you can use addListener() live listeners, which will only be active when the Activity or Service is running, and will not impact the device otherwise. This is particularly useful if you want to do live status updates for capabilities being available in an Activity, but with no further background impact. In general, you should try to use addListener(), and only use AndroidManifest.xml when you need to receive events all the time.

Best practices

In general, you should only use a listener in AndroidManifest.xml for events that must launch your service. For example, if your watch app needs to send an interactive message or data to the phone.

You should try to limit the number of wake-ups of your service by using filters. If most of the events do not need to launch your app, then use a path and a filter that only matches the event you need. This is critical to limit the number of launches of your service.

If you have other cases where you do not need to launch a service, such as listening for status updates in an Activity, then register a live listener only for the duration it is needed.

Documentation

There is more information available about Data Layer events and the use of WearableListenerService, and tags in the manifest. Android Studio has a guide with a summary of how to convert to the new API. The Android Wear samples also show best practices in the use of WearableListenerService, such as DataLayer and XYZTouristAttractions. The changes needed are very small, and can be seen in this git diff from one of the samples here.

Removal of BIND_LISTENER

With the release of Android Studio 2.1, lint rules have been added that flag the use of BIND_LISTENER as a fatal error, and developers will need to make a small change to the AndroidManifest.xml to declare accurate intent filters. If you are still using BIND_LISTENER, you will receive the following error:

 AndroidManifest.xml:11: Error: The com.google.android.gms.wearable.BIND_LISTENER action is deprecated. [WearableBindListener]  
          <action android:name="com.google.android.gms.wearable.BIND_LISTENER" />  
              ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~  

This will only impact developers who are recompiling their apps with Android Studio 2.1 and will not affect existing apps on user’s devices.

For developers who are using Google Play Services earlier than 8.2, the lint rules will not generate an error, but you should update to a newer version and implement more accurate intent filters as soon as possible.

In order to give users the best experience, we plan to disable BIND_LISTENER in the near future. It is therefore important that developers take action now, to avoid any future disruption experienced by users of their apps.