Merge "docs: Update JavaDoc links for Watch Face class." into mnc-preview-docs

  <li><a href="#WearableActivity">Create a Wearable Configuration Activity</a></li>

  <li><a href="#CompanionActivity">Create a Companion Configuration Activity</a></li>

</ol>

<h2>Related Samples</h2>

<ul>

<li><a href="{@docRoot}samples/WatchFace/index.html">

WatchFace</a></li>

</ul>

<h2>You should also read</h2>

<ul>

  <li><a href="{@docRoot}design/wear/watchfaces.html">Watch Faces for Android Wear</a></li>

wearable configuration activity on the wearable device, and they can start the companion

configuration activity from the Android Wear companion app.</p>

<p>The digital watch face from the <em>WatchFace</em> sample in the Android SDK demonstrates how to

<p>The digital watch face from the

<a href="{@docRoot}samples/WatchFace/index.html">WatchFace</a> sample demonstrates how to

implement handheld and wearable configuration activities and how to update a watch face in

response to configuration changes. This sample is located in the

<code>android-sdk/samples/android-21/wearable/WatchFace</code> directory.</p>

response to configuration changes.</p>

communicate the configuration change to the watch face activity.</p>

<p>For more details, see the <code>DigitalWatchFaceWearableConfigActivity</code> and

<code>DigitalWatchFaceUtil</code> classes in the <em>WatchFace</em> sample.</p>

<code>DigitalWatchFaceUtil</code> classes in the

<a href="{@docRoot}samples/WatchFace/index.html">WatchFace</a> sample.</p>

communicate the configuration change to the watch face activity.</p>

<p>For more details, see the <code>DigitalWatchFaceCompanionConfigActivity</code> class in the

<em>WatchFace</em> sample.</p>

<a href="{@docRoot}samples/WatchFace/index.html">WatchFace</a> sample.</p>

<h2 id="Listener">Create a Listener Service in the Wearable App</h2>

<p>To receive updated configuration parameters from the configuration activities, create a

service that implements the <code>WearableListenerService</code> interface from the <a

href="{@docRoot}training/wearables/data-layer/index.html">Wearable Data Layer API</a> in your

service that implements the

<a href="//developers.google.com/android/reference/com/google/android/gms/wearable/WearableListenerService"><code>WearableListenerService</code></a>

interface from the

<a href="{@docRoot}training/wearables/data-layer/index.html">Wearable Data Layer API</a> in your

wearable app. Your watch face implementation can redraw the watch face when the configuration

parameters change.</p>

<p>For more details, see the <code>DigitalWatchFaceConfigListenerService</code> and

<code>DigitalWatchFaceService</code> classes in the <em>WatchFace</em> sample.</p>

<code>DigitalWatchFaceService</code> classes in the

<a href="{@docRoot}samples/WatchFace/index.html">WatchFace</a> sample.</p>

  <li><a href="#Experience">Create a Compelling Experience</a></li>

  <li><a href="#AddData">Add Data to Your Watch Face</a></li>

</ol>

<h2>Related Samples</h2>

<ul>

<li><a href="{@docRoot}samples/WatchFace/index.html">

WatchFace</a></li>

</ul>

<h2>You should also read</h2>

<ul>

  <li><a href="{@docRoot}design/wear/watchfaces.html">Watch Faces for Android Wear</a></li>

<p class="img-caption"><strong>Figure 2.</strong> The calendar watch face.</p>

</div>

<p>The <em>WatchFace</em> sample in the Android SDK demonstrates how to obtain calendar data

from the user’s profile in the <code>CalendarWatchFaceService</code> class and shows how many

meetings there are in the following twenty-four hours. This sample is located in the

<code>android-sdk/samples/android-21/wearable/WatchFace</code> directory.</p>

<p>The

<a href="{@docRoot}samples/WatchFace/index.html">WatchFace</a>

sample demonstrates how to obtain calendar data from the user’s profile in the

<code>CalendarWatchFaceService</code> class and shows how many

meetings there are in the following twenty-four hours.</p>

<p>To implement a watch face that incorporates contextual data, follow these steps:</p>

<h3 id="Task">Provide a task to retrieve data</h3>

<p>Create a class inside your <code>CanvasWatchFaceService.Engine</code> implementation that

extends {@link android.os.AsyncTask} and add the code to retrieve the data you’re interested

