Watch Face Complications
In this document
00001. Adding Complications to a Watch Face
00002. Exposing Data to Complications
00003. Using Complication Types
00004. Using Fields for Complication Data
00005. API Additions
A complication is any feature in a watch face that displays more than hours and minutes. For example, a battery indicator is a complication. The Complications API is for both watch faces and data provider apps.
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.
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.
Watch faces can receive（接收） complication data of various types (e.g. small text data or icon data) and then display it.
As indicated（表明，顯示） in the diagram（圖標） below, Android Wear mediates the flow of data from providers to watch faces.
For creating or modifying watch faces, see Adding complications to a watch face.
For writing apps that provide data to watch faces, see Exposing data to complications.
Adding Complications to a Watch Face
Watch face developers can receive（接收） complication data and enable users toselect providers for that data. Additionally, Android Wear provides a user interface for data source selection.
Receiving data and rendering呈現 complications
To start receiving complication data, a watch face calls setActiveComplications withinthe WatchFaceService.Engine with a list of watch facecomplication IDs. A watch face creates these IDs to uniquely identify slots（插槽） on the watch face where complications can appear, and passes them to the createProviderChooserIntent method (of the ProviderChooserIntent class) to allow the user to decide which complication should go in which slot.
Complication data is delivered via （交付渠道）the onComplicationDataUpdate (of WatchFaceService.Engine) callback.
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 tablebelow).
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.
Allowing users to choose data providers
Android Wear provides a user interface (via an Activity) that enables users to choose providers for a particular complication. Watch faces can call thecreateProviderChooserIntent method toobtain an intent that can be used to show the chooser interface.
This intent must be used with startActivityForResult. When a watch face calls createProviderChooserIntent, the watch facesupplies 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.
When the user selects a data provider, the configuration issaved automatically; nothing more is required from the watch face.
User interactions（用戶交互） with complications
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 PendingIntent included in the ComplicationData object.The watch face is responsible for detecting taps on complications, and shouldfire the pending intent when a tap occurs.
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.
Exposing Data to Complications
A complication data provider （？Apps）is a service that extends ComplicationProviderService.To respond to update requests from the system, your data provider must implement the onComplicationUpdate method of the ComplicationProviderService class. This method will be called when the system wants（？Apps的） data from your provider - this could be when a complication using your provider becomes active, or when a fixed amount of time has passed. AComplicationManager object is passed as a parameter to the onComplicationUpdate method, and can be used to send data back to the system.
In your app's manifest, declare the service and add an intent filter for the following:
android.support.wearable.complications.ACTION_COMPLICATION_UPDATE_REQUEST
The service's manifest entry should also include an android:icon 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.
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 ComplicationProviderService class (in the Javadoc; see API Additions).
Update period
Your provider can specify an update period using the following metadata key in the manifest:
android.support.wearable.complications.UPDATE_PERIOD_SECONDS
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 applya minimum update period, and in particular, updates requests may come less often when the device is in ambient mode or is not being worn.
You can alternatively use a "push style" to send updates, rather than requesting updates on a fixed schedule. To do so, you canset the update period to 0 so scheduled update requests do not occur (or set it to a non-zero value) and use a ProviderUpdateRequester to trigger （觸發）calls toonComplicationUpdate as required.
Provider configuration
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:
android.support.wearable.complications.PROVIDER_CONFIG_ACTION
The value can be an action of your choice.
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 activitymust return RESULT_OK or RESULT_CANCELED, to tell the system whether the provider should be set.
The configuration activity may also be used as an opportunity to request any permissions required by the provider.
theComplicationProviderService class:
METADATA_KEY_PROVIDER_CONFIG_ACTION
Using Complication Types
Complication types determine the kinds of data shown in a complication. For example, the SHORT_TEXT type is available when the key data is a short string. In the example of the SHORT_TEXT type, optional data are an icon and a short title.
Data providers use these complication types differently from the way watch face providers use these types:
· A data provider chooses the types of complication data tosupply. For example, a step count provider might support the RANGED_VALUE andSHORT_TEXT types, whereas a "next meeting" provider might support the SHORT_TEXT and LONG_TEXT types. The data provider also chooses which optional fields of those types to include.
· A watch face provider chooses how many complication types tosupport. For example, a round complication on a watch face might support theSHORT_TEXT, ICON and RANGED_VALUE types, whereas a gauge（計量器） on the watch face might support only the RANGED_VALUE type.
A ComplicationData 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.
A given type may include different sets of fields. For example, SHORT_TEXT 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 Notes column of the table below). For example, the Short title field of the RANGED_VALUE type is not required so that, for example, gauges can be shown without including text.
Examples of Complication Types
The following shows examples of complication types:
Types and fields
The following table describes the types and fields of the ComplicationData object.
|
Type |
Required fields |
Optional fields |
Notes |
|
SHORT_TEXT |
Short text |
Icon |
Exactly one of Icon/Short title is expected to be shown if either or both are provided. |
|
ICON |
Icon |
|
Used when text is not needed.The icon is expected to be single-color, and may be tinted by the watch face. |
|
RANGED_VALUE |
Value |
Icon |
Optional fields are not guaranteed to be displayed. |
|
LONG_TEXT |
Long text |
Long title |
Title is expected to be shown if provided. |
|
SMALL_IMAGE |
Small image |
|
A small image has one of two styles: photo styleor icon style. Photo style means it should fill the space and can be cropped; icon style means it should not be cropped and may be padded. |
|
LARGE_IMAGE |
Large image |
|
This image is expected to be large enough to fill the watch face. |
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:
|
Type |
Required fields |
Optional fields |
Notes |
|
NOT_CONFIGURED |
None |
None |
Sent when a provider has not yet been chosen for a complication. |
|
EMPTY |
None |
None |
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. |
Using Fields for Complication Data
The fields of a ComplicationData 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."
The following table contains descriptions of the fields in a ComplicationData object. The fields may or may not be populated, depending on the complication type.
|
Field |
Description |
|
Short text |
Primary text field for small complications. Should not exceed 7 characters. |
|
Icon |
A single-color image representing the data or the source of the data. Must be tintable. Vector drawables are recommended for this field. |
|
Short title |
Descriptive field for small complications. Should not exceed 7 characters. May only be meaningful in combination with Short text. |
|
Long text |
Primary data field for large, text-based complications. |
|
Long title |
Descriptive field for large, text-based complications. May only be meaningful in combination with Long text. |
|
Value |
A numerical (float) representation of the data. Expected to be depicted relative to the bounds the Min value andMax value fields (but not required to be between those bounds). |
|
Min value |
The lower bound for the range within which Value should be depicted. Only meaningful in combination with Valueand Max value. |
|
Max value |
The upper bound for the range within which value should be depicted. Only meaningful in combination with Valueand Min value. |
|
Small image |
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. |
|
Large image |
An image with sufficient resolution to fill the watch face. May be full color. |
Providing time-dependent（按時間的） values
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.
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.
Providers can use the builders in the ComplicationText class to create these time-dependent values.
API Additions
The Complications API includes new classes in the Wearable Support Library. For more information, download the Android Wear 2.0 Preview Reference.
· ComplicationData
o Parcelable (using a Bundle internally); immutable
o Represents all types of complication data
o Includes a Builder for instance creation
· ComplicationText
o Used to supply text-based values in a ComplicationData object
o Includes options for time-dependent values, whose text value depends on the current time
· ComplicationProviderService
o Extends Service and includes callback methods to respond to the complication system
o Callback methods are all called on the main thread
· ComplicationManager
o A wrapper for the complication manager service, for use by providers
o Allows providers to send complication data to the system
· ProviderChooserIntent
o Non-instantiable utility class
o Includes a method that a watch face can call for starting a provider chooser (to allow a user to configure complications)
· ProviderInfoRetriever
o 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
· ProviderUpdateRequester
o Can be used by data provider apps to trigger calls to onComplicationUpdated in their provider service, to enable the push of updates
Additionally, the WatchFaceService.Engine class contains the following new methods:
· setActiveComplications
o Should be called by the watch face to tell the ComplicationManager object what complication slots are available and what types are supported
· onComplicationDataUpdate
Called by the ComplicationManager object to send complication data to the watch face
