ComplicationData.Builder

public static final class ComplicationData.Builder
extends Object

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

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

Builder class for ComplicationData.

Summary

Public constructors

Builder(int type)

Public methods

ComplicationData build()

Constructs and returns ComplicationData with the provided fields.

ComplicationData.Builder setBurnInProtectionIcon(Icon icon)

Sets the burn-in protection version of the icon field.

ComplicationData.Builder setBurnInProtectionSmallImage(Icon smallImage)

Sets the burn-in protection version of the small image field.

ComplicationData.Builder setContentDescription(ComplicationText description)

This method is deprecated. Use setImageContentDescription(ComplicationText) instead.

ComplicationData.Builder setEndTime(long endTime)

Sets the end time for this complication data.

ComplicationData.Builder setIcon(Icon icon)

Sets the icon field.

ComplicationData.Builder setImageContentDescription(ComplicationText description)

Sets the content description for an image or icon field for accessibility.

ComplicationData.Builder setImageStyle(int imageStyle)

Sets the display style for this complication data.

ComplicationData.Builder setLargeImage(Icon largeImage)

Sets the large image field.

ComplicationData.Builder setLongText(ComplicationText longText)

Sets the long text field.

ComplicationData.Builder setLongTitle(ComplicationText longTitle)

Sets the long title field.

ComplicationData.Builder setMaxValue(float maxValue)

Sets the max value field.

ComplicationData.Builder setMinValue(float minValue)

Sets the min value field.

ComplicationData.Builder setShortText(ComplicationText shortText)

Sets the short text field.

ComplicationData.Builder setShortTitle(ComplicationText shortTitle)

Sets the short title field.

ComplicationData.Builder setSmallImage(Icon smallImage)

Sets the small image field.

ComplicationData.Builder setStartTime(long startTime)

Sets the start time for this complication data.

ComplicationData.Builder setTapAction(PendingIntent pendingIntent)

Sets the tap action field.

ComplicationData.Builder setValue(float value)

Sets the value field.

Inherited methods

Public constructors

Builder

public Builder (int type)

Parameters
type int

Public methods

build

public ComplicationData build ()

Constructs and returns ComplicationData with the provided fields. All required fields must be populated before this method is called.

Returns
ComplicationData

Throws
IllegalStateException if the required fields have not been populated

setBurnInProtectionIcon

public ComplicationData.Builder setBurnInProtectionIcon (Icon icon)

Sets the burn-in protection version of the icon field. This should be provided if the icon field is provided, unless the main icon is already safe for use with burn-in protection.

The provided image must be single-color, so that watch faces can tint it as required.

The provided image must not contain solid blocks of pixels - it should instead be composed of outlines or lines only.

If this field is set, the icon field must also be set.

Returns this Builder to allow chaining.

Parameters
icon Icon

Returns
ComplicationData.Builder

Throws
IllegalStateException if this field is not valid for the complication type

setBurnInProtectionSmallImage

public ComplicationData.Builder setBurnInProtectionSmallImage (Icon smallImage)

Sets the burn-in protection version of the small image field. This should be provided if the small image field is provided, unless the main small image is already safe for use with burn-in protection.

The provided image must not contain solid blocks of pixels - it should instead be composed of outlines or lines only.

If this field is set, the small image field must also be set.

Returns this Builder to allow chaining.

Parameters
smallImage Icon

Returns
ComplicationData.Builder

Throws
IllegalStateException if this field is not valid for the complication type

setContentDescription

public ComplicationData.Builder setContentDescription (ComplicationText description)

This method is deprecated.
Use setImageContentDescription(ComplicationText) instead.

Sets the content description override field for accessibility. This is optional for all non-empty types. Only use this if you want to override the system default of creating a content description from the short/long/range text and title fields.

Note: If you simply want to add a content description for an image or icon included in your complication, use setImageContentDescription(ComplicationText) so that the other text fields will still be read automatically by the accessibility system.

