Merge "Initial Watch Face Format samples" into main

README.md

@@ -19,7 +19,10 @@ Samples
 
 * **[RuntimePermissionsWear](RuntimePermissionsWear)** (Kotlin) - Demonstrates requesting permissions not only on a Wear OS device and a mobile device, but also across devices, e.g., request permissions on a mobile device from your wear device and the other way around. Note: It does require you having both the Wear and Mobile version of the app installed on both devices. [Guide](https://developer.android.com/training/articles/wear-permissions)
 
-* **[WatchFaceKotlin](WatchFaceKotlin)** (Kotlin) - Demos the new AndroidX Watch Face APIs which provide their own storage mechanism for watch face preference values.
+* **[WatchFaceFormat](WatchFaceFormat)** - Demos the new Watch Face Format which allows quick development of performant watch
+    faces in XML [Guide](https://developer.android.com/training/wearables/wff)
+
+* **[WatchFaceKotlin](WatchFaceKotlin)** (Kotlin) - Demos the AndroidX Watch Face APIs which provide their own storage mechanism for watch face preference values.
 
 * **[WearAccessibilityApp](WearAccessibilityApp)** (Java) - Sample demonstrates how to include accessibility support for your wearable app. [Guide](https://developer.android.com/guide/topics/ui/accessibility)
 

WatchFaceFormat/README.md

@@ -0,0 +1,74 @@
+# Watch Face Format Sample
+
+A sample demonstrating the structure of Watch Face Format watch faces
+
+## Introduction
+
+The Watch Face Format (WFF) allows developers to build watch faces, and watch
+face design tools in a XML format.
+
+This sample demonstrates the basic structure of a WFF watch face, and how it
+should be packaged for uploading to Play or for local testing on an emulator or
+device.
+
+For more details on the Watch Face Format, see:
+
+- [Watch Face Format overview][wff-overview]
+- [Watch Face Format setup][wff-setup]
+- [XML reference][wff-xml-reference]
+- [Design guidance][watch-face-design-guidance]
+
+## Building the sample
+
+This sample uses a shell script to demonstrate the packaging of the watch face.
+
+You will need to set a handful of environment variables first:
+
+- `ANDROID_HOME` - path to your SDK installation, for example on Mac:
+  `/Users/<my_user>/Library/Android/sdk`
+- `AAPT2` - path to the AAPT2 binary, for example:
+  `$ANDROID_HOME/build-tools/<version>/aapt2`
+- `ANDROID_JAR` - path to the Android JAR, for example:
+  `$ANDROID_HOME/platforms/android-<version>/android.jar`
+- `BUNDLETOOL` - path to the Bundle Tool. On Mac, this can be installed using
+  `brew install bundletool`
+
+From the `WatchFaceFormat` directory, execute:
+
+```shell
+./build-wff.sh SimpleDigital
+```
+
+This will build the watch face in a few formats, notably:
+
+- `SimpleDigital/out/mybundle.aab` - a bundle suitable for upload to Play
+- `SimpleDigital/out/result_apks/universal.apk` - an APK, for easy deployment
+  to a local device.
+
+## Deploying locally for test
+
+On a Wear 4 device, such as the Wear emulator:
+
+1. install the watch face:
+
+    ```shell
+    adb install SimpleDigital/out/result_apks/universal.apk
+    ```
+
+1. Long press on the current watch face, and locate the option to select further
+   watch faces. Choose the **Simple Digital** watch face.
+
+## Support
+
+- Stack Overflow: <https://stackoverflow.com/questions/tagged/wear-os>
+- Error Reporting: If you've found an error in this sample, please file an
+  issue: <https://github.com/android/wear-os-samples>
+- Submitting Patches: Patches are encouraged, and may be submitted by forking
+  this project and submitting a pull request through GitHub. Please see
+  [CONTRIBUTING.md][contributing] for more details.
+
+[wff-overview]: https://developer.android.com/training/wearables/wff
+[wff-setup]: https://developer.android.com/training/wearables/wff/setup
+[wff-xml-reference]: https://developer.android.com/training/wearables/wff/watch-face
+[watch-face-design-guidance]: https://developer.android.com/design/ui/wear/guides/surfaces/watch-faces
+[contributing]: ../CONTRIBUTING.md

WatchFaceFormat/SimpleAnalog/AndroidManifest.xml

@@ -0,0 +1,35 @@
+<?xml version="1.0" encoding="utf-8" standalone="no"?>
+<!--
+    Copyright 2023 Google LLC
+
+    Licensed under the Apache License, Version 2.0 (the "License");
+    you may not use this file except in compliance with the License.
+    You may obtain a copy of the License at
+
+        https://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+-->
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+  xmlns:tools="http://schemas.android.com/tools"
+      package="com.example.simpleanalog"
+      android:versionCode="1"
+      android:versionName="1.0">
+
+  <uses-feature android:name="android.hardware.type.watch" />
+
+  <uses-sdk android:minSdkVersion="33" />
+
+  <!-- Note: hasCode is required to be false for Watch Face Format -->
+  <application
+      android:label="@string/watch_face_name"
+      android:hasCode="false">
+    <property
+        android:name="com.google.wear.watchface.format.version"
+        android:value="1" />
+  </application>
+</manifest>

WatchFaceFormat/SimpleAnalog/res/raw/watchface.xml

@@ -0,0 +1,51 @@
+<?xml version="1.0"?>
+<!--
+    Copyright 2023 Google LLC
+
+    Licensed under the Apache License, Version 2.0 (the "License");
+    you may not use this file except in compliance with the License.
+    You may obtain a copy of the License at
+
+        https://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+-->
+<!--
+	Basic example of an analog watch face, demonstrating:
+
+	- Use of HourHand, MinuteHand, SecondHand
+	- Ambient behavior
+	- Sweep vs Tick second hand behavior
+-->
+<WatchFace width="450" height="450">
+  <Metadata key="CLOCK_TYPE" value="ANALOG"/>
+  <Metadata key="TICK_PER_SECOND" value="15"/>
+  <Metadata key="PREVIEW_TIME" value="10:08:32"/>
+  <Scene backgroundColor="#ff000000">
+    <AnalogClock x="0" y="0" width="450" height="450">
+      <!-- Interactive-mode hands -->
+      <SecondHand resource="@drawable/second_hand" x="224" y="10" width="2" height="215" pivotX="0.5" pivotY="1">
+        <Variant mode="AMBIENT" target="alpha" value="0"/>
+        <!-- Second hand can either be 'Sweep' or 'Tick' in behaviour -->
+        <Sweep frequency="15"/>
+      </SecondHand>
+      <MinuteHand resource="@drawable/minute_hand" x="220" y="75" width="10" height="150" pivotX="0.5" pivotY="1">
+        <Variant mode="AMBIENT" target="alpha" value="0"/>
+      </MinuteHand>
+      <HourHand resource="@drawable/hour_hand" x="220" y="125" width="10" height="100" pivotX="0.5" pivotY="1">
+        <Variant mode="AMBIENT" target="alpha" value="0"/>
+      </HourHand>
+      <!-- Ambient versions - no second hand in ambient mode -->
+      <MinuteHand resource="@drawable/minute_hand_ambient" x="222" y="75" width="6" height="150" pivotX="0.5" pivotY="1" alpha="0">
+        <Variant mode="AMBIENT" target="alpha" value="255"/>
+      </MinuteHand>
+      <HourHand resource="@drawable/hour_hand_ambient" x="222" y="125" width="6" height="100" pivotX="0.5" pivotY="1" alpha="0">
+        <Variant mode="AMBIENT" target="alpha" value="255"/>
+      </HourHand>
+    </AnalogClock>
+  </Scene>
+</WatchFace>

WatchFaceFormat/SimpleAnalog/res/values/strings.xml

@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+    Copyright 2023 Google LLC
+
+    Licensed under the Apache License, Version 2.0 (the "License");
+    you may not use this file except in compliance with the License.
+    You may obtain a copy of the License at
+
+        https://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+-->
+<resources>
+  <string name="watch_face_name">Simple Analog</string>
+</resources>

WatchFaceFormat/SimpleAnalog/res/xml/watch_face_info.xml

@@ -0,0 +1,25 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+    Copyright 2023 Google LLC
+
+    Licensed under the Apache License, Version 2.0 (the "License");
+    you may not use this file except in compliance with the License.
+    You may obtain a copy of the License at
+
+        https://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+-->
+<WatchFaceInfo>
+  <!--
+    Preview is the only required element here.
+
+    For other elements, see:
+    https://developer.android.com/training/wearables/wff/setup#declare-metadata
+    -->
+  <Preview value="@drawable/preview" />
+</WatchFaceInfo>

WatchFaceFormat/SimpleDigital/AndroidManifest.xml

@@ -0,0 +1,35 @@
+<?xml version="1.0" encoding="utf-8" standalone="no"?>
+<!--
+    Copyright 2023 Google LLC
+
+    Licensed under the Apache License, Version 2.0 (the "License");
+    you may not use this file except in compliance with the License.
+    You may obtain a copy of the License at
+
+        https://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+-->
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+  xmlns:tools="http://schemas.android.com/tools"
+      package="com.example.simpledigital"
+      android:versionCode="1"
+      android:versionName="1.0">
+
+  <uses-feature android:name="android.hardware.type.watch" />
+
+  <uses-sdk android:minSdkVersion="33" />
+
+  <!-- Note: hasCode is required to be false for Watch Face Format -->
+  <application
+      android:label="@string/watch_face_name"
+      android:hasCode="false">
+    <property
+        android:name="com.google.wear.watchface.format.version"
+        android:value="1" />
+  </application>
+</manifest>

WatchFaceFormat/SimpleDigital/res/raw/watchface.xml

@@ -0,0 +1,58 @@
+<?xml version="1.0"?>
+<!--
+    Copyright 2023 Google LLC
+
+    Licensed under the Apache License, Version 2.0 (the "License");
+    you may not use this file except in compliance with the License.
+    You may obtain a copy of the License at
+
+        https://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+-->
+<!--
+    Basic example of a text-only, digital watch face, demonstrating:
+    
+    - Use of TimeText for digital watch faces
+    - Showing different styling in ambient mode, via the Variant element
+    - Localization using Android string resources
+-->
+<WatchFace width="450" height="450">
+  <Metadata key="CLOCK_TYPE" value="DIGITAL"/>
+  <Metadata key="TICK_PER_SECOND" value="15"/>
+  <Metadata key="PREVIEW_TIME" value="10:08:32"/>
+  <Scene backgroundColor="#ff000000">
+    <DigitalClock x="0" y="0" width="450" height="450">
+      <!-- For further attributes see:
+          https://developer.android.com/training/wearables/wff/clock/time-text -->
+      <!-- SYNC_TO_DEVICE specifies to respect the device 12/24h setting -->
+      <!-- Interactive mode version-->
+      <TimeText format="hh:mm" hourFormat="SYNC_TO_DEVICE" align="CENTER" x="0" y="175" width="450" height="100" alpha="255">
+        <Variant mode="AMBIENT" target="alpha" value="0"/>
+        <!-- Specifying the watch's default font-family by using SYNC_TO_DEVICE instead of a named family -->
+        <Font family="SYNC_TO_DEVICE" size="128" weight="NORMAL" slant="NORMAL" color="#ffffffff"/>
+      </TimeText>
+      <!-- Ambient mode version - thinner weight -->
+      <TimeText format="hh:mm" hourFormat="SYNC_TO_DEVICE" align="CENTER" x="0" y="175" width="450" height="100" alpha="0">
+        <!-- Specifying the watch's default family by using SYNC_TO_DEVICE -->
+        <Variant mode="AMBIENT" target="alpha" value="255"/>
+        <Font family="SYNC_TO_DEVICE" size="128" weight="THIN" slant="NORMAL" color="#ffffffff"/>
+      </TimeText>
+    </DigitalClock>
+    <Group x="0" y="0" width="450" height="450" name="hello_world">
+      <PartText x="0" y="285" width="450" height="50">
+        <Variant mode="AMBIENT" target="alpha" value="0"/>
+        <Text align="CENTER">
+          <!-- Demonstrates using Android string resources for localization -->
+          <Font family="SYNC_TO_DEVICE" size="36" color="#ffffffff">
+            <Template>@string/greeting</Template>
+          </Font>
+        </Text>
+      </PartText>
+    </Group>
+  </Scene>
+</WatchFace>

WatchFaceFormat/SimpleDigital/res/values-fr/strings.xml

@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+    Copyright 2023 Google LLC
+
+    Licensed under the Apache License, Version 2.0 (the "License");
+    you may not use this file except in compliance with the License.
+    You may obtain a copy of the License at
+
+        https://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+-->
+<resources>
+  <string name="watch_face_name">Numérique Basique</string>
+  <string name="greeting">Salut tout le monde!</string>
+</resources>

WatchFaceFormat/SimpleDigital/res/values/strings.xml

@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+    Copyright 2023 Google LLC
+
+    Licensed under the Apache License, Version 2.0 (the "License");
+    you may not use this file except in compliance with the License.
+    You may obtain a copy of the License at
+
+        https://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+-->
+<resources>
+    <string name="watch_face_name">Simple Digital</string>
+    <string name="greeting">Hello, world!</string>
+</resources>

WatchFaceFormat/SimpleDigital/res/xml/watch_face_info.xml

@@ -0,0 +1,25 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+    Copyright 2023 Google LLC
+
+    Licensed under the Apache License, Version 2.0 (the "License");
+    you may not use this file except in compliance with the License.
+    You may obtain a copy of the License at
+
+        https://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+-->
+<WatchFaceInfo>
+  <!--
+    Preview is the only required element here.
+
+    For other elements, see:
+    https://developer.android.com/training/wearables/wff/setup#declare-metadata
+    -->
+  <Preview value="@drawable/preview" />
+</WatchFaceInfo>