stub
\ No newline at end of file ++ A complication is a feature of a watch face beyond 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. +
+ ++ 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. +
+ ++ Along with reviewing this page, download the Android Wear 2.0 Preview + Reference and review the API additions in + the Javadoc for complications. +
+ ++ 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. +
+ ++ As indicated in the diagram below, Android Wear mediates the flow of data + from providers to watch faces. +
+ +
+
+ + Through this process, watch faces can receive complication data of + various types (e.g. small text + data or icon data) and then display it. +
+ ++ Watch face developers can receive complication data and enable users to + select providers for that data. Additionally, Android Wear provides a + user interface for + data source selection. +
+ +
+ To start receiving complication data, a watch face calls
+ setActiveComplications within the
+ WatchFaceService.Engine 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 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 table below). +
+ ++ 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. +
+ +
+ Android Wear provides a user interface (via an Activity) that enables
+ users to choose providers for a particular complication. Watch faces can
+ call the createProviderChooserIntent method to obtain 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 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.
+
+ When the user selects a data provider, the configuration is saved + automatically; nothing more is required from the watch face. +
+ +
+ 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 should fire 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. +
+ +
+ A complication data provider 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 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 ComplicationManager 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. This 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).
+
+ 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 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. +
+ +
+ 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 ProviderUpdateRequester to trigger
+ calls to onComplicationUpdate as required.
+
+ 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 activity must 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. +
+ +
+ For details, download the Android Wear 2.0 Preview Reference, containing
+ the Javadoc, and see the following in the
+ ComplicationProviderService class:
+
+METADATA_KEY_PROVIDER_CONFIG_ACTION ++
+ 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: +
+ +RANGED_VALUE and SHORT_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.
+ SHORT_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.
+
+ The following table describes the types and fields of the
+ ComplicationData object.
+
| + Type + | ++ Required fields + | ++ Optional fields + | ++ Notes + | +
|---|---|---|---|
| + SHORT_TEXT + | ++ Short text + | ++ IconShort title + | ++ Exactly one of Icon/Short title is expected to be shown if either or + both are provided. + | +
| + LONG_TEXT + | ++ Long text + | ++ Long titleIcon*Small image + | ++ Title is expected to be shown if provided. + | +
| + RANGED_VALUE + | ++ ValueMin valueMax value + | ++ IconShort textShort title + | ++ Optional fields are not guaranteed to be displayed. Uses include for + numerical data within bounds, such as for a percentage. + | +
| + ICON + | ++ Icon + | ++ | ++ Used when text is not needed.The icon is expected to be single-color, + and may be tinted by the watch face. + | +
| + SMALL_IMAGE + | ++ Small image + | ++ | ++ A small image has one of two styles: photo style or 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. + | +
+ The following shows examples of complication types: +
+ +
+
+
+ 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. + | +
| + 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 and Max + 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 Value and + Max value. + | +
| + Max value + | ++ The upper bound for the range within which value should be + depicted.Only meaningful in combination with Value and + Min value. + | +
| + Icon + | ++ A single-color image representing the data or the source of the + data.Must be tintable. + | +
| + 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. + | +
+ 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.
+
+ The Complications API includes the following new classes in the Wearable + Support Library: +
+ +ComplicationData
+ ComplicationText
+ ComplicationData object
+ ComplicationProviderService
+ Service and includes callback methods to
+ respond to the complication system
+ ComplicationManager
+ ProviderChooserIntent
+ ProviderInfoRetriever
+ ProviderUpdateRequester
+ onComplicationUpdated in their provider service, to
+ enable the push of updates
+
+ Additionally, the WatchFaceService.Engine class contains the
+ following new methods:
+
setActiveComplications
+ ComplicationManager object what complication slots are
+ available and what types are supported
+ onComplicationDataUpdate
+ ComplicationManager object to send
+ complication data to the watch face
+