Personalize with photos

Note: This feature is available on version 4 and higher of Watch Face Format.

Allowing the user to select photos for inclusion on the watch face can help bring a personal touch to your watch face experience.

The working with images section already covers how to display images in your watch face. If you want to allow the user to choose from a range of predefined images, then use a ListConfiguration as shown in the define user configurations section.

To use images in your watch face that the user can configure, use the <PhotosConfiguration> element, for example:

<UserConfigurations>
  <PhotosConfiguration id="photoConfig" configType="SINGLE"/>
</UserConfigurations>

The configType can be either SINGLE or MULTIPLE indicating whether the user will be able to select a single image within the companion or a collection of photos.

Support a single photo

For the single image case, the photo can be used within a PartImage element as follows:

<PartImage ...>
  <Photos source="[CONFIGURATION.photoConfig]" defaultImageResource="default_image"/>
</PartImage>

Note the defaultImageResource, which is shown when the user has not selected a photo in the companion and is a required attribute.

If the user wishes to select a different photo, then they must use the companion to replace the existing selection with another.

Support multiple photos

Using PhotosConfiguration with configType="MULTIPLE" allows the watch face to display a photo from a collection, which can be cycled through either through tapping or automatically after so many views have taken place.

<Photos change="ON_VISIBLE TAP" changeAfterEvery="5"
    source="[CONFIGURATION.photoConfig]" defaultImageResource="default_image"/>

The preceding example shows the two options that are introduced when using MULTIPLE:

  1. The change attribute allows the developer to specify what events should cause the photo to cycle through the available images.

In the preceding example, both TAP and ON_VISIBLE are specified, meaning that the photo changes in response either to a user tapping the photo or in response to the photo becoming visible.

  1. The changeAfterEvery attribute applies only to the ON_VISIBLE change event, specifing how many times the photo should have become visible before the photo is changed. For example, you may feel that changing the photo every time the user wakes their watch is too frequent. The default value here is 3.

For more details on working with PhotosConfiguration, see the samples on GitHub.