docs: Complications guide for Wear Preview

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>