diff options
| -rw-r--r-- | docs/html/wear/preview/features/complications.jd | 796 | ||||
| -rw-r--r-- | docs/html/wear/preview/images/complication-type-exs.png | bin | 0 -> 66588 bytes | |||
| -rw-r--r-- | docs/html/wear/preview/images/complications-data-flow.png | bin | 0 -> 16126 bytes |
3 files changed, 793 insertions, 3 deletions
diff --git a/docs/html/wear/preview/features/complications.jd b/docs/html/wear/preview/features/complications.jd index 3d88f3a67d1a..155f7335e8ef 100644 --- a/docs/html/wear/preview/features/complications.jd +++ b/docs/html/wear/preview/features/complications.jd @@ -1,7 +1,797 @@ page.title=Watch Face Complications -meta.tags="wear", "wear-preview", "complications" -page.tags="wear" +meta.keywords="wear-preview" +page.tags="wear-preview" +page.image=images/cards/card-n-sdk_2x.png @jd:body -<p>stub</p>
\ No newline at end of file + <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> diff --git a/docs/html/wear/preview/images/complication-type-exs.png b/docs/html/wear/preview/images/complication-type-exs.png Binary files differnew file mode 100644 index 000000000000..d6fe8908d025 --- /dev/null +++ b/docs/html/wear/preview/images/complication-type-exs.png diff --git a/docs/html/wear/preview/images/complications-data-flow.png b/docs/html/wear/preview/images/complications-data-flow.png Binary files differnew file mode 100644 index 000000000000..7fa43f2704ff --- /dev/null +++ b/docs/html/wear/preview/images/complications-data-flow.png |
