From 5c7636218dbc878641b2e11b86725b3e60730218 Mon Sep 17 00:00:00 2001 From: Bert McMeen Date: Wed, 31 Aug 2016 16:22:41 -0700 Subject: [PATCH] Docs: Complications additions and changes Bug: 28864917 Change-Id: I9551d30ee5fb4db9a77373b6445e145a5f4a3b11 --- .../wear/preview/features/complications.jd | 598 ++++++++++++++++-- 1 file changed, 540 insertions(+), 58 deletions(-) diff --git a/docs/html/wear/preview/features/complications.jd b/docs/html/wear/preview/features/complications.jd index 3334cb79b1430..c8661188eb0a1 100644 --- a/docs/html/wear/preview/features/complications.jd +++ b/docs/html/wear/preview/features/complications.jd @@ -12,6 +12,13 @@ page.image=/wear/preview/images/complications-main-image.png Adding Complications to a Watch Face +
  • + Permissions + for Complication Data +
    • +
  • + Default Providers for Watch Faces +
  • Exposing Data to Complications @@ -27,12 +34,14 @@ page.image=/wear/preview/images/complications-main-image.png API Additions
    • +

    See Also

    1. Watch Face sample app with complications
    + @@ -56,9 +65,12 @@ page.image=/wear/preview/images/complications-main-image.png

    - Along with reviewing this page, download the Android Wear 2.0 Preview - Reference (see the Complications API additions) 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 API additions for + complications and the + + behavior changes for Wear 2.0.

    @@ -117,8 +129,8 @@ page.image=/wear/preview/images/complications-main-image.png 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 + to the createProviderChooserIntent method + to allow the user to decide which complication should go in which slot.

    @@ -186,6 +198,406 @@ page.image=/wear/preview/images/complications-main-image.png where possible.

    +

    + Permissions for Complication Data +

    + +

    + A watch face must have the following permission + to receive complication data and open the provider chooser: +

    + +
    +com.google.android.wearable.permission.RECEIVE_COMPLICATION_DATA
