1 page.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"> 16 WatchFace</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 26 href="{@docRoot}training/wearables/apps/index.html">wearable app</a> with watch faces, these 27 watch faces become available in the Android Wear companion app on the companion device and in 28 the watch face picker on the wearable. Users can choose the active watch face for their wearable 29 device by selecting it on the companion app or using the watch face picker on the wearable 30 device.</p> 31 32 <p>Some watch faces support configuration parameters to let users customize how the watch face 33 looks and behaves. For example, some watch faces let users pick a custom background color, and 34 watch faces that tell time for two different time zones can let users select which time zones 35 they are interested in.</p> 36 37 <p>Watch faces that support configuration parameters can let users customize a watch face using 38 an activity in the wearable app, an activity on the handheld app, or both. Users can start the 39 wearable configuration activity on the wearable device, and they can start the companion 40 configuration 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 44 implement handheld and wearable configuration activities and how to update a watch face in 45 response 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 52 the service declaration in the manifest file of the wearable app:</p> 53 54 <pre> 55 <service 56 android:name=".DigitalWatchFaceService" ... /> 57 <!-- companion configuration activity --> 58 <meta-data 59 android:name= 60 "com.google.android.wearable.watchface.companionConfigurationAction" 61 android:value= 62 "com.example.android.wearable.watchface.CONFIG_DIGITAL" /> 63 <!-- wearable configuration activity --> 64 <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 </service> 71 </pre> 72 73 <p>Provide values for these entries that are preceded by the package name of your app. 74 Configuration activities register intent filters for this intent, and the system fires this 75 intent 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 78 need 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 85 watch face, because complex menus are hard to navigate on smaller screens. Your wearable 86 configuration activity should provide binary choices and just a few selections to customize 87 the 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 90 and declare the following intent filter in the manifest file of the wearable app:</p> 91 92 <pre> 93 <activity 94 android:name=".DigitalWatchFaceWearableConfigActivity" 95 android:label="@string/digital_config_name"> 96 <intent-filter> 97 <action android:name= 98 "com.example.android.wearable.watchface.CONFIG_DIGITAL" /> 99 <category android:name= 100 <strong>"com.google.android.wearable.watchface.category.WEARABLE_CONFIGURATION"</strong> /> 101 <category android:name="android.intent.category.DEFAULT" /> 102 </intent-filter> 103 </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 110 customize your watch face. When users make a selection, use the <a 111 href="{@docRoot}training/wearables/data-layer/index.html">Wearable Data Layer API</a> to 112 communicate 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 123 for a watch face, because it is easier to interact with complex menus on the larger screen of 124 a handheld device. For example, a configuration activity on a handheld device enables you to 125 present 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 128 declare the following intent filter in the manifest file of the handheld app:</p> 129 130 <pre> 131 <activity 132 android:name=".DigitalWatchFaceCompanionConfigActivity" 133 android:label="@string/app_name"> 134 <intent-filter> 135 <action android:name= 136 "com.example.android.wearable.watchface.CONFIG_DIGITAL" /> 137 <category android:name= 138 <strong>"com.google.android.wearable.watchface.category.COMPANION_CONFIGURATION"</strong> /> 139 <category android:name="android.intent.category.DEFAULT" /> 140 </intent-filter> 141 </activity> 142 </pre> 143 144 <p>In your configuration activity, build a UI that provides options to customize all the 145 configurable elements of your watch face. When users make a selection, use the <a 146 href="{@docRoot}training/wearables/data-layer/index.html">Wearable Data Layer API</a> to 147 communicate 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 157 service that implements the 158 <a href="//developers.google.com/android/reference/com/google/android/gms/wearable/WearableListenerService"><code>WearableListenerService</code></a> 159 interface from the 160 <a href="{@docRoot}training/wearables/data-layer/index.html">Wearable Data Layer API</a> in your 161 wearable app. Your watch face implementation can redraw the watch face when the configuration 162 parameters 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
