Merge "Docs: Complications additions and changes" into nyc-dev

            <a href="#adding_complications_to_a_watch_face">Adding

            Complications to a Watch Face</a>

          </li>

          <li>

            <a href="#permissions-for-complication-data">Permissions

            for Complication Data</a>

          </li>

          <li>

            <a href="#default-providers">Default Providers for Watch Faces</a>

          </li>

          <li>

            <a href="#exposing_data_to_complications">Exposing Data to

            Complications</a>

            <a href="#api_additions">API Additions</a>

          </li>

      </ol>

    <h2>See Also</h2>

      <ol>

        <li><a class="external-link"

          href="https://github.com/googlesamples/android-WatchFace">Watch

          Face sample app with complications</a></li>

      </ol>

      </div>

    </div>

    </p>

    <p>

      Along with reviewing this page, download the Android Wear 2.0 Preview

      Reference (see the Complications API <a href=

      "#api_additions">additions</a>) and review the Javadoc for complications.

      You can review the Javadoc for complications by downloading

      the Android Wear 2.0 Preview

      Reference. Also see the <a href="#api_additions">API additions for

      complications</a> and the

      <a href="https://developer.android.com/wear/preview/behavior-changes.html">

      behavior changes</a> for Wear 2.0.

    </p>

    <p>

      <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

      to the <code>createProviderChooserIntent</code> method

      to allow the user to decide

      which complication should go in which slot.

    </p>

      where possible.

    </p>

    <h2 id="permissions-for-complication-data">

      Permissions for Complication Data

    </h2>

    <p>

      A watch face must have the following <a href=

      "https://developer.android.com/training/permissions/requesting.html">permission</a>

      to receive complication data and open the provider chooser:

    </p>

<pre>

com.google.android.wearable.permission.RECEIVE_COMPLICATION_DATA

</pre>

    <h3 id="opening-the-provider-chooser">

      Opening the provider chooser

    </h3>

    <p>

      A watch face that was not granted the above permission will be unable to

      start the provider chooser.

    </p>

    <p>

      To make it easier to request the permission and start the chooser, the

      <code>ComplicationHelperActivity</code> class is available in the

      wearable support library. This class should be used instead of

      <code>ProviderChooserIntent</code> to start the chooser in almost all

      cases.

    </p>

    <h4 id="requesting-the-necessary-permission">

      Requesting the necessary permission

    </h4>

    <p>

      To use <code>ComplicationHelperActivity</code>, add it to the watch face

      in the <a href=

      "https://developer.android.com/guide/topics/manifest/manifest-intro.html">

      manifest file</a>:

    </p>

<pre>

<activity android:name="android.support.wearable.complications.ComplicationHelperActivity"/>

</pre>

    <p>

      To start the provider chooser, call the

      <code>ComplicationHelperActivity.createProviderChooserHelperIntent</code>

      method, to obtain an intent.

    </p>

    <p>

      The new intent can be used with either <code>startActivity</code> or

      <code>startActivityForResult</code> to launch the chooser.

    </p>

    <p>

      Here is an example of using the new intent with

      <code>startActivityForResult</code>:

    </p>

    <pre>

startActivityForResult(

  ComplicationHelperActivity.createProviderChooserHelperIntent(

     getActivity(),

     watchFace,

     complicationId,

     ComplicationData.TYPE_LARGE_IMAGE),

  PROVIDER_CHOOSER_REQUEST_CODE);

