Merge "docs: Fix WatchFace guide to no longer reference deprecated Time.java...

<ul>

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

</ul>

<h2>Related Samples</h2>

  <ul>

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

  </ul>

</div>

</div>

<p>After you have configured your project and added a class that implements the watch

face service, you can start writing code to initialize and draw your custom watch face.</p>

<p>This lesson explains how the system invokes the methods in the

watch face service using examples from the <em>WatchFace</em> sample

included in the Android SDK. This sample is located in the

<code>android-sdk/samples/android-21/wearable/WatchFace</code> directory. Many aspects of the

service implementations described here (such as initialization and detecting device features)

<p>This lesson includes examples from the

<a href="{@docRoot}samples/WatchFace/index.html">WatchFace</a> sample to show how the system uses

the watch face service. Many aspects of the

service implementations described here (such as initialization and device features detection)

apply to any watch face, so you can reuse some of the code in your own watch faces.</p>

     width="180" height="180" alt="" style="margin-left:25px;margin-top:12px"/>

<p class="img-caption">

<strong>Figure 1.</strong> The analog and digital watch faces in

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

the

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

<h2 id="Initialize">Initialize Your Watch Face</h2>

<ol>

<li>Declare variables for a custom timer, graphic objects, and other elements.</li>

<li>Initialize the watch face elements in the <code>Engine.onCreate()</code> method.</li>

<li>Initialize the custom timer in the <code>Engine.onVisibilityChanged()</code> method.</li>

<li>Initialize the watch face elements in the

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

method.</li>

<li>Initialize the custom timer in the

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

method.</li>

</ol>

<p>The following sections describe these steps in detail.</p>

<p>The resources that you intialize when the system loads your service need to be accessible

at different points throughout your implementation, so you can reuse them. You achieve this

by declaring member variables for these resources in your <code>WatchFaceService.Engine</code>

by declaring member variables for these resources in your

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

implementation.</p>

<p>Declare variables for the following elements:</p>

zone changes and update the time accordingly.</dd>

</dl>

<p>The <code>AnalogWatchFaceService.Engine</code> class in the <em>WatchFace</em> sample defines

these variables as shown in the snippet below. The custom timer is implemented as a

{@link android.os.Handler} instance that sends and processes delayed messages using the thread's

message queue. For this particular watch face, the custom timer ticks once every second. When the

timer ticks, the handler calls the <code>invalidate()</code> method and the system then calls

the <code>onDraw()</code> method to redraw the watch face.</p>

<p>The following snippet shows how to define these variables:</p>

<pre>

private class Engine extends CanvasWatchFaceService.Engine {

    static final int MSG_UPDATE_TIME = 0;

    /* a time object */

    Time mTime;

    Calendar mCalendar;

    /* device features */

    // device features

    boolean mLowBitAmbient;

    /* graphic objects */

    // graphic objects

    Bitmap mBackgroundBitmap;

    Bitmap mBackgroundScaledBitmap;

    Paint mHourPaint;

    Paint mMinutePaint;

    ...

    /* handler to update the time once a second in interactive mode */

    // handler to update the time once a second in interactive mode

    final Handler mUpdateTimeHandler = new Handler() {

        @Override

        public void handleMessage(Message message) {

        }

    };

    /* receiver to update the time zone */

    // receiver to update the time zone

    final BroadcastReceiver mTimeZoneReceiver = new BroadcastReceiver() {

        @Override

        public void onReceive(Context context, Intent intent) {

            mTime.clear(intent.getStringExtra("time-zone"));

            mTime.setToNow();

            mCalendar.setTimeZone(TimeZone.getDefault());

            invalidate();

        }

    };

    /* service methods (see other sections) */

    // service methods (see other sections)

    ...

}

</pre>

<p>In the example above, the custom timer is implemented as a

{@link android.os.Handler} instance that sends and processes delayed messages using the thread's

message queue. For this particular watch face, the custom timer ticks once every second. When the

timer ticks, the handler calls the

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

method and the system then calls the

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

method to redraw the watch face.</p>

<h3 id="InitializeElements">Initialize watch face elements</h3>

<p>After you have declared member variables for bitmap resources, paint styles, and other

elements that you reuse every time your redraw your watch face, initialize them when the system

<p>After declaring member variables for bitmap resources, paint styles, and other

elements that you reuse every time you redraw your watch face, initialize them when the system

loads your service. Initializing these elements only once and reusing them improves performance

and battery life.</p>

<p>In the <code>Engine.onCreate()</code> method, initialize the following elements:</p>

<p>In the

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

method, initialize the following elements:</p>

<ul>

<li>Load the background image.</li>

<li>Create styles and colors to draw graphic objects.</li>

<li>Allocate an object to hold the time.</li>

<li>Allocate an object to calculate the time.</li>

<li>Configure the system UI.</li>

</ul>

<p>The <code>Engine.onCreate()</code> method in the <code>AnalogWatchFaceService</code> class

initializes these elements as follows:</p>

<p>The following snippet shows how to initialize these elements:</p>

<pre>

@Override

