Define user configurations
Stay organized with collections Save and categorize content based on your preferences.

UserConfigurations let you create options that the user can choose between. You can adjust the appearance of watch face elements based on the chosen values.

The user configuration options can be:

BooleanConfiguration: typically used for where the user might have the option to show an element or not, or pick between two styles
ListConfiguration: provides the user with a range of options. For example, if the watch face had four different background images to choose from
ColorConfiguration: defines color themes, from which the user can select their preferred theme.

Boolean options

Boolean options are perhaps the simplest of the user configurations. They can be defined as follows:

<WatchFace ...>
  <UserConfigurations>
   <!-- show_date and show_date_label defined in res/values/strings.xml -->
    <BooleanConfiguration id="show_date"
        displayName="show_date_label"
        screenReaderText="show_date_label"
        defaultValue="TRUE"
    />
  </UserConfigurations>
  ...
</WatchFace>

Boolean options can then be used in a two ways:

Using the BooleanConfiguration structure within the watch face Scene:

<Scene>
    <BooleanConfiguration id="show_date">
        <BooleanOption id="TRUE">
        <!-- ...Content to show date -->
        </BooleanOption>
        <BooleanOption id="FALSE">
        <!-- ...Content when date not required -->
        </BooleanOption>
    </BooleanConfiguration>
</Scene>

Note that configuration options cannot be nested in their use, so the following is not valid:

<!-- Will not work -->
<!-- <Scene>
  <BooleanConfiguration id="show_date">
    <BooleanOption id="TRUE">
      <BooleanConfiguration id="show_time">
        <BooleanOption id="TRUE">
          Content intended for when show_date and show_time both set to TRUE
        </BooleanOption>
      </BooleanConfiguration>
    </BooleanOption>
  </BooleanConfiguration>
</Scene> -->

Alternatively, the configuration option can be used in expressions:

<Condition>
<Expressions>
    <Expression name="my_expression">
        <!-- Use show_date as part of a more complex evaluation -->
        <![CDATA[[CONFIGURATION.show_date] == "TRUE" && ... ]]>
    </Expression>
    </Expressions>
    <Compare expression="my_expression">
        <!-- Content goes here -->
    </Compare>
</Condition>

List options

List options work in a very similar manner to boolean options. For example, to provide a list of background images for the user to choose from:

<ListConfiguration id="bg_img" displayName="bg_img_lbl" icon="bg_img_ico"
    screenReaderText="bg_img_lbl" defaultValue="0">
  <ListOption id="0" displayName="bg0_lbl" screenReaderText="b0_lbl" icon="bg0_ico" />
  <ListOption id="1" displayName="bg1_lbl" screenReaderText="bg1_lbl" icon="bg1_ico" />
  ...
</ListConfiguration>

Similar to boolean options, there are again two ways to use this:

Using the ListConfiguration element in Scene:

<ListConfiguration id="bg_img">
  <ListOption id="0">
    <!-- Show background 0 -->
  </ListOption>
  <ListOption id="1">
    <!-- Show background 1 ... etc -->
  </ListOption>
</ListConfiguration>

Alternatively, the configuration option can be used in more complex expressions:

<Condition>
  <Expressions>
      <Expression name="background_zero_and_something_else">
        <!-- Use bg_img as part of a more complex evaluation -->
        <![CDATA[[CONFIGURATION.bg_img] == "0" && ... ]]>
      </Expression>
    </Expressions>
    <Compare expression="background_zero_and_something_else">
        <!-- Content goes here -->
    </Compare>
</Condition>

Color themes

Watch Face Format lets you define color themes through ColorConfiguration. Users can select the theme of their choice from the watch face editor, and the colors from this theme can appear throughout your watch face definition.

For example, to define a theme with two entries and three colors in the theme:

Relaxed
Urban

Define a ColorConfiguration as follows:

<UserConfigurations>
  <ColorConfiguration id="myThemeColor" displayName="theme_label" defaultValue="0">
    <ColorOption id="0" displayName="relaxed_label" colors="#3083dc #f8ffe5 #7dde92" />
    <ColorOption id="1" displayName="urban_label" colors="#f4b393 #fc60a8 #7a28cb" />
  </ColorConfiguration>
