docs: Complications guide for Wear Preview
am: c0780f1d52
* commit 'c0780f1d52c8e4d78e750fb0f16eec8280ddf5f4':
docs: Complications guide for Wear Preview
Change-Id: I71999d68698c336c354cc11d042775685b77da8d
This commit is contained in:
Bert McMeen
@@ -1,7 +1,797 @@
|
|||||||
page.title=Watch Face Complications
|
page.title=Watch Face Complications
|
||||||
meta.tags="wear", "wear-preview", "complications"
|
meta.keywords="wear-preview"
|
||||||
page.tags="wear"
|
page.tags="wear-preview"
|
||||||
|
page.image=images/cards/card-n-sdk_2x.png
|
||||||
|
|
||||||
@jd:body
|
@jd:body
|
||||||
|
|
||||||
<p>stub</p>
|
<div id="qv-wrapper">
|
||||||
|
<div id="qv">
|
||||||
|
<ol>
|
||||||
|
<li>
|
||||||
|
<a href=
|
||||||
|
"#adding_complications_to_a_watch_face">Adding Complications to a Watch Face</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>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
A complication is a feature of a watch face <a href=
|
||||||
|
"https://en.wikipedia.org/wiki/Complication_(horology)">beyond hours and
|
||||||
|
minutes</a>. For example, a battery indicator is a complication.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
The Complications API is for both watch faces and data provider apps.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<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>
|
||||||
|
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>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
Along with reviewing this page, download the Android Wear 2.0 Preview
|
||||||
|
Reference and review the <a href="#api_additions">API additions</a> in
|
||||||
|
the Javadoc for complications.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
Apps that provide data to watch faces for complications are called
|
||||||
|
"complication data providers." These apps lack control over how their
|
||||||
|
data is rendered. The consuming watch faces are responsible for drawing
|
||||||
|
the complications.
|
||||||
|
</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>
|
||||||
|
Through this process, 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>
|
||||||
|
|
||||||
|
<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> within 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 (of the
|
||||||
|
<code>ProviderChooserIntent</code> class) 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="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>
|
||||||
|
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. This 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).
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<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.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
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>
|
||||||
|
The configuration activity may also 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, 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="types_and_fields">
|
||||||
|
Types and fields
|
||||||
|
</h3>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
The following table describes the types and fields of the
|
||||||
|
<code>ComplicationData</code> object.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<table>
|
||||||
|
<tr>
|
||||||
|
<th scope="col">
|
||||||
|
Type
|
||||||
|
</th>
|
||||||
|
<th scope="col">
|
||||||
|
Required fields
|
||||||
|
</th>
|
||||||
|
<th scope="col">
|
||||||
|
Optional fields
|
||||||
|
</th>
|
||||||
|
<th scope="col">
|
||||||
|
Notes
|
||||||
|
</th>
|
||||||
|
</tr>
|
||||||
|
|
||||||
|
<tr>
|
||||||
|
<td>
|
||||||
|
SHORT_TEXT
|
||||||
|
</td>
|
||||||
|
<td>
|
||||||
|
Short text
|
||||||
|
</td>
|
||||||
|
<td>
|
||||||
|
IconShort title
|
||||||
|
</td>
|
||||||
|
<td>
|
||||||
|
Exactly one of Icon/Short title is expected to be shown if either or
|
||||||
|
both are provided.
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
|
||||||
|
<tr>
|
||||||
|
<td>
|
||||||
|
LONG_TEXT
|
||||||
|
</td>
|
||||||
|
<td>
|
||||||
|
Long text
|
||||||
|
</td>
|
||||||
|
<td>
|
||||||
|
Long titleIcon*Small image
|
||||||
|
</td>
|
||||||
|
<td>
|
||||||
|
Title is expected to be shown if provided.
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
|
||||||
|
<tr>
|
||||||
|
<td>
|
||||||
|
RANGED_VALUE
|
||||||
|
</td>
|
||||||
|
<td>
|
||||||
|
ValueMin valueMax value
|
||||||
|
</td>
|
||||||
|
<td>
|
||||||
|
IconShort textShort title
|
||||||
|
</td>
|
||||||
|
<td>
|
||||||
|
Optional fields are not guaranteed to be displayed. Uses include for
|
||||||
|
numerical data within bounds, such as for a percentage.
|
||||||
|
</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>
|
||||||
|
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 following two types have no fields. These two types may
|
||||||
|
be sent for any complication slot and do not need to be included in a
|
||||||
|
list of supported types:
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<table>
|
||||||
|
<tr>
|
||||||
|
<th scope="col">
|
||||||
|
Type
|
||||||
|
</th>
|
||||||
|
<th scope="col">
|
||||||
|
Required fields
|
||||||
|
</th>
|
||||||
|
<th scope="col">
|
||||||
|
Optional fields
|
||||||
|
</th>
|
||||||
|
<th scope="col">
|
||||||
|
Notes
|
||||||
|
</th>
|
||||||
|
</tr>
|
||||||
|
|
||||||
|
<tr>
|
||||||
|
<td>
|
||||||
|
NOT_CONFIGURED
|
||||||
|
</td>
|
||||||
|
<td>
|
||||||
|
None
|
||||||
|
</td>
|
||||||
|
<td>
|
||||||
|
None
|
||||||
|
</td>
|
||||||
|
<td>
|
||||||
|
Sent when a provider has not yet been chosen for a complication.
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
|
||||||
|
<tr>
|
||||||
|
<td>
|
||||||
|
EMPTY
|
||||||
|
</td>
|
||||||
|
<td>
|
||||||
|
None
|
||||||
|
</td>
|
||||||
|
<td>
|
||||||
|
None
|
||||||
|
</td>
|
||||||
|
<td>
|
||||||
|
Sent by a provider when there is no data to display in a
|
||||||
|
complication, or sent by the system when nothing should be shown in a
|
||||||
|
complication.
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
</table>
|
||||||
|
|
||||||
|
<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">
|
||||||
|
|
||||||
|
<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 scope="col">
|
||||||
|
Field
|
||||||
|
</th>
|
||||||
|
<th scope="col">
|
||||||
|
Description
|
||||||
|
</th>
|
||||||
|
</tr>
|
||||||
|
|
||||||
|
<tr>
|
||||||
|
<td>
|
||||||
|
Short text
|
||||||
|
</td>
|
||||||
|
<td>
|
||||||
|
Primary text field for small complications. Should not exceed 7
|
||||||
|
characters.
|
||||||
|
</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>
|
||||||
|
Icon
|
||||||
|
</td>
|
||||||
|
<td>
|
||||||
|
A single-color image representing the data or the source of the
|
||||||
|
data.Must be tintable.
|
||||||
|
</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 the following new classes in the Wearable
|
||||||
|
Support Library:
|
||||||
|
</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>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>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>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>ProviderChooserIntent</code>
|
||||||
|
<ul>
|
||||||
|
<li>Non-instantiable utility class
|
||||||
|
</li>
|
||||||
|
|
||||||
|
<li>Includes a method that a watch face can call for starting a
|
||||||
|
provider chooser (to allow a user to configure complications)
|
||||||
|
</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>
|
||||||
|
</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>
|
||||||
|
|||||||
BIN
docs/html/wear/preview/images/complication-type-exs.png
Normal file
BIN
docs/html/wear/preview/images/complication-type-exs.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 65 KiB |
BIN
docs/html/wear/preview/images/complications-data-flow.png
Normal file
BIN
docs/html/wear/preview/images/complications-data-flow.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 16 KiB |
Reference in New Issue
Block a user