1 /*
2  * Copyright 2020 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 package androidx.wear.remote.interactions
17 
18 import android.content.ComponentName
19 import android.content.Intent
20 import androidx.annotation.NonNull
21 import androidx.annotation.Nullable
22 
23 /**
24  * Helper functions for use by watch face configuration activities. In general, there are two
25  * distinct users:
26  * * ones creating Intents
27  * * ones receiving and responding to those Intents.
28  *
29  * To register a configuration activity for a watch face, add a `<meta-data>` entry to the watch
30  * face component in its Android Manifest file with an intent action to be fired to start the
31  * activity. The following meta-data will register the
32  * `androidx.wear.watchface.editor.action.WATCH_FACE_EDITOR` action to be started when configuring a
33  * watch face on the wearable device:
34  * ```
35  * <meta-data
36  * android:name="com.google.android.wearable.watchface.wearableConfigurationAction"
37  * android:value="androidx.wear.watchface.editor.action.WATCH_FACE_EDITOR" />
38  * ```
39  *
40  * To register a configuration activity to be started on a companion phone, add the following
41  * alternative meta-data entry to the watch face component:
42  * ```
43  * <meta-data
44  * android:name="com.google.android.wearable.watchface.companionConfigurationAction"
45  * android:value="androidx.wear.watchface.editor.action.WATCH_FACE_EDITOR" />
46  * ```
47  *
48  * The activity should have an intent filter which lists the action specified in the meta-data block
49  * above, in addition to the two categories present in the following example:
50  * ```
51  * <activity android:name=".MyWatchFaceConfigActivity">
52  * <intent-filter>
53  * <action android:name="androidx.wear.watchface.editor.action.WATCH_FACE_EDITOR" />
54  * <category android:name=
55  * "com.google.android.wearable.watchface.category.WEARABLE_CONFIGURATION" />
56  * <category android:name="android.intent.category.DEFAULT" />
57  * </intent-filter>
58  * </activity>
59  * ```
60  *
61  * For phone side configuration activities, substitute the category
62  * `com.google.android.wearable.watchface.category.COMPANION_CONFIGURATION` for
63  * `com.google.android.wearable.watchface.category.WEARABLE_CONFIGURATION`.
64  */
65 public class WatchFaceConfigIntentHelper private constructor() {
66     public companion object {
67         // The key for extra specifying a android.content.ComponentName of the watch face.
68         private const val EXTRA_WATCH_FACE_COMPONENT: String =
69             "android.support.wearable.watchface.extra.WATCH_FACE_COMPONENT"
70 
71         // The key for extra specifying the ID of the currently connected device in the phone-side
72         // config.
73         private const val EXTRA_PEER_ID: String = "android.support.wearable.watchface.extra.PEER_ID"
74 
75         /**
76          * This method is for retrieving the extended data of watch face [ComponentName] from the
77          * given [Intent]. [ComponentName] is being used to identify the APK and the class of the
78          * watch face service.
79          *
80          * @param watchFaceIntent The intent holding config activity launch.
81          * @return the value of an item previously added with [putWatchFaceComponentExtra], or null
82          *   if no value was found.
83          */
84         @Suppress("DEPRECATION")
85         @JvmStatic
86         @Nullable
getWatchFaceComponentExtranull87         public fun getWatchFaceComponentExtra(watchFaceIntent: Intent): ComponentName? =
88             watchFaceIntent.getParcelableExtra(EXTRA_WATCH_FACE_COMPONENT)
89 
90         /**
91          * This method is for adding the extended data of watch face [ComponentName] to the given
92          * [Intent].
93          *
94          * @param watchFaceIntent The intent holding config activity launch.
95          * @param componentName The component name of the watch face to be added as an extra.
96          */
97         @JvmStatic
98         @NonNull
99         public fun putWatchFaceComponentExtra(
100             watchFaceIntent: Intent,
101             componentName: ComponentName
102         ): Intent = watchFaceIntent.putExtra(EXTRA_WATCH_FACE_COMPONENT, componentName)
103 
104         /**
105          * This method is for retrieving the ID of the currently connected device from the given
106          * [Intent].
107          *
108          * @param watchFaceIntent The intent holding config activity launch.
109          * @return the value of an item previously added with [putPeerIdExtra], or null if no value
110          *   was found.
111          */
112         @JvmStatic
113         @Nullable
114         public fun getPeerIdExtra(watchFaceIntent: Intent): String? =
115             watchFaceIntent.getStringExtra(EXTRA_PEER_ID)
116 
117         /**
118          * This method is adding the ID of the currently connected device to the given [Intent].
119          *
120          * @param watchFaceIntent The intent holding config activity launch.
121          * @param peerId The string representing peer ID to be added as an extra.
122          */
123         @JvmStatic
124         @NonNull
125         public fun putPeerIdExtra(watchFaceIntent: Intent, peerId: String): Intent =
126             watchFaceIntent.putExtra(EXTRA_PEER_ID, peerId)
127     }
128 }
129