GoalProgressComplicationData
@RequiresApi(value = 33)
public final class GoalProgressComplicationData extends ComplicationData
| java.lang.Object | ||
| ↳ | androidx.wear.watchface.complications.data.ComplicationData | |
| ↳ | androidx.wear.watchface.complications.data.GoalProgressComplicationData | |
Type used for complications which shows the user's progress towards a goal, E.g. you've done 2400 out of your daily target of 10000 steps. Unlike RangedValueComplicationData is allowed to be larger than targetValue (e.g. you've done 12000 steps) and renderers may chose to acknowledge this in a special way (e.g. by colorizing part of the progress bar in a different color to indicate progress past the goal). The value may be accompanied by an icon and/or short text and title.
The targetValue field is required for this type, as well as one of value or dynamicValue. The progress 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.
If you want to represent a score for something that's not based on the user (e.g. air quality index) then you should instead use a RangedValueComplicationData and pass RangedValueComplicationData.TYPE_RATING into RangedValueComplicationData.Builder.setValueType.
A data source that wants to serve a SmallImageComplicationData 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="GOAL_PROGRESS"/>
Summary
Nested types |
|---|
@RequiresApi(value = 33)Builder for |
Public fields |
|
|---|---|
static final float |
Used to signal the range should be rendered as a placeholder. |
static final @NonNull ComplicationType |
The |
Public methods |
|
|---|---|
final ColorRamp |
Optional hint to render the progress bar representing |
final ComplicationText |
The content description field for accessibility. |
final DynamicBuilders.DynamicFloat |
@RequiresApi(value = 33)The |
final MonochromaticImage |
A simple |
@NonNull Instant |
getNextChangeInstant(@NonNull Instant afterInstant)Returns the next |
final SmallImage |
A |
final float |
The target |
final ComplicationText |
getText()The body |
final ComplicationText |
getTitle()The optional title |
final float |
getValue()The |
boolean |
Returns |
@NonNull String |
toString() |
Inherited methods |
||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Public fields
PLACEHOLDER
public static final float PLACEHOLDER
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
public static final @NonNull ComplicationType TYPE
The ComplicationType corresponding to objects of this type.
Public methods
getColorRamp
public final ColorRamp getColorRamp()
Optional hint to render the progress bar representing value with the specified ColorRamp.
getContentDescription
public final ComplicationText getContentDescription()
The content description field for accessibility.
getDynamicValue
@RequiresApi(value = 33)
public final DynamicBuilders.DynamicFloat getDynamicValue()
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.
getMonochromaticImage
public final MonochromaticImage getMonochromaticImage()
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.
getNextChangeInstant
public @NonNull Instant getNextChangeInstant(@NonNull Instant afterInstant)
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.
getSmallImage
public final SmallImage getSmallImage()
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.
getTargetValue
public final float getTargetValue()
The target Float value for this complication.
getText
public final ComplicationText getText()
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.
getTitle
public final ComplicationText getTitle()
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.
getValue
public final float getValue()
The Float value of this complication which is >= 0f, this value may be larger than targetValue. 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.
hasPlaceholderFields
public boolean hasPlaceholderFields()
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.