in.</p>

<p>Create a class inside your

<a href="{@docRoot}reference/android/support/wearable/watchface/CanvasWatchFaceService.Engine.html"><code>CanvasWatchFaceService.Engine</code></a>

implementation that extends {@link android.os.AsyncTask} and add the code to retrieve the data

you’re interested in.</p>

<p>The <code>CalendarWatchFaceService</code> class obtains the number of meetings in the next

day as follows:</p>

}

</pre>

<p>The <code>WearableCalendarContract</code> class from the Wearable Support Library provides

direct access to the user's calendar events from the companion device.</p>

<p>The

<a href="{@docRoot}reference/android/support/wearable/provider/WearableCalendarContract.html"><code>WearableCalendarContract</code></a>

class from the Wearable Support Library provides direct access to the user's calendar events from

the companion device.</p>

<p>When the task finishes retrieving data, your code invokes a callback method. The following

sections describe how to implement the callback method in detail.</p>

<h3 id="Redraw">Redraw your watch face with the updated data</h3>

<p>When the task that retrieves your data finishes, call the <code>invalidate()</code> method

so the system redraws your watch face. Store your data inside member variables of the

<code>Engine</code> class so you can access it inside the <code>onDraw()</code> method.</p>

<p>When the task that retrieves your data finishes, call the

<a href="{@docRoot}reference/android/support/wearable/watchface/CanvasWatchFaceService.Engine.html#invalidate()"><code>invalidate()</code></a>

method so the system redraws your watch face. Store your data inside member variables of the

<code>Engine</code> class so you can access it inside the

<a href="{@docRoot}reference/android/support/wearable/watchface/CanvasWatchFaceService.Engine.html#onDraw(android.graphics.Canvas, android.graphics.Rect)"><code>onDraw()</code></a>

method.</p>

<p>The <code>CalendarWatchFaceService</code> class provides a callback method for the task to

invoke when it finishes retrieving calendar data:</p>

<a href="{@docRoot}design/wear/watchfaces.html">design guidelines</a>.</p>

<p>Android Wear lets your watch face determine the screen shape at runtime. To detect whether

the screen is square or round, override the <code>onApplyWindowInsets()</code> method in the

<code>CanvasWatchFaceService.Engine</code> class as follows:</p>

the screen is square or round, override the

<a href="{@docRoot}reference/android/service/wallpaper/WallpaperService.Engine.html#onApplyWindowInsets(android.view.WindowInsets)"><code>onApplyWindowInsets()</code></a>

method in the

<a href="{@docRoot}reference/android/support/wearable/watchface/CanvasWatchFaceService.Engine.html"><code>CanvasWatchFaceService.Engine</code></a>

class as follows:</p>

<pre>

