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
|
Icon
|
getBurnInProtectionSmallImage()
Returns the burn-in protection version of the small image field for this complication,
or |
ComplicationText
|
getContentDescription()
Returns the content description override field for this complication, for screen readers. |
Icon
|
getIcon()
Returns the icon field for this complication, or |
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 |
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 |
ComplicationText
|
getShortTitle()
Returns the short title field for this complication, or |
Icon
|
getSmallImage()
Returns the small image field for this complication, or |
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
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 |
|
See also:
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 |
|
Content and code samples on this page are subject to the licenses described in the Content License. Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
Last updated 2024-04-11 UTC.