The provided text will be read aloud by a Text-to-speech converter for users who may be vision-impaired. It should describe all the information in your complication in a natural way, preferably in the user's currently selected Locale. If not provided, the TTS converter will synthesize a description from the textual information in the complication.

For example, for a weather complication, you might set as your description: "Eleven degrees celsius and raining in San Francisco."

Do not set if your complication contains other information besides an image, like text, title, or range, since setContentDescription will override the automatic vocalization of those textual fields. If you set this field, make sure it contains all information that is provided by the other text fields.

Returns this Builder to allow chaining.

Parameters
description ComplicationText

Returns
ComplicationData.Builder

setEndTime

public ComplicationData.Builder setEndTime (long endTime)

Sets the end time for this complication data. This is optional for any type.

The complication data will be considered inactive (i.e. should not be displayed) if the current time is greater than the end time. If not specified, the data is considered active for all time after the start time (or always active if start time is also not specified).

Returns this Builder to allow chaining.

Parameters
endTime long

Returns
ComplicationData.Builder

setIcon

public ComplicationData.Builder setIcon (Icon icon)

Sets the icon field. This is required for the ComplicationData.TYPE_ICON type, and is optional for the ComplicationData.TYPE_SHORT_TEXT, ComplicationData.TYPE_LONG_TEXT, ComplicationData.TYPE_RANGED_VALUE, and ComplicationData.TYPE_NO_PERMISSION types.

The provided image must be single-color, so that watch faces can tint it as required.

If the icon provided here is not suitable for display in ambient mode with burn-in protection (e.g. if it includes solid blocks of pixels), then a burn-in safe version of the icon must be provided via setBurnInProtectionIcon(Icon).

Returns this Builder to allow chaining.

Parameters
icon Icon

Returns
ComplicationData.Builder

Throws
IllegalStateException if this field is not valid for the complication type

setImageContentDescription

public ComplicationData.Builder setImageContentDescription (ComplicationText description)

Sets the content description for an image or icon field for accessibility. This is optional for any type that includes the icon, large image, or small image fields. It is recommended to provide an image content description whenever the data includes an image.

The provided text will be read aloud by a Text-to-speech converter for users who may be vision-impaired. It will be read aloud in addition to any long, short, or range text in the complication.

This differs from setContentDescription(ComplicationText) in that it does not override the other text fields: all textual fields, including this one, will be read aloud by screen readers.

If using to describe an image/icon that is purely stylistic and doesn't convey any information to the user, you may set the image content description to an empty string ("").

Returns this Builder to allow chaining.

Parameters
description ComplicationText

Returns
ComplicationData.Builder

setImageStyle

public ComplicationData.Builder setImageStyle (int imageStyle)

Sets the display style for this complication data. This is valid only for types that contain small images, i.e. ComplicationData.TYPE_SMALL_IMAGE and ComplicationData.TYPE_LONG_TEXT.

This affects how watch faces will draw the image in the complication.

If not specified, the default is ComplicationData.IMAGE_STYLE_PHOTO.

Parameters
imageStyle int

Returns
ComplicationData.Builder

Throws
IllegalStateException if this field is not valid for the complication type

setLargeImage

public ComplicationData.Builder setLargeImage (Icon largeImage)

Sets the large image field. This is required for the ComplicationData.TYPE_LARGE_IMAGE type, and is not valid for any other type.

The provided image should be suitably sized to fill the screen of the watch.

Returns this Builder to allow chaining.

Parameters
largeImage Icon

Returns
ComplicationData.Builder

Throws
IllegalStateException if this field is not valid for the complication type

setLongText

public ComplicationData.Builder setLongText (ComplicationText longText)

Sets the long text field. This is required for the ComplicationData.TYPE_LONG_TEXT type, and is not valid for any other type.

The value must be provided as a ComplicationText object, so that time-dependent values may be included.

Returns this Builder to allow chaining.

Parameters
longText ComplicationText

Returns
ComplicationData.Builder

Throws
IllegalStateException if this field is not valid for the complication type

setLongTitle

public ComplicationData.Builder setLongTitle (ComplicationText longTitle)