private class Engine extends CanvasWatchFaceService.Engine {

down the watch face to fit inside the portion of the screen not covered by the peek card. Digital

watch faces that display the time in the area of the screen not covered by peek cards do not

usually require adjustments. To determine the free space above the peek card so you can adapt

your watch face, use the <code>WatchFaceService.getPeekCardPosition()</code> method.</p>

your watch face, use the

<a href="{@docRoot}reference/android/support/wearable/watchface/WatchFaceService.Engine.html#getPeekCardPosition()"><code>WatchFaceService.Engine.getPeekCardPosition()</code></a>

method.</p>

<p>In ambient mode, peek cards have a transparent background. If your watch face contains details

near the card in ambient mode, consider drawing a black rectangle over them to ensure that users

</div>

<p>To ensure that the system indicators remain visible, you can configure their position on the

screen and whether they need background protection when you create a <code>WatchFaceStyle</code>

screen and whether they need background protection when you create a

<a href="{@docRoot}reference/android/support/wearable/watchface/WatchFaceStyle.html"><code>WatchFaceStyle</code></a>

instance:</p>

<ul>

<li>To set the position of the status bar, use the <code>setStatusBarGravity()</code> method.</li>

<li>To set the position of the hotword, use the <code>setHotwordIndicatorGravity()</code>

<li>To set the position of the status bar, use the

<a href="{@docRoot}reference/android/support/wearable/watchface/WatchFaceStyle.Builder.html#setStatusBarGravity(int)"><code>setStatusBarGravity()</code></a>

method.</li>

<li>To set the position of the hotword, use the

<a href="{@docRoot}reference/android/support/wearable/watchface/WatchFaceStyle.Builder.html#setHotwordIndicatorGravity(int)"><code>setHotwordIndicatorGravity()</code></a>

method.</li>

<li>To protect the status bar and hotword with a semi-transparent gray background, use the

<code>setViewProtection()</code> method. This is usually necessary if your watch face has a

light background, since the system indicators are white.</li>

<a href="{@docRoot}reference/android/support/wearable/watchface/WatchFaceStyle.Builder.html#setViewProtection(int)"><code>setViewProtection()</code></a>

method. This is usually necessary if your watch face has a light background, since the system

indicators are white.</li>

</ul>

<p>For more information about the system indicators, see <a

<p>Many watch faces consist of a background image and other graphic assets that are transformed

and overlapped on top of the background image, such as clock hands and other elements of the design

that move over time. Typically these graphic elements are rotated (and sometimes scaled) inside the

<code>Engine.onDraw()</code> method every time the system redraws the watch face, as described in

<a href="{@docRoot}reference/android/support/wearable/watchface/CanvasWatchFaceService.Engine.html#onDraw(android.graphics.Canvas, android.graphics.Rect)"><code>Engine.onDraw()</code></a>

method every time the system redraws the watch face, as described in

<a href="{@docRoot}training/wearables/watch-faces/drawing.html#Drawing">Draw Your Watch

Face</a>.</p>

<p>The larger these graphic assets are, the more computationally expensive it is to transform them.

Transforming large graphic assets in the <code>Engine.onDraw()</code> method drastically reduces

the frame rate at which the system can run your animations.</p>

Transforming large graphic assets in the

<a href="{@docRoot}reference/android/support/wearable/watchface/CanvasWatchFaceService.Engine.html#onDraw(android.graphics.Canvas, android.graphics.Rect)"><code>Engine.onDraw()</code></a>

method drastically reduces the frame rate at which the system can run your animations.</p>

<div id="fig1" style="float:right;width:250px;margin-left:25px">

<img src="{@docRoot}training/wearables/watch-faces/images/ClockHandFull.png" alt=""

<h2 id="OutDrawing">Move Expensive Operations Outside the Drawing Method</h2>

<p>The system calls the <code>Engine.onDraw()</code> method every time it redraws your watch

face, so you should only include operations that are strictly required to update the watch

face inside this method to improve performance.<p>

<p>The system calls the

<a href="{@docRoot}reference/android/support/wearable/watchface/CanvasWatchFaceService.Engine.html#onDraw(android.graphics.Canvas, android.graphics.Rect)"><code>Engine.onDraw()</code></a>

method every time it redraws your watch face, so you should only include operations that are

strictly required to update the watch face inside this method to improve performance.<p>

<p>When possible, avoid performing these operations inside the <code>onDraw()</code> method:</p>

<p>When possible, avoid performing these operations inside the

<a href="{@docRoot}reference/android/support/wearable/watchface/CanvasWatchFaceService.Engine.html#onDraw(android.graphics.Canvas, android.graphics.Rect)"><code>Engine.onDraw()</code></a>

method:</p>

<ul>

<li>Loading images and other resources.</li>

<li>Performing computations whose result does not change between frames.</li>

</ul>

<p>You can usually perform these operations in the <code>Engine.onCreate()</code> method instead.

<p>You can usually perform these operations in the

<a href="{@docRoot}reference/android/support/wearable/watchface/WatchFaceService.Engine.html#onCreate(android.view.SurfaceHolder)"><code>Engine.onCreate()</code></a>

method instead.

You can resize images ahead of time in the {@link

android.service.wallpaper.WallpaperService.Engine#onSurfaceChanged(android.view.SurfaceHolder, int, int, int)

Engine.onSurfaceChanged()} method, which provides you with the size of the canvas.</p>

<p>To analyze the performance of your watch face, use the Android Device Monitor. In particular,

ensure that the execution time for your <code>Engine.onDraw()</code> implementation is short and

ensure that the execution time for your

<a href="{@docRoot}reference/android/support/wearable/watchface/CanvasWatchFaceService.Engine.html#onDraw(android.graphics.Canvas, android.graphics.Rect)"><code>Engine.onDraw()</code></a>

implementation is short and

consistent across invocations. For more information, see

<a href="{@docRoot}tools/debugging/ddms.html">Using DDMS</a>.</p>

