ComplicationData

public class ComplicationData
extends Object implements Parcelable

java.lang.Object
   ↳ android.support.wearable.complications.ComplicationData

This class is deprecated.
use the Jetpack Wear Watch Face libraries instead.

Container for complication data of all types.

A ComplicationProviderService should create instances of this class using ComplicationData.Builder and send them to the complication system by calling ComplicationManager.updateComplicationData(int, ComplicationData). Depending on the type of complication data, some fields will be required and some will be optional - see the documentation for each type, and for the builder's set methods, for details.

A watch face will receive instances of this class via its onComplicationDataUpdate method, as long as providers are configured and setActiveComplications has been called.

When rendering the complication data for a given time, the watch face should first call isActive(long) to determine whether the data is valid at that time. See the documentation for each of the complication types below for details of which fields are expected to be displayed.

Summary

Nested classes

class ComplicationData.Builder

This class is deprecated. use the Jetpack Wear Watch Face libraries instead.  

@interface ComplicationData.ComplicationType

This @interface is deprecated. use the Jetpack Wear Watch Face libraries instead.  

@interface ComplicationData.ImageStyle

This @interface is deprecated. use the Jetpack Wear Watch Face libraries instead.  

Constants

int IMAGE_STYLE_ICON

Style for small images that have a transparent background and are expected to be drawn entirely within the space available, such as a launcher icon.

int IMAGE_STYLE_PHOTO

Style for small images which are photos that are expected to fill the space available.

int TYPE_EMPTY

Type sent when the user has specified that an active complication should have no provider, i.e.

int TYPE_ICON

Type used for complications which consist only of a tintable icon.

int TYPE_LARGE_IMAGE

Type used for complications which consist only of a large image.

int TYPE_LONG_TEXT

Type used for complications where the primary piece of data is a piece of text.

int TYPE_NOT_CONFIGURED

Type sent when a complication does not have a provider configured.

int TYPE_NO_DATA

Type that can be sent by any provider, regardless of the configured type, when the provider has no data to be displayed.

int TYPE_NO_PERMISSION

Type sent by the system when the watch face does not have permission to receive complication data.

int TYPE_RANGED_VALUE

Type used for complications including a numerical value within a range, such as a percentage.

int TYPE_SHORT_TEXT

Type used for complications where the primary piece of data is a short piece of text (expected to be no more than seven characters in length).

int TYPE_SMALL_IMAGE

Type used for complications which consist only of a small image.

Inherited constants

Fields

public static final Creator<ComplicationData> CREATOR

Public methods

int describeContents()
Icon getBurnInProtectionIcon()

Returns the burn-in protection version of the icon field for this complication, or null if no such icon was provided.

Icon getBurnInProtectionSmallImage()

Returns the burn-in protection version of the small image field for this complication, or null if no such icon was provided.

ComplicationText getContentDescription()

Returns the content description override field for this complication, for screen readers.

Icon getIcon()

Returns the icon field for this complication, or null if no value was provided for the field.

ComplicationText getImageContentDescription()

Returns the image content description field for this complication, for screen readers.

int getImageStyle()

Returns the image style field for this complication.

Icon getLargeImage()

Returns the large image field for this complication.

ComplicationText getLongText()

Returns the long text field for this complication.

ComplicationText getLongTitle()

Returns the long title field for this complication, or null if no value was provided for the field.

float getMaxValue()

Returns the max value field for this complication.

float getMinValue()

Returns the min value field for this complication.

ComplicationText getShortText()

Returns the short text field for this complication, or null if no value was provided for the field.

ComplicationText getShortTitle()

Returns the short title field for this complication, or null if no value was provided for the field.

Icon getSmallImage()

Returns the small image field for this complication, or null if no value was provided for the field.

PendingIntent getTapAction()

Returns the tap action field for this complication.

int getType()

Returns the type of this complication data.

float getValue()

Returns the value field for this complication.

boolean isActive(long dateTimeMillis)

Returns true if the complication is active and should be displayed at the given time.

String toString()
void writeToParcel(Parcel dest, int flags)

Inherited methods

Constants

IMAGE_STYLE_ICON

