page.title=Watch Face Complications
meta.keywords="wear-preview"
page.tags="wear-preview"
page.image=/wear/preview/images/complications-main-image.png
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li>
<a href="#adding_complications_to_a_watch_face">Adding
Complications to a Watch Face</a>
</li>
<li>
<a href="#permissions-for-complication-data">Permissions
for Complication Data</a>
</li>
<li>
<a href="#default-providers">Default Providers for Watch Faces</a>
</li>
<li>
<a href="#exposing_data_to_complications">Exposing Data to
Complications</a>
</li>
<li>
<a href="#using_complication_types">Using Complication Types</a>
</li>
<li>
<a href="#using_fields_for_complication_data">Using Fields for
Complication Data</a>
</li>
<li>
<a href="#api_additions">API Additions</a>
</li>
</ol>
<h2>See Also</h2>
<ol>
<li><a class="external-link"
href="https://github.com/googlesamples/android-WatchFace">Watch
Face sample app with complications</a></li>
</ol>
</div>
</div>
<p>
A complication is any feature in a watch face that displays <a href=
"https://en.wikipedia.org/wiki/Complication_(horology)">more than hours and
minutes</a>. For example, a battery indicator is a complication. The
Complications API is for both watch faces and data provider apps.
</p>
<div class="col-4of10">
<img src="../images/complications-main-image.png" alt="Complications"
id="img-split-screen">
</div>
<p>
Watch faces can display extra information without needing code for
getting the underlying data. Data providers can supply data (such as
battery level, weather, or step-count data) to any watch face using the
API.
</p>
<p>
You can review the Javadoc for complications by downloading
the Android Wear 2.0 Preview
Reference. Also see the <a href="#api_additions">API additions for
complications</a> and the
<a href="https://developer.android.com/wear/preview/behavior-changes.html">
behavior changes</a> for Wear 2.0.
</p>
<p>
Apps that provide data to watch faces for complications are called
"complication data providers." These apps are not responsible for controlling
how their data is rendered on the watch face.
This allows a watch face to integrate the data naturally with the
watch face design.
The consuming watch faces are responsible for drawing
the complications.
</p>
<p>
Watch faces can receive complication data of
<a href="#using_complication_types">various types</a> (e.g. small text
data or icon data) and then display it.
</p>
<p>
As indicated in the diagram below, Android Wear mediates the flow of data
from providers to watch faces.
</p>
<img src="../images/complications-data-flow.png" width="" alt=
"Complications data flow" title="Complications data flow">
<p>
For creating or modifying watch faces, see <a href=
"#adding_complications_to_a_watch_face">Adding complications to a watch
face</a>.
</p>
<p>
For writing apps that provide data to watch faces, see <a href=
"#exposing_data_to_complications">Exposing data to complications</a>.
</p>
<h2 id="adding_complications_to_a_watch_face">
Adding Complications to a Watch Face
</h2>
<p>
Watch face developers can receive complication data and enable users to
select providers for that data. Additionally, Android Wear provides a
<a href="#allowing_users_to_choose_data_providers">user interface for
data source selection</a>.
</p>
<h3 id="receiving_data_and_rendering_complications">
Receiving data and rendering complications
</h3>
<p>
To start receiving complication data, a watch face calls
<code>setActiveComplications</code>, in the
<code>WatchFaceService.Engine</code> class, with a list of watch face
complication IDs. A watch face creates these IDs to uniquely identify
slots on the watch face where complications can appear, and passes them
to the <code>createProviderChooserIntent</code> method
to allow the user to decide
which complication should go in which slot.
</p>
<p>
Complication data is delivered via the
<code>onComplicationDataUpdate</code> (of
<code>WatchFaceService.Engine</code>) callback.
</p>
<p>
The watch face may render the data as desired as long as the expected
fields are represented; the required fields should always be included and
the data should be represented in some way. Depending on the type, some
of the optional fields should also be included (see the Notes column in
the <a href="#types_and_fields">table</a> below).
</p>
<p>
We provide design guidelines for our style, as a suggestion for standard
complications, but developers can use their own styles or incorporate the
data into the watch face in different ways.
</p>
<h3 id="allowing_users_to_choose_data_providers">
Allowing users to choose data providers
</h3>
<p>
Android Wear provides a user interface (via an Activity) that enables
users to choose providers for a particular complication. Watch faces can
call the <code>createProviderChooserIntent</code> method to obtain an
intent that can be used to show the chooser interface.
</p>
<p>
This intent must be used with <code>startActivityForResult</code>. When a
watch face calls <code>createProviderChooserIntent</code>, the watch face
supplies a watch face complication ID and a list of supported types. The
types should be listed in order of preference, usually with types
offering more information, such as ranged value, given higher preference.
</p>
<p>
When the user selects a data provider, the configuration is saved
automatically; nothing more is required from the watch face.
</p>
<h3 id="user_interactions_with_complications">
User interactions with complications
</h3>
<p>
Providers can specify an action that occurs if the user taps on a
complication, so it should be possible for most complications to be
tappable. This action will be specified as a <code>PendingIntent</code>
included in the <code>ComplicationData</code> object. The watch face is
responsible for detecting taps on complications, and should fire the
pending intent when a tap occurs.
</p>
<p>
It may be infeasible to make some complications tappable (e.g., in the
case of a complication that fills the entire background of the watch
face), but it is expected that watch faces accept taps on complications
where possible.
</p>
<h2 id="permissions-for-complication-data">
Permissions for Complication Data
</h2>
<p>
A watch face must have the following <a href=
"https://developer.android.com/training/permissions/requesting.html">permission</a>
to receive complication data and open the provider chooser:
</p>
<pre>
com.google.android.wearable.permission.RECEIVE_COMPLICATION_DATA
</pre>
<h3 id="opening-the-provider-chooser">
Opening the provider chooser
</h3>
<p>
A watch face that was not granted the above permission will be unable to
start the provider chooser.
</p>
<p>
To make it easier to request the permission and start the chooser, the
<code>ComplicationHelperActivity</code> class is available in the
wearable support library. This class should be used instead of
<code>ProviderChooserIntent</code> to start the chooser in almost all
cases.
</p>
<h4 id="requesting-the-necessary-permission">
Requesting the necessary permission
</h4>
<p>
To use <code>ComplicationHelperActivity</code>, add it to the watch face
in the <a href=
"https://developer.android.com/guide/topics/manifest/manifest-intro.html">
manifest file</a>:
</p>
<pre>
<activity android:name="android.support.wearable.complications.ComplicationHelperActivity"/>
</pre>
<p>
To start the provider chooser, call the
<code>ComplicationHelperActivity.createProviderChooserHelperIntent</code>
method, to obtain an intent.
</p>
<p>
The new intent can be used with either <code>startActivity</code> or
<code>startActivityForResult</code> to launch the chooser.
</p>
<p>
Here is an example of using the new intent with
<code>startActivityForResult</code>:
</p>
<pre>
startActivityForResult(
ComplicationHelperActivity.createProviderChooserHelperIntent(
getActivity(),
watchFace,
complicationId,
ComplicationData.TYPE_LARGE_IMAGE),
PROVIDER_CHOOSER_REQUEST_CODE);
</pre>
<p>
When the helper activity is started, the helper activity checks if the
permission was granted. If the permission was not granted, the helper
activity makes a runtime permission request. If the permission request is
accepted (or is unneeded), the provider chooser is shown.
</p>
<p>
If <code>startActivityForResult</code> was used with the intent, the
result delivered back to the calling Activity will have a result code of
<code>RESULT_OK</code> if a provider was successfully set, or a result
code of <code>RESULT_CANCELLED</code> if no provider was set.
</p>
<p>
In the case where a provider was set,
<code>ComplicationProviderInfo</code> for the chosen provider will be
included in the data intent of the result, as an extra with the key
<code>ProviderChooserIntent#EXTRA_PROVIDER_INFO</code>.
</p>
<h3 id="receiving-complication-data">
Receiving complication data
</h3>
<p>
In general, watch faces need the above permission in order to receive
complication data, but there are some exceptions. Specifically, a watch
face can only receive data from a provider if one of the following is
true:
</p>
<ul>
<li>The provider is a "safe" system provider,
</li>
<li>The provider and watch face are from the same app,
</li>
<li>The provider whitelists the watch face as a "safe" watch face, or
</li>
<li>The watch face has the permission
</li>
</ul>
<h4 id="lack-of-appropriate-permission">
Lack of appropriate permission
</h4>
<p>
If none of the above is true, then when <code>ComplicationData</code>
normally would be sent by a provider to a watch face, the system instead
sends data of the type <code>TYPE_NO_PERMISSION</code>. This type
includes an icon (an exclamation mark) and short text ("--") to allow it
to be rendered as if it were of the short text type or icon type, for
convenience.
</p>
<p>
When a watch face receives data of <code>TYPE_NO_PERMISSION</code>, the
watch face should render this appropriately, so the user can see that
action is needed for the complication to work. If possible, a tap on a
complication in this state should launch a permission request. This can
be done using
<code>ComplicationHelperActivity.createPermissionRequestHelperIntent</code>,
if the helper activity was added to the watch face app.
</p>
<p>
If a user accepts the permission request created by the helper activity,
updates are requested for all the active complications on the watch face
automatically, allowing the <code>TYPE_NO_PERMISSION</code> data to be
replaced by real data.
</p>
<h4 id="safe-providers">
Safe providers
</h4>
<p>
Some system providers are considered "safe", because they only supply
information that the watch face already could obtain itself.
</p>
<p>
These providers are listed in the new <code>SystemProviders</code> class
in the wearable support library. Whether a system provider is safe is
stated in the Javadoc (in the Android Wear 2.0 Preview Reference). Also
see <a href="#system-providers">System providers</a> for a list.
</p>
<h4 id="provider-specified-safe-watch-faces">
Provider-specified safe watch faces
</h4>
<p>
Providers can specify certain watch faces as "safe" to receive their
data. This is intended to be used only when the watch face will attempt
to use the provider as a default (see below),
and the provider trusts the watch face app.
</p>
<p>
To declare watch faces as safe, the provider adds metadata with a key of
<code>android.support.wearable.complications.SAFE_WATCH_FACES</code>. The
metadata value should be a comma-separated list (whitespace is ignored).
Entries in the list can be component names (of
<code>WatchFaceServices</code>, given as if
<code>ComponentName.flattenToString()</code> had been called), or they
can be package names (of apps, in which case every watch face within a
specified app is considered safe).
</p>
<p>
For example:
</p>
<pre>
<meta-data
android:name="android.support.wearable.complications.SAFE_WATCH_FACES"
android:value="
com.app.watchface/com.app.watchface.MyWatchFaceService,
com.anotherapp.anotherwatchface/com.something.WatchFaceService,
com.something.text
"/>
</pre>
<h2 id="default-providers">
Default Providers for Watch Faces
</h2>
<p>
Watch faces can specify default providers that are used until a user
selects a provider.
</p>
<h3 id="setting-default-providers">
Setting default providers
</h3>
<p>
Set default providers using the
<code>setDefaultComplicationProvider</code> method in
<code>WatchFaceService.Engine</code>. This method may be called at any
time, but it does nothing if the user already chose a provider for the
given complication.
</p>
<h3 id="safe-providers2">
Safe providers
</h3>
<p>
For most providers, the <code>RECEIVE_COMPLICATION_DATA</code> permission
must be granted to a watch face before data can flow to it. However, some
system providers are considered "safe", and do not require the watch face
to have the permission for data to be sent (see <a href=
"#safe-providers">Safe Providers</a> and <a href=
"#system-providers">System providers</a>). These providers may be
preferable to use as defaults, as they can supply data immediately.
</p>
<p>
Alternatively, if a watch face has a partnership with a certain provider
and wishes to use it as a default, it can request that the provider list
it as a safe watch face (see <a href=
"#provider-specified-safe-watch-faces">Provider-specified safe watch
faces</a>).
</p>
<h3 id="system-providers">
System providers
</h3>
<p>
The system includes providers that can be used as defaults. These are
listed in the <code>SystemProviders</code> class in the wearable support
library.
</p>
<p>
The following table has details about providers that are considered safe:
</p>
<table>
<tr>
<th>
Method name in the SystemProviders class
</th>
<th>
Safety
</th>
<th>
Can be the default
</th>
<th>
Notes
</th>
</tr>
<tr>
<td>
<code>dateProvider()</code>
</td>
<td>
Yes
</td>
<td>
Yes
</td>
<td>
The standard system date provider. Tapping opens the standard Agenda
app.
</td>
</tr>
<tr>
<td>
<code>currentTimeProvider()</code>
</td>
<td>
Yes
</td>
<td>
Yes
</td>
<td>
The standard system "time and date" provider. No tap action.
</td>
</tr>
<tr>
<td>
<code>batteryProvider()</code>
</td>
<td>
Yes
</td>
<td>
Yes
</td>
<td>
The standard system battery provider. No tap action.
</td>
</tr>
<tr>
<td>
<code>stepCountProvider()</code>
</td>
<td>
Yes
</td>
<td>
Yes
</td>
<td>
Shows a daily total of steps, as reported by
<code>readDailyTotal</code>.
</td>
</tr>
<tr>
<td>
<code>unreadCountProvider()</code>
</td>
<td>
Yes
</td>
<td>
Yes
</td>
<td>
Shows the number of unread notifications in the stream.
</td>
</tr>
<tr>
<td>
<code>worldClockProvider()</code>
</td>
<td>
Yes
</td>
<td>
Yes
</td>
<td>
Will default to London or New York. Can be tapped to change the time
zone.
</td>
</tr>
<tr>
<td>
<code>appsProvider()</code>
</td>
<td>
Yes
</td>
<td>
Yes
</td>
<td>
Will show an "apps" icon at first, which can be tapped to choose an
app.
</td>
</tr>
<tr>
<td>
<code>nextEventProvider()</code>
</td>
<td>
No
</td>
<td>
Yes (but not a safe provider)
</td>
<td>
The standard system "next event" provider. Tapping opens
the standard Agenda app.
</p>
</td>
</tr>
</table>
<h2 id="exposing_data_to_complications">
Exposing Data to Complications
</h2>
<p>
A complication data provider is a service that extends
<code>ComplicationProviderService</code>. To respond to update requests
from the system, your data provider must implement the
<code>onComplicationUpdate</code> method of the
<code>ComplicationProviderService</code> class. This method will be
called when the system wants data from your provider - this could be when
a complication using your provider becomes active, or when a fixed amount
of time has passed. A <code>ComplicationManager</code> object is passed
as a parameter to the <code>onComplicationUpdate</code> method, and can
be used to send data back to the system.
</p>
<p class="note"><strong>Note:</strong> When you provide data as a
complication data provider, the watch face receives the raw values
you send so it can draw them on the watch face.
</p>
<p>
In your app's manifest, declare the service and add an intent filter for
the following:
</p>
<pre>
android.support.wearable.complications.ACTION_COMPLICATION_UPDATE_REQUEST
</pre>
<p>
The service's manifest entry should also include an
<code>android:icon</code> attribute. The provided icon should be a
single-color white icon. Vector drawables are recommended for the icons.
An icon should represent the provider and will be shown in the provider
chooser.
</p>
<p>
Include metadata to specify the supported types, update period, and
configuration action, if required; for details, download the Android Wear
2.0 Preview Reference and see the keys listed for the
<code>ComplicationProviderService</code> class (in the Javadoc; see
<a href="#api_additions">API Additions</a>).
</p>
<p>
Additionally, a permission for provider services ensures that only the Android Wear system
can bind to provider services. Only the Android Wear system can have this
permission.
</p>
<p>
Provider services should add the following to their service declarations
in the manifest:
</p>
<pre>
android:permission="com.google.android.wearable.permission.BIND_COMPLICATION_PROVIDER"
</pre>
<h3 id="update_period">
Update period
</h3>
<p>
Your provider can specify an update period using the following metadata
key in the manifest:
</p>
<pre>
android.support.wearable.complications.UPDATE_PERIOD_SECONDS
</pre>
<p>
This should be set to as long a time as possible, as updating too
frequently may impact battery life. Note that update requests are not
guaranteed to be sent with this frequency. The system does apply a
minimum update period, and in particular, updates requests may come less
often when the device is in ambient mode or is not being worn.
</p>
<p>
You can alternatively use a "push style" to send updates, rather than
requesting updates on a fixed schedule. To do so, you can set the update
period to 0 so scheduled update requests do not occur (or set it to a
non-zero value) and use a <code>ProviderUpdateRequester</code> to trigger
calls to <code>onComplicationUpdate</code> as required.
</p>
<h3 id="provider_configuration">
Provider configuration
</h3>
<p>
If required, a provider can include a configuration activity that is
shown to the user when the user chooses a data provider. To include the
configuration activity, include a metadata item in the provider service
declaration in the manifest with a key of the following:
</p>
<p>
<code>android.support.wearable.complications.PROVIDER_CONFIG_ACTION</code>
</p>
<p>
The value can be an action of your choice.
</p>
<p>
Then create the configuration activity with an intent filter for that
action. The configuration activity must reside in the same package as the
provider. The configuration activity must return <code>RESULT_OK</code> or
<code>RESULT_CANCELED</code>, to tell the system whether the provider
should be set.
</p>
<p>
If a data provider needs a specific permission to access a user's data,
then standard code
for runtime <a href="{@docRoot}training/articles/wear-permissions.html">
permissions</a> is needed.
A <a href="{@docRoot}training/wearables/watch-faces/configuration.html">
configuration activity</a> may be used as an opportunity to request
any permissions required by the provider.
</p>
<p>
For details, download the Android Wear 2.0 Preview Reference (see
<a href="#api_additions">API Additions</a>), containing the Javadoc, and
see the following in the <code>ComplicationProviderService</code> class:
</p>
<pre>
METADATA_KEY_PROVIDER_CONFIG_ACTION
</pre>
<h2 id="using_complication_types">
Using Complication Types
</h2>
<p>
Complication types determine the kinds of data shown in a complication.
For example, the <code>SHORT_TEXT</code> type is available when the key
data is a short string. In the example of the <code>SHORT_TEXT</code>
type, optional data are an icon and a short title.
</p>
<p>
Data providers use these complication types differently from the way
watch face providers use these types:
</p>
<ul>
<li>A data provider chooses the types of complication data to supply. For
example, a step count provider might support the
<code>RANGED_VALUE</code> and <code>SHORT_TEXT</code> types, whereas a
"next meeting" provider might support the <code>SHORT_TEXT</code> and
<code>LONG_TEXT</code> types. The data provider also chooses which
optional fields of those types to include.
</li>
<li>A watch face provider chooses how many complication types to support.
For example, a round complication on a watch face might support the
<code>SHORT_TEXT</code>, <code>ICON</code> and <code>RANGED_VALUE</code>
types, whereas a gauge on the watch face might support only the
<code>RANGED_VALUE</code> type.
</li>
</ul>
<p>
A <code>ComplicationData</code> object will always have a single
complication type. Each complication type has required and optional
fields. Generally, a required field represents the primary piece of data;
most types take their name from the required field.
</p>
<p>
A given type may include different sets of fields. For example,
<code>SHORT_TEXT</code> may be just a single piece of text, or a title
and text, or an icon and text. A complication that supports a given type
must be able to display all the expected variants. However, some optional
fields do not need to be displayed (see the <em>Notes</em> column of the
table below). For example, the Short title field of the
<code>RANGED_VALUE</code> type is not required so that, for example,
gauges can be shown without including text.
</p>
<h3 id="examples_of_complication_types">
Examples of Complication Types
</h3>
<p>
The following shows examples of complication types:
</p>
<img src="../images/complication-type-exs.png" width="" alt=
"Complication types" title="Complications types - examples">
<h3 id="types_and_fields">
Types and fields
</h3>
<p>
The following table describes the types and fields of the
<code>ComplicationData</code> object.
If a watch face requests a field that is invalid for a complication type,
a default value for the field is returned.
For example, if a watch face tries to access a <code>Long text</code>
field in a <code>SHORT_TEXT</code> type, the default value for the
<code>Long text</code> field is returned.
</p>
<table>
<tr>
<th style="width:175px">
Type
</th>
<th style="width:175px">
Required fields
</th>
<th style="width:175px">
Optional fields
</th>
<th>
Notes
</th>
</tr>
<tr>
<td>
SHORT_TEXT
</td>
<td>
Short text
</td>
<td>
Icon<br>
Short title
</td>
<td>
Exactly one of Icon/Short title is expected to be shown if either or
both are provided.
</td>
</tr>
<tr>
<td>
ICON
</td>
<td>
Icon
</td>
<td>
</td>
<td>
Used when text is not needed.The icon is expected to be single-color,
and may be tinted by the watch face.
</td>
</tr>
<tr>
<td>
RANGED_VALUE
</td>
<td>
Value<br>
Min value<br>
Max value
</td>
<td>
Icon<br>
Short text<br>
Short title
</td>
<td>
Optional fields are not guaranteed to be displayed.
</td>
</tr>
<tr>
<td>
LONG_TEXT
</td>
<td>
Long text
</td>
<td>
Long title<br>
Icon<br>
Small image
</td>
<td>
Title is expected to be shown if provided.
</td>
</tr>
<tr>
<td>
SMALL_IMAGE
</td>
<td>
Small image
</td>
<td>
</td>
<td>
A small image has one of two styles: <em>photo style</em> or <em>icon
style</em>. Photo style means it should fill the space and can be
cropped; icon style means it should not be cropped and may be padded.
</td>
</tr>
<tr>
<td>
LARGE_IMAGE
</td>
<td>
Large image
</td>
<td>
</td>
<td>
This image is expected to be large enough to fill the watch face.
</td>
</tr>
</table>
<p>
In addition, the types in the table below are for empty data and
may be sent for any complication slot. These types have no fields
and do not need to be included in a
list of supported types. These types enable watch
faces to differentiate among the following three cases:
</p>
<ul>
<li>No provider was chosen
</li>
<li>The user has selected "empty" for a slot
</li>
<li>A provider has no data to send
</li>
</ul>
<p>
Providers should not send <code>TYPE_EMPTY</code> in response to
update requests. Providers should send <code>TYPE_NO_DATA</code> instead.
</p>
<p>
Details on the complication types for "empty" data are in the
following table:
</p>
<table>
<tr>
<th>Complication type
</th>
<th>Description
</th>
</tr>
<tr>
<td>
<code>TYPE_NOT_CONFIGURED</code>
</td>
<td>
Sent by the system when a complication is activated but the user has
not selected a provider, and no default was set.
<p>
Cannot be sent by providers.
</p>
</td>
</tr>
<tr>
<td>
<code>TYPE_EMPTY</code>
</td>
<td>
Sent by the system when a complication is activated and the user has
chosen "empty" instead of a provider, or when the watch face has
chosen no provider, and this type, as the default.
<p>
Cannot be sent by providers.
</p>
</td>
</tr>
<tr>
<td>
<code>TYPE_NO_DATA</code>
</td>
<td>
Sent by the system when a complication (that has a provider) is
activated, to clear the complication before actual data is received
from the provider.
<p>
Should be sent by providers if they have no actual data to send.
</p>
</td>
</tr>
</table>
<h2 id="using_fields_for_complication_data">
Using Fields for Complication Data
</h2>
<p>
The fields of a <code>ComplicationData</code> object have different
functions. For example, a text field contains the primary data while a
title field is descriptive; a step count complication might have a text
field value of "2,543" with a title field value of "steps."
</p>
<p>
The following table contains descriptions of the fields in a
<code>ComplicationData</code> object. The fields may or may not be
populated, depending on the complication type.
</p>
<table>
<tr>
<th style="width:175px">
Field
</th>
<th>
Description
</th>
</tr>
<tr>
<td>
Short text
</td>
<td>
Primary text field for small complications. Should not exceed 7
characters.
</td>
</tr>
<tr>
<td>
Icon
</td>
<td>
A single-color image representing the data or the source of the data.
Must be tintable. Vector drawables are recommended for this field.
</td>
</tr>
<tr>
<td>
Short title
</td>
<td>
Descriptive field for small complications. Should not exceed 7
characters. May only be meaningful in combination with <em>Short
text</em>.
</td>
</tr>
<tr>
<td>
Long text
</td>
<td>
Primary data field for large, text-based complications.
</td>
</tr>
<tr>
<td>
Long title
</td>
<td>
Descriptive field for large, text-based complications. May only be
meaningful in combination with <em>Long text</em>.
</td>
</tr>
<tr>
<td>
Value
</td>
<td>
A numerical (float) representation of the data. Expected to be
depicted relative to the bounds the <em>Min value</em> and <em>Max
value</em> fields (but not required to be between those bounds).
</td>
</tr>
<tr>
<td>
Min value
</td>
<td>
The lower bound for the range within which <em>Value</em> should be
depicted. Only meaningful in combination with <em>Value</em> and
<em>Max value</em>.
</td>
</tr>
<tr>
<td>
Max value
</td>
<td>
The upper bound for the range within which <em>value</em> should be
depicted. Only meaningful in combination with <em>Value</em> and
<em>Min value</em>.
</td>
</tr>
<tr>
<td>
Small image
</td>
<td>
A small image to represent the data or the source of the data. May be
full color. Not expected to fill the entire watch face.
</td>
</tr>
<tr>
<td>
Large image
</td>
<td>
An image with sufficient resolution to fill the watch face. May be
full color.
</td>
</tr>
</table>
<h3 id="providing_time-dependent_values">
Providing time-dependent values
</h3>
<p>
Some complications need to display a value that relates to the current
time. Examples include the current date, the time until the next meeting,
or the time in another time zone.
</p>
<p>
Providers of such data should not need to update a complication every
second/minute to keep those values up to date. Instead, they can specify
the values as relative to the current date or time.
</p>
<p>
Providers can use the builders in the <code>ComplicationText</code> class
to create these time-dependent values.
</p>
<h2 id="api_additions">
API Additions
</h2>
<p>
The Complications API includes new classes in the wearable support
library. For more information, download the <a href=
"{@docRoot}wear/preview/start.html#get_the_preview_reference_documentation">
Android Wear 2.0 Preview Reference</a>.
</p>
<ul>
<li>
<code>ComplicationData</code>
<ul>
<li>Parcelable (using a Bundle internally); immutable
</li>
<li>Represents all types of complication data
</li>
<li>Includes a Builder for instance creation
</li>
</ul>
</li>
<li>
<code>ComplicationHelperActivity</code>
<ul>
<li>Used to request the following permission: <br>
<code>com.google.android.wearable.permission.RECEIVE_COMPLICATION_DATA</code>
</li>
<li>Used instead of <code>ProviderChooserIntent</code>
to start the chooser in almost all cases
</li>
</ul>
</li>
<li>
<code>ComplicationManager</code>
<ul>
<li>A wrapper for the complication manager service, for use by
providers
</li>
<li>Allows providers to send complication data to the system
</li>
</ul>
</li>
<li>
<code>ComplicationProviderService</code>
<ul>
<li>Extends <code>Service</code> and includes callback methods to
respond to the complication system
</li>
<li>Callback methods are all called on the main thread
</li>
</ul>
</li>
<li>
<code>ComplicationText</code>
<ul>
<li>Used to supply text-based values in a
<code>ComplicationData</code> object
</li>
<li>Includes options for time-dependent values, whose text value
depends on the current time
</li>
</ul>
</li>
<li>
<code>ProviderChooserIntent</code>
<ul>
<li>Non-instantiable utility class that is not commonly used; use
<code>ComplicationHelperActivity</code> instead
</li>
</ul>
</li>
<li>
<code>ProviderInfoRetriever</code>
<ul>
<li>Can be used (by watch face configuration activities) to retrieve
the current data provider information (app, provider name, icon) for
all complications belonging to a watch face
</li>
</ul>
</li>
<li>
<code>ProviderUpdateRequester</code>
<ul>
<li>Can be used by data provider apps to trigger calls to
<code>onComplicationUpdated</code> in their provider service, to
enable the push of updates
</li>
</ul>
</li>
<li>
<code>SystemProviders</code>
<ul>
<li>Lists system providers that are considered "safe",
because they only supply information that the watch face
already could obtain itself
</li>
</ul>
</li>
</ul>
<p>
Additionally, the <code>WatchFaceService.Engine</code> class contains the
following new methods:
</p>
<ul>
<li>
<code>setActiveComplications</code>
<ul>
<li>Should be called by the watch face to tell the
<code>ComplicationManager</code> object what complication slots are
available and what types are supported
</li>
</ul>
</li>
<li>
<code>onComplicationDataUpdate</code>
<ul>
<li>Called by the <code>ComplicationManager</code> object to send
complication data to the watch face
</li>
</ul>
</li>
</ul>