public void onCreate(SurfaceHolder holder) {

    super.onCreate(holder);

    /* configure the system UI (see next section) */

    // configure the system UI (see next section)

    ...

    /* load the background image */

    // load the background image

    Resources resources = AnalogWatchFaceService.this.getResources();

    Drawable backgroundDrawable = resources.getDrawable(R.drawable.bg);

    Drawable backgroundDrawable = resources.getDrawable(R.drawable.bg, null);

    mBackgroundBitmap = ((BitmapDrawable) backgroundDrawable).getBitmap();

    /* create graphic styles */

    // create graphic styles

    mHourPaint = new Paint();

    mHourPaint.setARGB(255, 200, 200, 200);

    mHourPaint.setStrokeWidth(5.0f);

    mHourPaint.setStrokeCap(Paint.Cap.ROUND);

    ...

    /* allocate an object to hold the time */

    mTime = new Time();

    // allocate a Calendar to calculate local time using the UTC time and time zone

    mCalendar = Calendar.getInstance();

}

</pre>

<p>The background bitmap is loaded only once when the system initializes the watch face. The

graphic styles are instances of the {@link android.graphics.Paint} class. You later use these

styles to draw the elements of your watch face inside the <code>Engine.onDraw()</code> method,

as described in <a href="#Drawing">Drawing Your Watch Face</a>.</p>

graphic styles are instances of the {@link android.graphics.Paint} class. Use these

styles to draw the elements of your watch face 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, as described in <a href="#Drawing">Drawing Your Watch Face</a>.</p>

<h3 id="Timer">Initialize the custom timer</h3>

<p>An example timer definition from the <code>AnalogWatchFaceService</code> class that ticks once

every second is shown in <a href="#Variables">Declare variables</a>. In the

<code>Engine.onVisibilityChanged()</code> method, start the custom timer if these two

conditions apply:</p>

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

method, start the custom timer if these two conditions apply:</p>

<ul>

<li>The watch face is visible.</li>

<p>This custom timer ticks once every second, as described in <a href="#Variables">Declare

variables</a>.</p>

<p>In the <code>Engine.onVisibilityChanged()</code> method, start the timer if required and

and register the receiver for time zone changes as follows:</p>

<p>In the

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

method, start the timer if required and register the receiver for time zone changes as follows:

</p>

<pre>

@Override

        registerReceiver();

        // Update time zone in case it changed while we weren't visible.

        mTime.clear(TimeZone.getDefault().getID());

        mTime.setToNow();

        mCalendar.setTimeZone(TimeZone.getDefault());

    } else {

        unregisterReceiver();

    }

    // Whether the timer should be running depends on whether we're visible and

    // whether we're in ambient mode), so we may need to start or stop the timer

    // whether we're in ambient mode, so we may need to start or stop the timer

    updateTimer();

}

</pre>

<p>When the watch face is visible, the <code>onVisibilityChanged()</code> method registers

the receiver for time zone changes and starts the custom timer if the device is in interactive

mode. When the watch face is not visible, this method stops the custom timer and unregisters

the receiver for time zone changes. The <code>registerReceiver()</code> and

<code>unregisterReceiver()</code> methods are implemented as follows:</p>

<p>When the watch face is visible, the

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

method registers the receiver for time zone changes. If the device is in interactive mode, this

method also starts the custom timer. When the watch face is not visible, this

method stops the custom timer and unregisters the receiver for time zone changes.

The <code>registerReceiver()</code> and <code>unregisterReceiver()</code> methods are implemented as

follows:</p>

<pre>