public static final int IMAGE_STYLE_ICON

Style for small images that have a transparent background and are expected to be drawn entirely within the space available, such as a launcher icon. Watch faces may add padding when drawing these images, but should never crop these images.

Constant Value: 2 (0x00000002)

IMAGE_STYLE_PHOTO

public static final int IMAGE_STYLE_PHOTO

Style for small images which are photos that are expected to fill the space available. Images of this style may be cropped to fit the shape of the complication - in particular, the image may be cropped to a circle.

This is the default value.

Constant Value: 1 (0x00000001)

TYPE_EMPTY

public static final int TYPE_EMPTY

Type sent when the user has specified that an active complication should have no provider, i.e. when the user has chosen "Empty" in the provider chooser. Providers cannot send data of this type.

No fields may be populated for complication data of this type.

Constant Value: 2 (0x00000002)

TYPE_ICON

public static final int TYPE_ICON

Type used for complications which consist only of a tintable icon.

The icon field is required for this type, and is expected to always be displayed, unless the device is in ambient mode with burn-in protection enabled, in which case the burnInProtectionIcon field should be used instead.

The contentDescription field is recommended for this type. Use it to describe what data the icon represents. If the icon is purely stylistic, and does not convey any information to the user, then enter the empty string as the contentDescription.

No other fields are valid for this type.

Constant Value: 6 (0x00000006)

TYPE_LARGE_IMAGE

public static final int TYPE_LARGE_IMAGE

Type used for complications which consist only of a large image. A large image here is one that could be used to fill the watch face, for example as the background.

The large image field is required for this type, and is expected to always be displayed, unless the device is in ambient mode.

The contentDescription field is recommended for this type. Use it to describe what data the image represents. If the image is purely stylistic, and does not convey any information to the user, then enter the empty string as the contentDescription.

No other fields are valid for this type.

Constant Value: 8 (0x00000008)

TYPE_LONG_TEXT

public static final int TYPE_LONG_TEXT

Type used for complications where the primary piece of data is a piece of text. The text may be accompanied by an icon and/or a title.

The long text field is required for this type, and is expected to always be displayed.

The long title field is optional for this type. If provided, it is expected that this field will be displayed.

The icon (and burnInProtectionIcon) and small image fields are also optional for this type. If provided, at least one of these should be displayed.

Constant Value: 4 (0x00000004)

TYPE_NOT_CONFIGURED

public static final int TYPE_NOT_CONFIGURED

Type sent when a complication does not have a provider configured. The system will send data of this type to watch faces when the user has not chosen a provider for an active complication, and the watch face has not set a default provider. Providers cannot send data of this type.

No fields may be populated for complication data of this type.

Constant Value: 1 (0x00000001)

TYPE_NO_DATA

public static final int TYPE_NO_DATA

Type that can be sent by any provider, regardless of the configured type, when the provider has no data to be displayed. Watch faces may choose whether to render this in some way or leave the slot empty.

No fields may be populated for complication data of this type.

Constant Value: 10 (0x0000000a)

TYPE_NO_PERMISSION

public static final int TYPE_NO_PERMISSION

Type sent by the system when the watch face does not have permission to receive complication data.

Fields will be populated to allow the data to be rendered as if it were of TYPE_SHORT_TEXT or TYPE_ICON for consistency and convenience, but watch faces may render this as they see fit.

It is recommended that, where possible, tapping on the complication when in this state should trigger a permission request. A ComplicationHelperActivity may be used to make this request and update all complications if permission is granted.

Constant Value: 9 (0x00000009)

TYPE_RANGED_VALUE

public static final int TYPE_RANGED_VALUE

Type used for complications including a numerical value within a range, such as a percentage. The value may be accompanied by an icon and/or short text and title.

The value, min value, and max value fields are required for this type, and the value within the range is expected to always be displayed.

The icon (and burnInProtectionIcon), short title, and short text fields are optional for this type. The watch face may choose which of these fields to display, if any.

Constant Value: 5 (0x00000005)

TYPE_SHORT_TEXT

public static final int TYPE_SHORT_TEXT