</pre>

    <p>

      When the helper activity is started, the helper activity checks if the

      permission was granted. If the permission was not granted, the helper

      activity makes a runtime permission request. If the permission request is

      accepted (or is unneeded), the provider chooser is shown.

    </p>

    <p>

      If <code>startActivityForResult</code> was used with the intent, the

      result delivered back to the calling Activity will have a result code of

      <code>RESULT_OK</code> if a provider was successfully set, or a result

      code of <code>RESULT_CANCELLED</code> if no provider was set.

    </p>

    <p>

      In the case where a provider was set,

      <code>ComplicationProviderInfo</code> for the chosen provider will be

      included in the data intent of the result, as an extra with the key

      <code>ProviderChooserIntent#EXTRA_PROVIDER_INFO</code>.

    </p>

    <h3 id="receiving-complication-data">

      Receiving complication data

    </h3>

    <p>

      In general, watch faces need the above permission in order to receive

      complication data, but there are some exceptions. Specifically, a watch

      face can only receive data from a provider if one of the following is

      true:

    </p>

    <ul>

      <li>The provider is a "safe" system provider,

      </li>

      <li>The provider and watch face are from the same app,

      </li>

      <li>The provider whitelists the watch face as a "safe" watch face, or

      </li>

      <li>The watch face has the permission

      </li>

    </ul>

    <h4 id="lack-of-appropriate-permission">

      Lack of appropriate permission

    </h4>

    <p>

      If none of the above is true, then when <code>ComplicationData</code>

      normally would be sent by a provider to a watch face, the system instead

      sends data of the type <code>TYPE_NO_PERMISSION</code>. This type

      includes an icon (an exclamation mark) and short text ("--") to allow it

      to be rendered as if it were of the short text type or icon type, for

      convenience.

    </p>

    <p>

      When a watch face receives data of <code>TYPE_NO_PERMISSION</code>, the

      watch face should render this appropriately, so the user can see that

      action is needed for the complication to work. If possible, a tap on a

      complication in this state should launch a permission request. This can

      be done using

      <code>ComplicationHelperActivity.createPermissionRequestHelperIntent</code>,

      if the helper activity was added to the watch face app.

    </p>

    <p>

      If a user accepts the permission request created by the helper activity,

      updates are requested for all the active complications on the watch face

      automatically, allowing the <code>TYPE_NO_PERMISSION</code> data to be

      replaced by real data.

    </p>

    <h4 id="safe-providers">

      Safe providers

    </h4>

    <p>

      Some system providers are considered "safe", because they only supply

      information that the watch face already could obtain itself.

    </p>

    <p>

      These providers are listed in the new <code>SystemProviders</code> class

      in the wearable support library. Whether a system provider is safe is

      stated in the Javadoc (in the Android Wear 2.0 Preview Reference). Also

      see <a href="#system-providers">System providers</a> for a list.

    </p>

    <h4 id="provider-specified-safe-watch-faces">

      Provider-specified safe watch faces

    </h4>

    <p>

      Providers can specify certain watch faces as "safe" to receive their

      data. This is intended to be used only when the watch face will attempt

      to use the provider as a default (see below),

      and the provider trusts the watch face app.

    </p>

    <p>

      To declare watch faces as safe, the provider adds metadata with a key of

      <code>android.support.wearable.complications.SAFE_WATCH_FACES</code>. The

      metadata value should be a comma-separated list (whitespace is ignored).

      Entries in the list can be component names (of

      <code>WatchFaceServices</code>, given as if

      <code>ComponentName.flattenToString()</code> had been called), or they

      can be package names (of apps, in which case every watch face within a

      specified app is considered safe).

    </p>

    <p>

      For example:

    </p>

<pre>

<meta-data

       android:name="android.support.wearable.complications.SAFE_WATCH_FACES"

        android:value="

          com.app.watchface/com.app.watchface.MyWatchFaceService,

          com.anotherapp.anotherwatchface/com.something.WatchFaceService,

          com.something.text

        "/>