  <li><a href="#CallbackMethods">Implement the Service Callback Methods</a></li>

  <li><a href="#RegisterService">Register the Service Implementation</a></li>

</ol>

<h2>Related Samples</h2>

<ul>

<li><a href="{@docRoot}samples/WatchFace/index.html">

WatchFace</a></li>

</ul>

<h2>You should also read</h2>

<ul>

  <li><a href="{@docRoot}design/wear/watchfaces.html">Watch Faces for Android Wear</a></li>

<h3 id="Dependencies">Dependencies</h3>

<p>The Wearable Support Library provides the necessary classes that you extend to create watch

<p>The

<a href="{@docRoot}reference/android/support/wearable/watchface/package-summary.html">Wearable Support Library</a>

provides the necessary classes that you extend to create watch

face implementations. The Google Play services client libraries (<code>play-services</code> and

<code>play-services-wearable</code>) are required to sync data items between the companion device

and the wearable with the <a href="{@docRoot}training/wearables/data-layer/index.html">Wearable

notification). The service implementation then draws the watch face on the screen using the

updated time and any other relevant data.</p>

<p>To implement a watch face, you extend the <code>CanvasWatchFaceService</code>

and <code>CanvasWatchFaceService.Engine</code> classes, and then you override the callback methods

in the <code>CanvasWatchFaceService.Engine</code> class. These classes are included in the

Wearable Support Library.</p>

<p>To implement a watch face, you extend the

<a href="{@docRoot}reference/android/support/wearable/watchface/CanvasWatchFaceService.html"><code>CanvasWatchFaceService</code></a>

and

<a href="{@docRoot}reference/android/support/wearable/watchface/CanvasWatchFaceService.Engine.html"><code>CanvasWatchFaceService.Engine</code></a>

classes, and then you override the callback methods in the

<a href="{@docRoot}reference/android/support/wearable/watchface/CanvasWatchFaceService.Engine.html"><code>CanvasWatchFaceService.Engine</code></a>

class. These classes are included in the

<a href="{@docRoot}reference/android/support/wearable/watchface/package-summary.html">Wearable Support Library</a>.

</p>

<p>The following snippet outlines the key methods you need to implement:</p>

}

</pre>

<p class="note"><strong>Note:</strong> The <em>WatchFace</em> sample in the Android SDK

demonstrates how to implement analog and digital watch faces extending the

<code>CanvasWatchFaceService</code> class. This sample is located in the

<code>android-sdk/samples/android-21/wearable/WatchFace</code> directory.</p>

<p>The <code>CanvasWatchFaceService</code> class provides an invalidate mechanism similar to

<p>The

<a href="{@docRoot}reference/android/support/wearable/watchface/CanvasWatchFaceService.html"><code>CanvasWatchFaceService</code></a>

class provides an invalidate mechanism similar to

the {@link android.view.View#invalidate View.invalidate()} method. You can call the

<code>invalidate()</code> method throughout your implementation when you want the system to

redraw the watch face. You can only use the <code>invalidate()</code> method in the main UI

thread. To invalidate the canvas from another thread, call the <code>postInvalidate()</code>

<a href="{@docRoot}reference/android/support/wearable/watchface/CanvasWatchFaceService.Engine.html#invalidate()"><code>invalidate()</code></a>

method throughout your implementation when

you want the system to redraw the watch face. You can only use the

<a href="{@docRoot}reference/android/support/wearable/watchface/CanvasWatchFaceService.Engine.html#invalidate()"><code>invalidate()</code></a>

method in the main UI thread. To invalidate the canvas from another thread, call the

<a href="{@docRoot}reference/android/support/wearable/watchface/CanvasWatchFaceService.Engine.html#postInvalidate()"><code>postInvalidate()</code></a>

method.</p>

<p>For more information about implementing the methods in the

<code>CanvasWatchFaceService.Engine</code> class, see <a

<a href="{@docRoot}reference/android/support/wearable/watchface/CanvasWatchFaceService.Engine.html"><code>CanvasWatchFaceService.Engine</code></a>

class, see <a

href="{@docRoot}training/wearables/watch-faces/drawing.html">Drawing Watch Faces</a>.</p>