docs/html/training/wearables/apps/layouts.jd

page.title=Creating Custom Layouts

@jd:body

<div id="tb-wrapper">
<div id="tb">

<h2>This lesson teaches you to</h2>
<ol>
  <li><a href="#CustomNotifications">Create custom notifications</a></li>
  <li><a href="#UiLibrary">Create Layouts with the Wearable UI Library</li>
</ol>

<h2>You should also read</h2>
<ul>
  <li><a href="{@docRoot}design/wear/index.html">Android Wear Design Principles</a></li>
</ul>

</div>
</div>

<p>Creating layouts for wearables is the same as handheld devices, except you have to design
for the screen size and for glanceability. Do not port functionality
and the UI from a handheld app and expect a good experience. You should create custom layouts
only when necessary. Read the <a href="{@docRoot}design/wear/index.html">design guidelines</a>
for information on how to design great wearable apps.</p>

<h2 id="CustomNotifications">Create Custom Notifications</h2>

<p>
In general, you should create notifications on the handheld and let them
automatically sync to the wearable. This lets you build your notifications
once and have them appear on many types of devices (not just wearables, but
eventually Auto and TV) without having to design them for different
form factors.</p>

<p>If the standard notification styles don't work for you (such as
{@link android.support.v4.app.NotificationCompat.BigTextStyle} or
{@link android.support.v4.app.NotificationCompat.InboxStyle}), you can display an activity with
a custom layout. You can only create and issue custom notifications on the wearable, and the
system does not sync these notifications to the handheld.</p>

<p clas="note"><b>Note:</b> When creating custom notifications on the wearable, you can use the
standard notification APIs (API Level 20) instead of the Support Library.
</p>

<p>To create a custom notification:</p>
<ol>
  <li>Create a layout and set it as the content view for the activity
  that you want to display.
<pre>
public void onCreate(Bundle bundle){
    ...
    setContentView(R.layout.notification_activity);
}
</pre>
  </li>
  <li>Define necessary properties for the activity in the Android manifest to allow
  the activity to be displayed in the wearable's context stream process. You need to declare the
  activity to be exportable, be embeddable, and have an empty task affinity. We also recommend
  setting the theme to <code>Theme.DeviceDefault.Light</code>. For example:</li>
<pre>
&lt;activity android:name="com.example.MyDisplayActivity"
     android:exported="true"
     android:allowEmbedded="true"
     android:taskAffinity=""
     android:theme="@android:style/Theme.DeviceDefault.Light" /&gt;
</pre>
  </li>
  <li>Create a {@link android.app.PendingIntent} for the activity that you want to display.
  For example:
<pre>
Intent notificationIntent = new Intent(this, NotificationActivity.class);
PendingIntent notificationPendingIntent = PendingIntent.getActivity(this, 0, notificationIntent,
        PendingIntent.FLAG_UPDATE_CURRENT);
</pre>
  </li>
  <li>Build a {@link android.app.Notification} and call
  {@link android.app.Notification.WearableExtender#setDisplayIntent setDisplayIntent()}
  providing the {@link android.app.PendingIntent}. The system uses this
  {@link android.app.PendingIntent} to launch the activity when
  users view your notification.
  </li>
  <li>Issue the notification using the
  {@link android.app.NotificationManager#notify notify()} method.
  <p class="note"><b>Note:</b> When the notification is peeking on the homescreen, the system
  displays it with a standard template that it generates from the notification's semantic data. This template works well on all watchfaces. When users swipe the notification up, they'll then see the
  custom activity for the notification.</p>
  </li>
</ol>
<h2 id="UiLibrary">Create Layouts with the Wearable UI Library</h2>
<p>
There's an unofficial UI library that is automatically included when you create your wearable
app with the Android Studio Project Wizard. You can also add the library to your <code>build.gradle</code>
file with the following dependency declaration:

<pre>
dependencies {
    compile fileTree(dir: 'libs', include: ['*.jar'])
    <b>compile 'com.google.android.support:wearable:+'</b>
    compile 'com.google.android.gms:play-services-wearable:+'
}
</pre>
This library helps you build UIs that are designed for wearables. Here are some of the major classes:
</p>

<ul>
    <li><code>BoxInsetLayout</code> - A FrameLayout that's aware of screen shape and can box its
    children in the center square of a round screen.</li>
    <li><code>CardFragment</code> - A fragment that presents content within an expandable,
    vertically scrollable card.</li>
    <li><code>CircledImageView</code> - An image view surrounded by a circle.</li>
    <li><code>ConfirmationActivity</code> - An activity that displays confirmation animations after the user
    completes an action.</li>
    <li><code>DismissOverlayView</code> - A view for implementing long-press-to-dismiss.</li>
    <li><code>GridViewPager</code> - A layout manager that allows the user to both vertically and
    horizontally through pages of data. You supply an implementation of a GridPagerAdapter to
    generate the pages that the view shows.</li>
    <li><code>GridPagerAdapter</code> - An adapter that supplies pages to a GridViewPager.</li>
    <li><code>FragmentGridPagerAdapter</code> - An implementation of GridPagerAdapter that
    represents each page as a fragment.</li>
    </li>
    <li><code>WatchViewStub</code> - A class that can inflate a specific layout,
    depending on the shape of the device's screen.</li>
    <li><code>WearableListView</code> - An alternative version of ListView that is optimized for
    ease of use on small screen wearable devices. It displays a vertically scrollable list of items,
    and automatically snaps to the nearest item when the user stops scrolling.
    </li>
</ul>

<p class="note"><a href="{@docRoot}shareables/training/wearable-support-docs.zip">Download the full API
reference documentation</a> for the classes above. The documentation goes over how to use
each UI widget.</p>