Type used for complications where the primary piece of data is a short piece of text (expected to be no more than seven characters in length). The short text may be accompanied by an icon or a short title (or both, but if both are provided then a watch face may choose to display only one).

The short text field is required for this type, and is expected to always be displayed.

The icon (and burnInProtectionIcon) and short title fields are optional for this type. If only one of these is provided, it is expected that it will be displayed. If both are provided, it is expected that one of these will be displayed.

Constant Value: 3 (0x00000003)

TYPE_SMALL_IMAGE

public static final int TYPE_SMALL_IMAGE

Type used for complications which consist only of a small image.

The small image field is required for this type, and is expected to always be displayed, unless the device is in ambient mode, in which case either nothing or the burnInProtectionSmallImage field may be used instead.

The contentDescription field is recommended for this type. Use it to describe what data the image represents. If the image is purely stylistic, and does not convey any information to the user, then enter the empty string as the contentDescription.

No other fields are valid for this type.

Constant Value: 7 (0x00000007)

Fields

CREATOR

public static final Creator<ComplicationData> CREATOR

Public methods

describeContents

public int describeContents ()

Returns
int

getBurnInProtectionIcon

public Icon getBurnInProtectionIcon ()

Returns the burn-in protection version of the icon field for this complication, or null if no such icon was provided. The image returned is expected to be an outline image suitable for use in ambient mode on screens with burn-in protection. The image is also expected to be single-color and so may be tinted to whatever color the watch face requires (but note that Drawable.mutate() should be called before drawables are tinted, and that the color used should be suitable for ambient mode with burn-in protection).

If the device is in ambient mode, and utilises burn-in protection, then the result of this method must be used instead of the result of getIcon().

Valid for the types TYPE_SHORT_TEXT, TYPE_LONG_TEXT, TYPE_RANGED_VALUE, TYPE_ICON, or TYPE_NO_PERMISSION.

Returns
Icon

getBurnInProtectionSmallImage

public Icon getBurnInProtectionSmallImage ()

Returns the burn-in protection version of the small image field for this complication, or null if no such icon was provided. The image returned is expected to be an outline image suitable for use in ambient mode on screens with burn-in protection. The image is also expected to be single-color and so may be tinted to whatever color the watch face requires (but note that Drawable.mutate() should be called before drawables are tinted, and that the color used should be suitable for ambient mode with burn-in protection).

If the device is in ambient mode, and utilises burn-in protection, then the result of this method must be used instead of the result of getSmallImage().

Valid for the types TYPE_LONG_TEXT and TYPE_SMALL_IMAGE.

Returns
Icon

getContentDescription

public ComplicationText getContentDescription ()

Returns the content description override field for this complication, for screen readers.

Valid for all non-empty types.

Returns
ComplicationText

getIcon

public Icon getIcon ()

Returns the icon field for this complication, or null if no value was provided for the field. The image returned is expected to be single-color and so may be tinted to whatever color the watch face requires (but note that Drawable.mutate() should be called before drawables are tinted).

If the device is in ambient mode, and utilises burn-in protection, then the result of getBurnInProtectionIcon() must be used instead of this.

Valid for the types TYPE_SHORT_TEXT, TYPE_LONG_TEXT, TYPE_RANGED_VALUE, TYPE_ICON, or TYPE_NO_PERMISSION.

Returns
Icon

getImageContentDescription

public ComplicationText getImageContentDescription ()

Returns the image content description field for this complication, for screen readers.

Valid for types that include the icon, large image, or small image fields.

Returns
ComplicationText

getImageStyle

public int getImageStyle ()

Returns the image style field for this complication.

The result of this method should be taken in to account when drawing a small image complication.

Valid only for types that contain small images, i.e. TYPE_SMALL_IMAGE and TYPE_LONG_TEXT.

Returns
int

getLargeImage

public Icon getLargeImage ()

Returns the large image field for this complication. This image is expected to be of a suitable size to fill the screen of the watch.

As this may be any image, it is unlikely to be suitable for display in ambient mode when burn-in protection is enabled, or in low-bit ambient mode, and should not be rendered under these circumstances.