private void registerReceiver() {

<h3 id="TimeTick">Update the watch face in ambient mode</h3>

<p>In ambient mode, the system calls the <code>Engine.onTimeTick()</code> method every minute.

It is usually sufficient to update your watch face once per minute in this mode. To update your

watch face while in interactive mode, you must provide a custom timer as described in

<a href="#Timer">Initialize the custom timer</a>.</p>

<p>In ambient mode, the system calls the

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

method every minute. It is usually sufficient to update your watch face once per minute in this

mode. To update your watch face while in interactive mode, you must provide a custom timer as

described in <a href="#Timer">Initialize the custom timer</a>.</p>

<p>In ambient mode, most watch face implementations simply invalidate the canvas to redraw the watch

face in the <code>Engine.onTimeTick()</code> method:</p>

face in the

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

method:</p>

<pre>

@Override

<li>Specify the positioning of the system indicators.</li>

</ul>

<p>To configure these aspects of the system UI, create a <code>WatchFaceStyle</code> instance

and pass it to the <code>Engine.setWatchFaceStyle()</code> method.</p>

<p>To configure these aspects of the system UI, create a

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

instance and pass it to the

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

method.</p>

<p>The <code>AnalogWatchFaceService</code> class configures the system UI as follows:</p>

public void onCreate(SurfaceHolder holder) {

    super.onCreate(holder);

    /* configure the system UI */

    // configure the system UI

    setWatchFaceStyle(new WatchFaceStyle.Builder(AnalogWatchFaceService.this)

            .setCardPeekMode(WatchFaceStyle.PEEK_MODE_SHORT)

            .setBackgroundVisibility(WatchFaceStyle

system indicators.</p>

<p>For more details about configuring the system UI, see the

<a href="{@docRoot}shareables/training/wearable-support-docs.zip">API reference</a> for the

<code>WatchFaceStyle</code> class.</p>

<a href="{@docRoot}reference/packages-wearable-support.html">Wear API reference documentation</a>.

</p>

<h2 id="Screen">Obtain Information About the Device Screen</h2>

<p>The system calls the <code>Engine.onPropertiesChanged()</code> method when it determines

the properties of the device screen, such as whether the device uses low-bit ambient mode and

whether the screen requires burn-in protection.</p>

<p>The system calls the

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

method when it determines the properties of the device screen, such as whether the device uses

low-bit ambient mode and whether the screen requires burn-in protection.</p>

<p>The following code snippet shows how to obtain these properties:</p>

<h2 id="Modes">Respond to Changes Between Modes</h2>

<p>When the device switches between ambient and interactive modes, the system calls the

<code>Engine.onAmbientModeChanged()</code> method. Your service implementation should make

any necessary adjustments to switch between modes and then call the <code>invalidate()</code>

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

method. Your service implementation should make any necessary adjustments to switch between modes

and then call the

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

method for the system to redraw the watch face.</p>

<p>The following snippet shows how this method is implemented in the

<code>AnalogWatchFaceService</code> class inside the <em>WatchFace</em> sample:</p>

<p>The following snippet shows how to implement this method:</p>

<pre>

@Override

<h2 id="Drawing">Draw Your Watch Face</h2>

<p>To draw a custom watch face, the system calls the <code>Engine.onDraw()</code> method with a

{@link android.graphics.Canvas} instance and the bounds in which you should draw your watch face.

The bounds account for any inset areas, such as the "chin" on the bottom of some round devices.

You can use this canvas to draw your watch face directly as follows:</p>

<p>To draw a custom watch face, 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 with a {@link android.graphics.Canvas} instance and the bounds in which you should draw your

watch face. The bounds take into account any inset areas, such as the "chin" on the bottom of some

round devices. You can use this canvas to draw your watch face directly as follows:</p>

<ol>

<li>If this is the first invocation of the <code>onDraw()</code> method, scale your background

to fit.</li>

<li>If this is the first invocation of the

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

method, scale your background to fit.</li>

<li>Check whether the device is in ambient mode or interactive mode.</li>

<li>Perform any required graphic computations.</li>

<li>Draw your background bitmap on the canvas.</li>

<li>Use the methods in the {@link android.graphics.Canvas} class to draw your watch face.</li>

</ol>

<p>The <code>AnalogWatchFaceService</code> class in the <em>WatchFace</em> sample follows these

steps to implement the <code>onDraw()</code> method as follows:</p>

<p>The following snippet shows how to implement 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>

<pre>

@Override

public void onDraw(Canvas canvas, Rect bounds) {

    // Update the time

    mTime.setToNow();

    mCalendar.setTimeInMillis(System.currentTimeMillis());

    // Constant to help calculate clock hand rotations

    final float TWO_PI = (float) Math.PI * 2f;

    int width = bounds.width();

    int height = bounds.height();

        || mBackgroundScaledBitmap.getWidth() != width

        || mBackgroundScaledBitmap.getHeight() != height) {

        mBackgroundScaledBitmap = Bitmap.createScaledBitmap(mBackgroundBitmap,

                                         width, height, true /* filter */);

                                      width, height, true);

    }

    canvas.drawBitmap(mBackgroundScaledBitmap, 0, 0, null);

    float centerY = height / 2f;

    // Compute rotations and lengths for the clock hands.

    float secRot = mTime.second / 30f * (float) Math.PI;

    int minutes = mTime.minute;

    float minRot = minutes / 30f * (float) Math.PI;

    float hrRot = ((mTime.hour + (minutes / 60f)) / 6f ) * (float) Math.PI;

    float seconds = mCalendar.get(Calendar.SECOND) +

                    mCalendar.get(Calendar.MILLISECOND) / 1000f;

    float secRot = seconds / 60f * TWO_PI;

    float minutes = mCalendar.get(Calendar.MINUTE) + seconds / 60f;

    float minRot = minutes / 60f * TWO_PI;

    float hours = mCalendar.get(Calendar.HOUR) + minutes / 60f;

    float hrRot = hours / 12f * TWO_PI;

    float secLength = centerX - 20;

    float minLength = centerX - 40;

<p>This method computes the required positions for the clock hands based on the current time

and draws them on top of the background bitmap using the graphic styles initialized in the

<code>onCreate()</code> method. The second hand is only drawn in interactive mode, not in

ambient mode.</p>

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

method. The second hand is only drawn in interactive mode, not in ambient mode.</p>

<p>For more information about drawing on a Canvas instance, see <a

href="{@docRoot}guide/topics/graphics/2d-graphics.html">Canvas and Drawables</a>.</p>

<p>The <em>WatchFace</em> sample in the Android SDK includes additional watch faces that you

can refer to as examples of how to implement the <code>onDraw()</code> method.</p>

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

watch faces that you can refer to as examples of how to implement 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>