RangedValueComplicationData


class RangedValueComplicationData : ComplicationData


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 min and max fields are required for this type, as well as one of value or dynamicValue. The value within the range is expected to always be displayed.

The icon, title, and text fields are optional and the watch face may choose which of these fields to display, if any.

If a monochromaticImage and a smallImage are both specified then only one should be displayed. If the complication is drawn with a single color it's recommended to choose monochromaticImage and apply a tint. If the complication is rendered with multiple colors it's recommended to choose the smallImage. It's best practice for a ComplicationDataSource to specify both a monochromaticImage and a smallImage.

A data source that wants to serve a RangedValueComplicationData must include the following meta data in its manifest (NB the value is a comma separated list):

<meta-data android:name="android.support.wearable.complications.SUPPORTED_TYPES"
android:value="RANGED_VALUE"/>

Summary

Constants

const Int

The ranged value represents a percentage in the range 0..100.

const Int

The ranged value represents a rating or score for something unrelated to the user, e.g. the air quality index or the UV index.

const Int

The ranged value's semantic hasn't been explicitly defined, most commonly it's a percentage however.

Public companion properties

Float

Used to signal the range should be rendered as a placeholder.

ComplicationType

The ComplicationType corresponding to objects of this type.

Public functions

open Instant

Returns the next Instant after afterInstant at which any field of the complication may change.

open Boolean

Returns true if any of the fields of this ComplicationData are placeholders.

open String

Public properties

ColorRamp?

Optional hint to render the value with the specified ColorRamp.

ComplicationText?

The content description field for accessibility.

DynamicBuilders.DynamicFloat?

The DynamicFloat optionally set by the data source.

Float

The maximum Float value for this complication.

Float

The minimum Float value for this complication.

MonochromaticImage?

A simple MonochromaticImage image that can be tinted by the watch face.

SmallImage?

A SmallImage that is expected to cover a small fraction of a watch face occupied by a single complication.

ComplicationText?

The body ComplicationText of the complication.

ComplicationText?

The optional title ComplicationText.

Float

The Float value of this complication which is >= min and <= max or equal to PLACEHOLDER.

Int

The semantic meaning of value.

Inherited functions

From androidx.wear.watchface.complications.data.ComplicationData
open operator Boolean
equals(other: Any?)
open Int

Inherited properties

From androidx.wear.watchface.complications.data.ComplicationData
ComponentName?

The ComponentName of the androidx.wear.watchface.complications.datasource.ComplicationDataSourceService that provided the ComplicationData.

Int

The display policy for this complication.

ComplicationData?

Used in case any dynamic value has been invalidated.

Int

The persistence policy for this complication.

PendingIntent?

The PendingIntent to send when the complication is tapped on.

Boolean

tapAction which is a PendingIntent unfortunately can't be serialized.

ComplicationType

The ComplicationType of this complication data.

TimeRange

The TimeRange within which the complication should be displayed.

Constants

TYPE_PERCENTAGE

const val TYPE_PERCENTAGE = 2: Int

The ranged value represents a percentage in the range 0..100. E.g. Battery charge.

TYPE_RATING

const val TYPE_RATING = 1: Int

The ranged value represents a rating or score for something unrelated to the user, e.g. the air quality index or the UV index.

TYPE_UNDEFINED

const val TYPE_UNDEFINED = 0: Int

The ranged value's semantic hasn't been explicitly defined, most commonly it's a percentage however.

Public companion properties

PLACEHOLDER

val PLACEHOLDERFloat

Used to signal the range should be rendered as a placeholder. It's suggested that a placeholder ranged value be drawn as a grey arc with a percentage value selected by the renderer.

Note a placeholder may only be used in the context of NoDataComplicationData.placeholder.

TYPE

val TYPEComplicationType

The ComplicationType corresponding to objects of this type.

Public functions

getNextChangeInstant

open fun getNextChangeInstant(afterInstant: Instant): Instant

Returns the next Instant after afterInstant at which any field of the complication may change. If there's no scheduled changes then Instant.MAX will be returned.

See ComplicationText.getNextChangeTime

Parameters
afterInstant: Instant

The reference Instant, after which changes will be reported.

hasPlaceholderFields

open fun hasPlaceholderFields(): Boolean

Returns true if any of the fields of this ComplicationData are placeholders. I.e. if any fields are equal to: ComplicationText.PLACEHOLDER, SmallImage.PLACEHOLDER, MonochromaticImage.PLACEHOLDER, PhotoImageComplicationData.PLACEHOLDER, or RangedValueComplicationData.PLACEHOLDER.

toString

open fun toString(): String

Public properties

colorRamp

Added in 1.2.0
val colorRampColorRamp?

Optional hint to render the value with the specified ColorRamp. When present the renderer may choose to use the ColorRamp when rendering the progress bar.

contentDescription

Added in 1.0.0
val contentDescriptionComplicationText?

The content description field for accessibility.

dynamicValue

Added in 1.2.0
val dynamicValueDynamicBuilders.DynamicFloat?

The DynamicFloat optionally set by the data source. If present the system will dynamically evaluate this and store the result in value. Watch faces can typically ignore this field.

max

Added in 1.0.0
val maxFloat

The maximum Float value for this complication.

min

Added in 1.0.0
val minFloat

The minimum Float value for this complication.

monochromaticImage

Added in 1.0.0
val monochromaticImageMonochromaticImage?

A simple MonochromaticImage image that can be tinted by the watch face. If the monochromaticImage is equal to MonochromaticImage.PLACEHOLDER the renderer must treat it as a placeholder rather than rendering normally, its suggested it should be rendered as a light grey box.

smallImage

Added in 1.2.0
val smallImageSmallImage?

A SmallImage that is expected to cover a small fraction of a watch face occupied by a single complication. If the smallImage is equal to SmallImage.PLACEHOLDER the renderer must treat it as a placeholder rather than rendering normally, its suggested it should be rendered as a light grey box.

text

Added in 1.0.0
val textComplicationText?

The body ComplicationText of the complication. 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. If the text is equal to ComplicationText.PLACEHOLDER the renderer must treat it as a placeholder rather than rendering normally, its suggested it should be rendered as a light grey box.

title

Added in 1.0.0
val titleComplicationText?

The optional title ComplicationText. The length of the title, 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. If the title is equal to ComplicationText.PLACEHOLDER the renderer must treat it as a placeholder rather than rendering normally, its suggested it should be rendered as a light grey box.

value

Added in 1.0.0
val valueFloat

The Float value of this complication which is >= min and <= max or equal to PLACEHOLDER. If it's equal to PLACEHOLDER the renderer must treat it as a placeholder rather than rendering normally, its suggested to be drawn as a grey arc with a percentage value selected by the renderer. The semantic meaning of value is described by valueType.

valueType

Added in 1.2.0
val valueTypeInt

The semantic meaning of value. The complication renderer may choose to visually differentiate between the different types, for example rendering a dot on a line/arc to indicate the value for a TYPE_RATING.