Valid only if the type of this complication data is TYPE_LARGE_IMAGE.

Returns
Icon

getLongText

public ComplicationText getLongText ()

Returns the long text field for this complication.

The value is provided as a ComplicationText object, from which the text to display can be obtained for a given point in time.

Valid only if the type of this complication data is TYPE_LONG_TEXT.

Returns
ComplicationText

getLongTitle

public ComplicationText getLongTitle ()

Returns the long title field for this complication, or null if no value was provided for the field.

The value is provided as a ComplicationText object, from which the text to display can be obtained for a given point in time.

Valid only if the type of this complication data is TYPE_LONG_TEXT.

Returns
ComplicationText

getMaxValue

public float getMaxValue ()

Returns the max value field for this complication.

Valid only if the type of this complication data is TYPE_RANGED_VALUE.

Returns
float

getMinValue

public float getMinValue ()

Returns the min value field for this complication.

Valid only if the type of this complication data is TYPE_RANGED_VALUE.

Returns
float

getShortText

public ComplicationText getShortText ()

Returns the short text field for this complication, or null if no value was provided for the field.

The value is provided as a ComplicationText object, from which the text to display can be obtained for a given point in time.

The length of the text, including any time-dependent values at any valid time, is expected to not exceed seven characters. When using this text, the watch face should be able to display any string of up to seven characters (reducing the text size appropriately if the string is very wide). Although not expected, it is possible that strings of more than seven characters might be seen, in which case they may be truncated.

Valid only if the type of this complication data is TYPE_SHORT_TEXT, TYPE_RANGED_VALUE, or TYPE_NO_PERMISSION.

Returns
ComplicationText

getShortTitle

public ComplicationText getShortTitle ()

Returns the short title field for this complication, or null if no value was provided for the field.

The value is provided as a ComplicationText object, from which the text to display can be obtained for a given point in time.

The length of the text, including any time-dependent values at any valid time, is expected to not exceed seven characters. When using this text, the watch face should be able to display any string of up to seven characters (reducing the text size appropriately if the string is very wide). Although not expected, it is possible that strings of more than seven characters might be seen, in which case they may be truncated.

Valid only if the type of this complication data is TYPE_SHORT_TEXT, TYPE_RANGED_VALUE, or TYPE_NO_PERMISSION.

Returns
ComplicationText

getSmallImage

public Icon getSmallImage ()

Returns the small image field for this complication, or null if no value was provided for the field.

This may be either a photo style image, which is expected to fill the space available, or an icon style image, which should be drawn entirely within the space available. Use getImageStyle() to determine which of these applies.

As this may be any image, it is unlikely to be suitable for display in ambient mode when burn-in protection is enabled, or in low-bit ambient mode, and should not be rendered under these circumstances.

Valid for the types TYPE_LONG_TEXT and TYPE_SMALL_IMAGE.

Returns
Icon

getTapAction

public PendingIntent getTapAction ()

Returns the tap action field for this complication. The result is a PendingIntent that should be fired if the complication is tapped on, assuming the complication is tappable, or null if no tap action has been specified.

Valid for all non-empty types.

Returns
PendingIntent

getType

public int getType ()

Returns the type of this complication data.

Will be one of TYPE_SHORT_TEXT, TYPE_LONG_TEXT, TYPE_RANGED_VALUE, TYPE_ICON, TYPE_SMALL_IMAGE, TYPE_LARGE_IMAGE, TYPE_NOT_CONFIGURED, TYPE_EMPTY, TYPE_NO_PERMISSION, or TYPE_NO_DATA.

Returns
int

getValue

public float getValue ()

Returns the value field for this complication.

Valid only if the type of this complication data is TYPE_RANGED_VALUE.

Returns
float

isActive

public boolean isActive (long dateTimeMillis)

Returns true if the complication is active and should be displayed at the given time. If this returns false, the complication should not be displayed.

This must be checked for any time for which the complication will be displayed.

Parameters
dateTimeMillis long

Returns
boolean

toString

public String toString ()

Returns
String

writeToParcel

public void writeToParcel (Parcel dest, 
                int flags)

Parameters
dest Parcel

flags int