</pre>

  <h2 id="default-providers">

      Default Providers for Watch Faces

  </h2>

    <p>

      Watch faces can specify default providers that are used until a user

      selects a provider.

    </p>

    <h3 id="setting-default-providers">

      Setting default providers

    </h3>

    <p>

      Set default providers using the

      <code>setDefaultComplicationProvider</code> method in

      <code>WatchFaceService.Engine</code>. This method may be called at any

      time, but it does nothing if the user already chose a provider for the

      given complication.

    </p>

    <h3 id="safe-providers2">

      Safe providers

    </h3>

    <p>

      For most providers, the <code>RECEIVE_COMPLICATION_DATA</code> permission

      must be granted to a watch face before data can flow to it. However, some

      system providers are considered "safe", and do not require the watch face

      to have the permission for data to be sent (see <a href=

      "#safe-providers">Safe Providers</a> and <a href=

      "#system-providers">System providers</a>). These providers may be

      preferable to use as defaults, as they can supply data immediately.

    </p>

    <p>

      Alternatively, if a watch face has a partnership with a certain provider

      and wishes to use it as a default, it can request that the provider list

      it as a safe watch face (see <a href=

      "#provider-specified-safe-watch-faces">Provider-specified safe watch

      faces</a>).

    </p>

    <h3 id="system-providers">

      System providers

    </h3>

    <p>

      The system includes providers that can be used as defaults. These are

      listed in the <code>SystemProviders</code> class in the wearable support

      library.

    </p>

    <p>

      The following table has details about providers that are considered safe:

    </p>

    <table>

      <tr>

        <th>

          Method name in the SystemProviders class

        </th>

        <th>

          Safety

        </th>

        <th>

          Can be the default

        </th>

        <th>

          Notes

        </th>

      </tr>

      <tr>

        <td>

          <code>dateProvider()</code>

        </td>

        <td>

          Yes

        </td>

        <td>

          Yes

        </td>

        <td>

          The standard system date provider. Tapping opens the standard Agenda

          app.

        </td>

      </tr>

      <tr>

        <td>

          <code>currentTimeProvider()</code>

        </td>

        <td>

          Yes

        </td>

        <td>

          Yes

        </td>

        <td>

          The standard system "time and date" provider. No tap action.

        </td>

      </tr>

      <tr>

        <td>

          <code>batteryProvider()</code>

        </td>

        <td>

          Yes

        </td>

        <td>

          Yes

        </td>

        <td>

          The standard system battery provider. No tap action.

        </td>

      </tr>

      <tr>

        <td>

          <code>stepCountProvider()</code>

        </td>

        <td>

          Yes

        </td>

        <td>

          Yes

        </td>

        <td>

          Shows a daily total of steps, as reported by

          <code>readDailyTotal</code>.

        </td>

      </tr>

      <tr>

        <td>

          <code>unreadCountProvider()</code>

        </td>

        <td>

          Yes

        </td>

        <td>

          Yes

        </td>

        <td>

          Shows the number of unread notifications in the stream.

        </td>

      </tr>

      <tr>

        <td>

          <code>worldClockProvider()</code>

        </td>

        <td>

          Yes

        </td>

        <td>

          Yes

        </td>

        <td>

          Will default to London or New York. Can be tapped to change the time

          zone.

        </td>

      </tr>

      <tr>

        <td>

          <code>appsProvider()</code>

        </td>

        <td>

          Yes

        </td>

        <td>

          Yes

        </td>

        <td>

          Will show an "apps" icon at first, which can be tapped to choose an

          app.

        </td>

      </tr>

      <tr>

        <td>

          <code>nextEventProvider()</code>

        </td>

        <td>

          No

        </td>

        <td>

          Yes (but not a safe provider)

        </td>

        <td>

          The standard system "next event" provider. Tapping opens

            the standard Agenda app.

          </p>

        </td>

      </tr>

    </table>

    <h2 id="exposing_data_to_complications">

      Exposing Data to Complications

    </h2>

      be used to send data back to the system.

    </p>

    <p class="note"><strong>Note:</strong> When you provide data as a

    complication data provider, the watch face receives the raw values

    you send so it can draw them on the watch face.

    </p>

    <p>

      In your app's manifest, declare the service and add an intent filter for

      the following:

    <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

      <a href="#api_additions">API Additions</a>).

    </p>

    <p>

      Additionally, a permission for provider services ensures that only the Android Wear system

      can bind to provider services. Only the Android Wear system can have this

      permission.

    </p>

    <p>

      Provider services should add the following to their service declarations

      in the manifest:

    </p>

<pre>

android:permission="com.google.android.wearable.permission.BIND_COMPLICATION_PROVIDER"