+
    + +

    + Opening the provider chooser +

    + +

    + A watch face that was not granted the above permission will be unable to + start the provider chooser. +

    + +

    + To make it easier to request the permission and start the chooser, the + ComplicationHelperActivity class is available in the + wearable support library. This class should be used instead of + ProviderChooserIntent to start the chooser in almost all + cases. +

    + +

    + Requesting the necessary permission +

    + +

    + To use ComplicationHelperActivity, add it to the watch face + in the + manifest file: +

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

    + To start the provider chooser, call the + ComplicationHelperActivity.createProviderChooserHelperIntent + method, to obtain an intent. +

    + +

    + The new intent can be used with either startActivity or + startActivityForResult to launch the chooser. +

    + +

    + Here is an example of using the new intent with + startActivityForResult: +

    + + 
    +startActivityForResult(
+  ComplicationHelperActivity.createProviderChooserHelperIntent(
+     getActivity(),
+     watchFace,
+     complicationId,
+     ComplicationData.TYPE_LARGE_IMAGE),
+  PROVIDER_CHOOSER_REQUEST_CODE);
+
    +

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

    + +

    + If startActivityForResult was used with the intent, the + result delivered back to the calling Activity will have a result code of + RESULT_OK if a provider was successfully set, or a result + code of RESULT_CANCELLED if no provider was set. +

    + +

    + In the case where a provider was set, + ComplicationProviderInfo for the chosen provider will be + included in the data intent of the result, as an extra with the key + ProviderChooserIntent#EXTRA_PROVIDER_INFO. +

    + +

    + Receiving complication data +

    + +

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

    + + + +

    + Lack of appropriate permission +

    + +

    + If none of the above is true, then when ComplicationData + normally would be sent by a provider to a watch face, the system instead + sends data of the type TYPE_NO_PERMISSION. 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. +

    + +

    + When a watch face receives data of TYPE_NO_PERMISSION, 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 + ComplicationHelperActivity.createPermissionRequestHelperIntent, + if the helper activity was added to the watch face app. +

    + +

    + 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 TYPE_NO_PERMISSION data to be + replaced by real data. +

    + +

    + Safe providers +

    + +

    + Some system providers are considered "safe", because they only supply + information that the watch face already could obtain itself. +

    + +

    + These providers are listed in the new SystemProviders 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 System providers for a list. +

    + +

    + Provider-specified safe watch faces +

    + +

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

    + +

    + To declare watch faces as safe, the provider adds metadata with a key of + android.support.wearable.complications.SAFE_WATCH_FACES. The + metadata value should be a comma-separated list (whitespace is ignored). + Entries in the list can be component names (of + WatchFaceServices, given as if + ComponentName.flattenToString() had been called), or they + can be package names (of apps, in which case every watch face within a + specified app is considered safe). +

    + +

    + For example: +

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

    + Default Providers for Watch Faces +

    + +

    + Watch faces can specify default providers that are used until a user + selects a provider. +

    + +

    + Setting default providers +

    + +

    + Set default providers using the + setDefaultComplicationProvider method in + WatchFaceService.Engine. This method may be called at any + time, but it does nothing if the user already chose a provider for the + given complication. +

    + +

    + Safe providers +

    + +

    + For most providers, the RECEIVE_COMPLICATION_DATA 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 Safe Providers and System providers). These providers may be + preferable to use as defaults, as they can supply data immediately. +

    + +

    + 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 Provider-specified safe watch + faces). +

    + +

    + System providers +

    + +

    + The system includes providers that can be used as defaults. These are + listed in the SystemProviders class in the wearable support + library. +

    + +

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

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + Method name in the SystemProviders class + + Safety + + Can be the default + + Notes +
    + dateProvider() + + Yes + + Yes + + The standard system date provider. Tapping opens the standard Agenda + app. +
    + currentTimeProvider() + + Yes + + Yes + + The standard system "time and date" provider. No tap action. +
    + batteryProvider() + + Yes + + Yes + + The standard system battery provider. No tap action. +
    + stepCountProvider() + + Yes + + Yes + + Shows a daily total of steps, as reported by + readDailyTotal. +
    + unreadCountProvider() + + Yes + + Yes + + Shows the number of unread notifications in the stream. +
    + worldClockProvider() + + Yes + + Yes + + Will default to London or New York. Can be tapped to change the time + zone. +
    + appsProvider() + + Yes + + Yes + + Will show an "apps" icon at first, which can be tapped to choose an + app. +
    + nextEventProvider() + + No + + Yes (but not a safe provider) + + The standard system "next event" provider. Tapping opens + the standard Agenda app. +

    +
    + +

    Exposing Data to Complications

    @@ -203,6 +615,11 @@ page.image=/wear/preview/images/complications-main-image.png be used to send data back to the system.

    +

    Note: 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. +

    +

    In your app's manifest, declare the service and add an intent filter for the following: @@ -210,7 +627,8 @@ page.image=/wear/preview/images/complications-main-image.png 

     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 @@ -227,6 +645,21 @@ android.support.wearable.complications.ACTION_COMPLICATION_UPDATE_REQUEST API Additions).

    +

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

    + +

    + Provider services should add the following to their service declarations + in the manifest: +

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

    Update period

    @@ -371,6 +804,11 @@ METADATA_KEY_PROVIDER_CONFIG_ACTION

    The following table describes the types and fields of the ComplicationData 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 Long text + field in a SHORT_TEXT type, the default value for the + Long text field is returned.

    @@ -489,56 +927,80 @@ METADATA_KEY_PROVIDER_CONFIG_ACTION

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

    + + + +

    + Providers should not send TYPE_EMPTY in response to + update requests. Providers should send TYPE_NO_DATA instead. +

    + +

    + Details on the complication types for "empty" data are in the + following table:

    - - - - - - + + + + -
    - Type + Complication type - Required fields - - Optional fields - - Notes + Description
    - NOT_CONFIGURED + TYPE_NOT_CONFIGURED - None - - None - - 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. +

    + Cannot be sent by providers. +

    - EMPTY + TYPE_EMPTY - 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. +

    + Cannot be sent by providers. +

    +
    + TYPE_NO_DATA - 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. + 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. +

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

    @@ -700,8 +1162,8 @@ METADATA_KEY_PROVIDER_CONFIG_ACTION

    - The Complications API includes new classes in the Wearable Support - Library. For more information, download the Android Wear 2.0 Preview Reference.

    @@ -722,26 +1184,14 @@ METADATA_KEY_PROVIDER_CONFIG_ACTION
  • - ComplicationText + ComplicationHelperActivity -
    • - -
  • - ComplicationProviderService -
    • @@ -759,13 +1209,35 @@ METADATA_KEY_PROVIDER_CONFIG_ACTION
  • - ProviderChooserIntent + ComplicationProviderService +
    • + +
  • + ComplicationText + +
    • + +
  • + ProviderChooserIntent +
    • @@ -789,6 +1261,16 @@ METADATA_KEY_PROVIDER_CONFIG_ACTION + +
  • + SystemProviders + +