1page.title=Providing Configuration Activities
2
3@jd:body
4
5<div id="tb-wrapper">
6<div id="tb">
7<h2>This lesson teaches you to</h2>
8<ol>
9  <li><a href="#Intent">Specify an Intent for Configuration Activities</a></li>
10  <li><a href="#WearableActivity">Create a Wearable Configuration Activity</a></li>
11  <li><a href="#CompanionActivity">Create a Companion Configuration Activity</a></li>
12</ol>
13<h2>Related Samples</h2>
14<ul>
15<li><a href="{@docRoot}samples/WatchFace/index.html">
16WatchFace</a></li>
17</ul>
18<h2>You should also read</h2>
19<ul>
20  <li><a href="{@docRoot}design/wear/watchfaces.html">Watch Faces for Android Wear</a></li>
21</ul>
22</div>
23</div>
24
25<p>When users install a handheld app that contains a <a
26href="{@docRoot}training/wearables/apps/index.html">wearable app</a> with watch faces, these
27watch faces become available in the Android Wear companion app on the companion device and in
28the watch face picker on the wearable. Users can choose the active watch face for their wearable
29device by selecting it on the companion app or using the watch face picker on the wearable
30device.</p>
31
32<p>Some watch faces support configuration parameters to let users customize how the watch face
33looks and behaves. For example, some watch faces let users pick a custom background color, and
34watch faces that tell time for two different time zones can let users select which time zones
35they are interested in.</p>
36
37<p>Watch faces that support configuration parameters can let users customize a watch face using
38an activity in the wearable app, an activity on the handheld app, or both. Users can start the
39wearable configuration activity on the wearable device, and they can start the companion
40configuration activity from the Android Wear companion app.</p>
41
42<p>The digital watch face from the
43<a href="{@docRoot}samples/WatchFace/index.html">WatchFace</a> sample demonstrates how to
44implement handheld and wearable configuration activities and how to update a watch face in
45response to configuration changes.</p>
46
47
48
49<h2 id="Intent">Specify an Intent for Configuration Activities</h2>
50
51<p>If your watch face includes configuration activities, add the following metadata entries to
52the service declaration in the manifest file of the wearable app:</p>
53
54<pre>
55&lt;service
56    android:name=".DigitalWatchFaceService" ... />
57    &lt;!-- companion configuration activity -->
58    &lt;meta-data
59        android:name=
60           "com.google.android.wearable.watchface.companionConfigurationAction"
61        android:value=
62           "com.example.android.wearable.watchface.CONFIG_DIGITAL" />
63    &lt;!-- wearable configuration activity -->
64    &lt;meta-data
65        android:name=
66           "com.google.android.wearable.watchface.wearableConfigurationAction"
67        android:value=
68           "com.example.android.wearable.watchface.CONFIG_DIGITAL" />
69    ...
70&lt;/service>
71</pre>
72
73<p>Provide values for these entries that are preceded by the package name of your app.
74Configuration activities register intent filters for this intent, and the system fires this
75intent when users want to configure your watch face.</p>
76
77<p>If your watch face only includes a companion or a wearable configuration activity, you only
78need to include the corresponding metadata entry from the example above.</p>
79
80
81
82<h2 id="WearableActivity">Create a Wearable Configuration Activity</h2>
83
84<p>Wearable configuration activities provide a limited set of customization choices for a
85watch face, because complex menus are hard to navigate on smaller screens. Your wearable
86configuration activity should provide binary choices and just a few selections to customize
87the main aspects of your watch face.</p>
88
89<p>To create a wearable configuration activity, add a new activity to your wearable app module
90and declare the following intent filter in the manifest file of the wearable app:</p>
91
92<pre>
93&lt;activity
94    android:name=".DigitalWatchFaceWearableConfigActivity"
95    android:label="@string/digital_config_name">
96    &lt;intent-filter>
97        &lt;action android:name=
98            "com.example.android.wearable.watchface.CONFIG_DIGITAL" />
99        &lt;category android:name=
100        <strong>"com.google.android.wearable.watchface.category.WEARABLE_CONFIGURATION"</strong> />
101        &lt;category android:name="android.intent.category.DEFAULT" />
102    &lt;/intent-filter>
103&lt;/activity>
104</pre>
105
106<p>The name of the action in this intent filter must match the intent name you defined in
107<a href="#Intent">Specify an Intent for Configuration Activities</a>.</p>
108
109<p>In your configuration activity, build a simple UI that provides selections for users to
110customize your watch face. When users make a selection, use the <a
111href="{@docRoot}training/wearables/data-layer/index.html">Wearable Data Layer API</a> to
112communicate the configuration change to the watch face activity.</p>
113
114<p>For more details, see the <code>DigitalWatchFaceWearableConfigActivity</code> and
115<code>DigitalWatchFaceUtil</code> classes in the
116<a href="{@docRoot}samples/WatchFace/index.html">WatchFace</a> sample.</p>
117
118
119
120<h2 id="CompanionActivity">Create a Companion Configuration Activity</h2>
121
122<p>Companion configuration activities give users access to the full set of configuration choices
123for a watch face, because it is easier to interact with complex menus on the larger screen of
124a handheld device. For example, a configuration activity on a handheld device enables you to
125present users with elaborate color pickers to select the background color of a watch face.</p>
126
127<p>To create a companion configuration activity, add a new activity to your handheld app module and
128declare the following intent filter in the manifest file of the handheld app:</p>
129
130<pre>
131&lt;activity
132    android:name=".DigitalWatchFaceCompanionConfigActivity"
133    android:label="@string/app_name">
134    &lt;intent-filter>
135        &lt;action android:name=
136            "com.example.android.wearable.watchface.CONFIG_DIGITAL" />
137        &lt;category android:name=
138        <strong>"com.google.android.wearable.watchface.category.COMPANION_CONFIGURATION"</strong> />
139        &lt;category android:name="android.intent.category.DEFAULT" />
140    &lt;/intent-filter>
141&lt;/activity>
142</pre>
143
144<p>In your configuration activity, build a UI that provides options to customize all the
145configurable elements of your watch face. When users make a selection, use the <a
146href="{@docRoot}training/wearables/data-layer/index.html">Wearable Data Layer API</a> to
147communicate the configuration change to the watch face activity.</p>
148
149<p>For more details, see the <code>DigitalWatchFaceCompanionConfigActivity</code> class in the
150<a href="{@docRoot}samples/WatchFace/index.html">WatchFace</a> sample.</p>
151
152
153
154<h2 id="Listener">Create a Listener Service in the Wearable App</h2>
155
156<p>To receive updated configuration parameters from the configuration activities, create a
157service that implements the
158<a href="//developers.google.com/android/reference/com/google/android/gms/wearable/WearableListenerService"><code>WearableListenerService</code></a>
159interface from the
160<a href="{@docRoot}training/wearables/data-layer/index.html">Wearable Data Layer API</a> in your
161wearable app. Your watch face implementation can redraw the watch face when the configuration
162parameters change.</p>
163
164<p>For more details, see the <code>DigitalWatchFaceConfigListenerService</code> and
165<code>DigitalWatchFaceService</code> classes in the
166<a href="{@docRoot}samples/WatchFace/index.html">WatchFace</a> sample.</p>
167