</pre>

    <h3 id="update_period">

      Update period

    </h3>

    <p>

      The following table describes the types and fields of the

      <code>ComplicationData</code> object.

      If a watch face requests a field that is invalid for a complication type,

      a default value for the field is returned.

      For example, if a watch face tries to access a <code>Long text</code>

      field in a <code>SHORT_TEXT</code> type, the default value for the

      <code>Long text</code> field is returned.

    </p>

    <table>

    </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:

      In addition, the types in the table below are for empty data and

      may be sent for any complication slot. These types have no fields

      and do not need to be included in a

      list of supported types. These types enable watch

      faces to differentiate among the following three cases:

    </p>

    <ul>

      <li>No provider was chosen

      </li>

      <li>The user has selected "empty" for a slot

      </li>

      <li>A provider has no data to send

      </li>

    </ul>

    <p>

      Providers should not send <code>TYPE_EMPTY</code> in response to

      update requests. Providers should send <code>TYPE_NO_DATA</code> instead.

    </p>

    <p>

      Details on the complication types for "empty" data are in the

      following table:

    </p>

    <table>

      <tr>

        <th style="width:175px">

          Type

        </th>

        <th style="width:175px">

          Required fields

        <th>Complication type

        </th>

        <th style="width:175px">

          Optional fields

        </th>

        <th>

          Notes

        <th>Description

        </th>

      </tr>

      <tr>

        <td>

          NOT_CONFIGURED

          <code>TYPE_NOT_CONFIGURED</code>

        </td>

        <td>

          None

        </td>

        <td>

          None

        </td>

        <td>

          Sent when a provider has not yet been chosen for a complication.

          Sent by the system when a complication is activated but the user has

          not selected a provider, and no default was set.

          <p>

            Cannot be sent by providers.

          </p>

        </td>

      </tr>

      <tr>

        <td>

          EMPTY

          <code>TYPE_EMPTY</code>

        </td>

        <td>

          None

          Sent by the system when a complication is activated and the user has

          chosen "empty" instead of a provider, or when the watch face has

          chosen no provider, and this type, as the default.

          <p>

            Cannot be sent by providers.

          </p>

        </td>

      </tr>

      <tr>

        <td>

          None

          <code>TYPE_NO_DATA</code>

        </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.

          Sent by the system when a complication (that has a provider) is

          activated, to clear the complication before actual data is received

          from the provider.

          <p>

            Should be sent by providers if they have no actual data to send.

          </p>

        </td>

      </tr>

    </table>

    </h2>

    <p>

      The Complications API includes new classes in the Wearable Support

      Library. For more information, download the <a href=

      The Complications API includes new classes in the wearable support

      library. For more information, download the <a href=

      "{@docRoot}wear/preview/start.html#get_the_preview_reference_documentation">

      Android Wear 2.0 Preview Reference</a>.

    </p>

      </li>

      <li>

        <code>ComplicationText</code>

        <code>ComplicationHelperActivity</code>

        <ul>

          <li>Used to supply text-based values in a

          <code>ComplicationData</code> object

          <li>Used to request the following permission: <br>

<code>com.google.android.wearable.permission.RECEIVE_COMPLICATION_DATA</code>

          </li>

          <li>Includes options for time-dependent values, whose text value

          depends on the current time

          <li>Used instead of <code>ProviderChooserIntent</code>

          to start the chooser in almost all cases

          </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>

      <li>

        <code>ComplicationManager</code>

        <code>ComplicationText</code>

        <ul>

          <li>A wrapper for the complication manager service, for use by

          providers

          <li>Used to supply text-based values in a

          <code>ComplicationData</code> object

          </li>

          <li>Allows providers to send complication data to the system

          <li>Includes options for time-dependent values, whose text value

          depends on the current time

          </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>Non-instantiable utility class that is not commonly used; use

          <code>ComplicationHelperActivity</code> instead

          </li>

        </ul>

      </li>

          </li>

        </ul>

      </li>

      <li>

        <code>SystemProviders</code>

        <ul>

          <li>Lists system providers that are considered "safe",

          because they only supply information that the watch face

          already could obtain itself

          </li>

        </ul>

      </li>

    </ul>

    <p>