</UserConfigurations>

These can then be used as data sources instead of hexadecimal color values. Note how the index value is specified to select the first, second, or third element of the theme:

<HourHand resource="hour" ... tintColor="[CONFIGURATION.myThemeColor.0]" />
<MinuteHand resource="minute" ... tintColor="[CONFIGURATION.myThemeColor.1]" />
<SecondHand resource="second" ... tintColor="[CONFIGURATION.myThemeColor.2]" />

In the specific case where each ColorOption only has one color defined, it is also possible to reference it as CONFIGURATION.myThemeColor, without the index.

The user can then select the theme entry of their choice in the watch face editor.

Flavors

Note: Flavors are supported on version 2 and higher of Watch Face Format.

UserConfigurations provide the user with a lot of flexibility, but as you increase the number of configuration elements you define, the number of combinations can grow overwhelmingly.

Flavors lets you define presets for the UserConfigurations that you think are worth highlighting.

The user can then select from these preset flavors within the companion app, or continue to choose each configuration value individually.

For example, consider a watch face where you define three settings (inner elements and details of attributes have been omitted for clarity):

<UserConfigurations>
  <ColorConfiguration id="themeColor" ...>
    <ColorOption id="0" displayName="bright_label" ... />
    <ColorOption id="1" displayName="monochrome_label" ... />
  </ColorConfiguration>
  <ListConfiguration id="clockAppearance" ... >
    <ListOption id="0" displayName="big_and_bold_label" ... />
    <ListrOption id="1" displayName="minimal_label" ... />
  </ListConfiguration>
  <BooleanConfiguration id="showHr" ... />
</UserConfigurations>

You have defined:

A color theme configuration, allowing the user to select which color theme to apply. You've defined two themes, one colorful and one monochrome.
A list of clock appearance choices. You've defined two choices, a big bold clock and a more minimal looking clock.
A choice of whether to show the user's heart rate on the watch face.

Furthermore, you have a ComplicationSlot on the watch face.

You decide that there are two Flavors that you want to highlight to the user. There are many more possible combinations of all these settings, but these are the ones you think work best:

A sporty flavor: This will consist of:
1. The bright color theme, to energize you and get you active (ID: 0)
2. The big and bold clock, so it can be seen whilst working out (ID: 0)
3. Heart rate showing on the watch face for reference
4. The complication slot showing step count
A sophisticated flavor: This will consist of:
1. The monochrome color theme, to match any outfit (ID: 1)
2. The minimal clock, to fit well with any environment (ID: 1)
3. No heart rate showing on the watch face
4. The complication slot not enabled

Flavors require enabling in watch_face_info.xml:

<?xml version="1.0" encoding="utf-8"?>
<WatchFaceInfo>
    ...
    <MultipleInstancesAllowed value="true" />
    <FlavorsSupported value="true" />
</WatchFaceInfo>

Then, each Flavor is defined within UserConfigurations as follows:

<Flavors defaultValue="sportyFlavor">
  <Flavor id="sportyFlavor" ... >
    <Configuration id="themeColor" optionId="0"/>
    <Configuration id="clockAppearance" optionId="0"/>
    <Configuration id="showHr" optionId="TRUE"/>
    <ComplicationSlot slotId="0">
      <DefaultProviderPolicy
              defaultSystemProvider="STEP_COUNT"
              defaultSystemProviderType="SHORT_TEXT"/>
    </ComplicationSlot>
  </Flavor>
  <Flavor id="sophisticatedFlavor" ... >
    <Configuration id="themeColor" optionId="1"/>
    <Configuration id="clockAppearance" optionId="1"/>
    <Configuration id="showHr" optionId="FALSE"/>
    <ComplicationSlot slotId="0">
      <!--
        Type here is set to empty to demonstrate how to hide a complication
        slot in Flavors.
      -->
      <DefaultProviderPolicy
              defaultSystemProvider="SUNRISE_SUNSET"
              defaultSystemProviderType="EMPTY"/>
    </ComplicationSlot>
  </Flavor>
</Flavors>

Define user configurations Stay organized with collections Save and categorize content based on your preferences.

Boolean options

List options

Color themes

Flavors

Define user configurations
Stay organized with collections Save and categorize content based on your preferences.