Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
Luan Nguyen
2015-06-17 14:55:43 +00:00
committed by Android (Google) Code Review
parent 5980ae8f06 cce9c74f4e
commit 5cef09b075
5 changed files with 105 additions and 52 deletions
Download Patch File Download Diff File Expand all files Collapse all files

25
docs/html/training/wearables/watch-faces/configuration.jd
View File

@@ -10,6 +10,11 @@ page.title=Providing Configuration Activities
<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>
@@ -34,10 +39,10 @@ an activity in the wearable app, an activity on the handheld app, or both. Users
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>
@@ -107,7 +112,8 @@ href="{@docRoot}training/wearables/data-layer/index.html">Wearable Data Layer AP
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>
@@ -141,17 +147,20 @@ href="{@docRoot}training/wearables/data-layer/index.html">Wearable Data Layer AP
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>

36
docs/html/training/wearables/watch-faces/information.jd
View File

@@ -9,6 +9,11 @@ page.title=Showing Information in Watch Faces
<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>
@@ -77,10 +82,11 @@ weather.</p>
<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>
@@ -95,9 +101,10 @@ meetings there are in the following twenty-four hours. This sample is located in
<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>
@@ -130,8 +137,10 @@ private class LoadMeetingsTask extends AsyncTask&lt;Void, Void, Integer> {
}
</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>
@@ -189,9 +198,12 @@ section.</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>

26
docs/html/training/wearables/watch-faces/issues.jd
View File

@@ -31,8 +31,11 @@ should adapt to and take advantage of the particular shape of the screen, as des
<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 {
@@ -75,7 +78,9 @@ the notification card is present.</p>
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
@@ -93,16 +98,21 @@ can read the contents of the card.</p>
</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

27
docs/html/training/wearables/watch-faces/performance.jd
View File

@@ -34,13 +34,15 @@ power on the device.</p>
<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=""
@@ -105,11 +107,14 @@ active, disable bitmap filtering.</p>
<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>
@@ -118,13 +123,17 @@ face inside this method to improve performance.<p>
<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>

43
docs/html/training/wearables/watch-faces/service.jd
View File

@@ -10,6 +10,11 @@ page.title=Building a Watch Face Service
<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>
@@ -64,7 +69,9 @@ Project</a>.</p>
<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
@@ -116,10 +123,15 @@ or when an important event occurs (like switching to ambient mode or receiving a
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>
@@ -173,20 +185,21 @@ public class AnalogWatchFaceService extends CanvasWatchFaceService {
}
</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>