Sets the long title field. This is optional for the ComplicationData.TYPE_LONG_TEXT type, and is not valid for any other type.

The value must be provided as a ComplicationText object, so that time-dependent values may be included.

Returns this Builder to allow chaining.

Parameters
longTitle ComplicationText

Returns
ComplicationData.Builder

Throws
IllegalStateException if this field is not valid for the complication type

setMaxValue

public ComplicationData.Builder setMaxValue (float maxValue)

Sets the max value field. This is required for the ComplicationData.TYPE_RANGED_VALUE type, and is not valid for any other type.

Returns this Builder to allow chaining.

Parameters
maxValue float

Returns
ComplicationData.Builder

Throws
IllegalStateException if this field is not valid for the complication type

setMinValue

public ComplicationData.Builder setMinValue (float minValue)

Sets the min value field. This is required for the ComplicationData.TYPE_RANGED_VALUE type, and is not valid for any other type.

Returns this Builder to allow chaining.

Parameters
minValue float

Returns
ComplicationData.Builder

Throws
IllegalStateException if this field is not valid for the complication type

setShortText

public ComplicationData.Builder setShortText (ComplicationText shortText)

Sets the short text field. This is required for the ComplicationData.TYPE_SHORT_TEXT type, is optional for the ComplicationData.TYPE_RANGED_VALUE and ComplicationData.TYPE_NO_PERMISSION types, and is not valid for any other type.

The value must be provided as a ComplicationText object, so that time-dependent values may be included.

The length of the text, including any time-dependent values, should not exceed seven characters. If it does, the text may be truncated by the watch face or might not fit in the complication.

Returns this Builder to allow chaining.

Parameters
shortText ComplicationText

Returns
ComplicationData.Builder

Throws
IllegalStateException if this field is not valid for the complication type

setShortTitle

public ComplicationData.Builder setShortTitle (ComplicationText shortTitle)

Sets the short title field. This is valid for the ComplicationData.TYPE_SHORT_TEXT, ComplicationData.TYPE_RANGED_VALUE, and ComplicationData.TYPE_NO_PERMISSION types, and is not valid for any other type.

The value must be provided as a ComplicationText object, so that time-dependent values may be included.

The length of the text, including any time-dependent values, should not exceed seven characters. If it does, the text may be truncated by the watch face or might not fit in the complication.

Returns this Builder to allow chaining.

Parameters
shortTitle ComplicationText

Returns
ComplicationData.Builder

Throws
IllegalStateException if this field is not valid for the complication type

setSmallImage

public ComplicationData.Builder setSmallImage (Icon smallImage)

Sets the small image field. This is required for the ComplicationData.TYPE_SMALL_IMAGE type, and is optional for the ComplicationData.TYPE_LONG_TEXT type.

Returns this Builder to allow chaining.

Parameters
smallImage Icon

Returns
ComplicationData.Builder

Throws
IllegalStateException if this field is not valid for the complication type

setStartTime

public ComplicationData.Builder setStartTime (long startTime)

Sets the start time for this complication data. This is optional for any type.

The complication data will be considered inactive (i.e. should not be displayed) if the current time is less than the start time. If not specified, the data is considered active for all time up to the end time (or always active if end time is also not specified).

Returns this Builder to allow chaining.

Parameters
startTime long

Returns
ComplicationData.Builder

setTapAction

public ComplicationData.Builder setTapAction (PendingIntent pendingIntent)

Sets the tap action field. This is optional for any non-empty type.

The provided PendingIntent may be fired if the complication is tapped on. Note that some complications might not be tappable, in which case this field will be ignored.

Returns this Builder to allow chaining.

Parameters
pendingIntent PendingIntent

Returns
ComplicationData.Builder

setValue

public ComplicationData.Builder setValue (float value)

Sets the value field. This is required for the ComplicationData.TYPE_RANGED_VALUE type, and is not valid for any other type.

Returns this Builder to allow chaining.

Parameters
value float

Returns
ComplicationData.Builder

Throws
IllegalStateException if this field is not valid for the complication type