Provide useful data through complications

Complications are a feature of both physical and smartwatch watch faces that show additional information. Typically the user selects what information is shown in a complication.

Typically complications come in a number of shapes:

  1. Rectangular
  2. Circular
  3. Arcs, along the edge of the watch face
  4. Background, covering the whole of the watch face

In Wear OS, the Complication system can be broken down into two parts:

  1. The Complication data source
  2. The Complication rendering

For example, a health and fitness app might implement a Daily Steps complication data source. This could be rendered by the WFF watch face.

Data sources in complications

Complication data sources specify only the data to be rendered, and the type of complication. The data source plays no part in determining how the data should be represented on the watch face.

For example, the health and fitness Daily Steps complication data source may produce the following data to indicate the user has taken 2400 of their target 10000 steps today:

Note that there is nothing in this data that indicates how this should be rendered.

The watch face specifies what types of complication it is capable of rendering. This determines which data sources are then available for the user to select from.

In the case of the Daily Steps example, you decide in your watch face definition how to render the Value and TargetValue: would it be as text, or as a progress indicator? That is for you as the watch face designer to decide.

Define complications

Offering the ability to show complications on your watch face can be valuable to users, as it allows them to have a greater range of information at a glance and customized to their needs.

Decide if and how many complications to support on your watch face, what their shapes and positioning will be, and what types of data they support.

Each space on the watch face for a complication is defined as a ComplicationSlot within which a bounding area is defined for the rendering of the complication:

<ComplicationSlot slotId="1" supportedTypes="SHORT_TEXT SMALL_IMAGE EMPTY"
    x="0" y="0" width="225" height="225">
    <BoundingArc centerX="225" centerY="225" width="450" height="450"
        startAngle="270" endAngle="360" thickness="50" />
  <Complication type="SHORT_TEXT">
      <!-- Complication content for rendering SHORT_TEXT data goes here -->
  </Complication>
  <Complication type="SMALL_IMAGE">
      <!-- Complication content for rendering SMALL_IMAGE data goes here -->
  </Complication>
</ComplicationSlot>

A similar approach can be applied to the other bounding shapes such as rectangle and ellipse.

Set the complication type and defaults

The complication system provides a number of different types, which allows the watch face to express what type of data it can represent on the screen. For example, an Arc complication, as shown previously, isn't a great fit for an image-based complication data type such as SMALL_IMAGE, but could work very well for numeric data such as RANGED_VALUE.

In your ComplicationSlot declaration, set supportedTypes to the space-separated list of the types that can be rendered in this slot.

You must also set the default source for the ComplicationSlot unless you allow the EMPTY type, in which case setting a default is optional:

<ComplicationSlot slotId="1" ...>
    <BoundingArc .../>
    <DefaultProviderPolicy
        defaultSystemProvider="STEP_COUNT"
        defaultSystemProviderType="SHORT_TEXT" />
</ComplicationSlot>

In addition to having to specify system providers, you can optionally specify non-system providers, such as third-party providers to use by default, if they are already installed.

Render complication data

Having defined the ComplicationSlot, bounds, and containing Complication element, use standard WFF components, such as PartDraw, PartImage and PartText to display the Complication data.

Elements within the Complication data have access to a special data source: COMPLICATION, which provides the various data properties set by the complication data source.

For example, a SMALL_IMAGE complication can set the COMPLICATION.SMALL_IMAGE and COMPLICATION.SMALL_IMAGE_AMBIENT values. These can be used instead of resource in an Image element:

<Complication type="SMALL_IMAGE">
  <PartImage ...>
    <Image resource="[COMPLICATION.SMALL_IMAGE]" />
  </PartImage>
</Complication>

Each different complication type has a different set of available properties that can be set; for a full list of each, see the Complication reference. This example displays the text from a SHORT_TEXT complication:

<Complication type="SHORT_TEXT">
  <PartText ...>
    <Text>
      <Font ...>
        <Template>
          <![CDATA[%s]]><Parameter expression="[COMPLICATION.TEXT]" />
        </Template>
      </Font>
  </PartImage>
</Complication>

Maximize usefulness when rendering complications

There are a number of challenges when adding ComplicationSlots to your watch face:

  1. There are numerous Complication data types. Different apps may provide one or many of these.
  2. Each Complication data type, as well as having mandatory properties also has many optional properties. Check that the most useful rendering is made from the available properties, taking into account the different combinations.

To address these issues, some strategies include:

  1. Support multiple complication types for each slot. For example, SHORT_TEXT is quite widely supported by complication data sources, so supporting a number of different types, such as SHORT_TEXT RANGED_VALUE for a small circular complication, increases compatibility.
  2. Offer different complication types across the watch face. For example, you could support RANGED_VALUE and GOAL_PROGRESS on edge-positioned Arc complications, and SHORT_TEXT and SMALL_IMAGE on circular complications in the body of the watch face.
  3. Check for optional elements for each data type. For example, SHORT_TEXT optionally supports a title property and an image. Your layout for rendering the available data might differ depending on whether an image or title is available or not.