public final class ComplicationDrawable extends Drawable

java.lang.Object
   ↳ android.graphics.drawable.Drawable
     ↳ androidx.wear.watchface.complications.rendering.ComplicationDrawable

A styleable drawable object that draws complicationSlots. You can create a ComplicationDrawable from XML inflation or by using one of the constructor methods.

Constructing a ComplicationDrawable

To construct a ComplicationDrawable programmatically, use the ComplicationDrawable constructor. Afterwards, styling attributes you want to modify can be set via set methods.

val complicationDrawable = ComplicationDrawable(context)
complicationDrawable.activeStyle.backgroundColor = backgroundColor
complicationDrawable.activeStyle.textColor = textColor

Constructing a ComplicationDrawable from XML

Constructing a ComplicationDrawable from an XML file makes it easier to modify multiple styling attributes at once without calling any set methods. You may also use different XML files to switch between different styles your watch face supports.

To construct a ComplicationDrawable from a drawable XML file, you may create an XML file in your project's res/drawable folder. A ComplicationDrawable with red text and white title in active mode, and white text and white title in ambient mode would look like this:

<?xml version="1.0" encoding="utf-8"?>
<android.support.wearable.complication.rendering.ComplicationDrawable
xmlns:app="http://schemas.android.com/apk/res-auto"
app:textColor="#FFFF0000"
app:titleColor="#FFFFFFFF">
<ambient
app:textColor="#FFFFFFFF" />
</android.support.wearable.complication.rendering.ComplicationDrawable>

A top-level drawable tag with the class attribute may also be used to construct a ComplicationDrawable from an XML file:

<?xml version="1.0" encoding="utf-8"?>
<drawable
class="android.support.wearable.complication.rendering.ComplicationDrawable"
xmlns:app="http://schemas.android.com/apk/res-auto"
app:textColor="#FFFF0000"
app:titleColor="#FFFFFFFF">
<ambient
app:textColor="#FFFFFFFF" />
</drawable>

To inflate a ComplicationDrawable from XML file, use the .getDrawable method. ComplicationDrawable needs access to the current context in order to style and draw the complication.

public void onCreate(SurfaceHolder holder) {
...
ComplicationDrawable complicationDrawable = (ComplicationDrawable)
getDrawable(R.drawable.complication);
complicationDrawable.setContext(WatchFaceService.this);
...
}

Syntax:

<?xml version="1.0" encoding="utf-8"?>
<android.support.wearable.complication.rendering.ComplicationDrawable
xmlns:app="http://schemas.android.com/apk/res-auto"
app:backgroundColor="color"
app:backgroundDrawable="drawable"
app:borderColor="color"
app:borderDashGap="dimension"
app:borderDashWidth="dimension"
app:borderRadius="dimension"
app:borderStyle="none|solid|dashed"
app:borderWidth="dimension"
app:highlightColor="color"
app:iconColor="color"
app:rangedValuePrimaryColor="color"
app:rangedValueProgressHidden="boolean"
app:rangedValueRingWidth="dimension"
app:rangedValueSecondaryColor="color"
app:textColor="color"
app:textSize="dimension"
app:textTypeface="string"
app:titleColor="color"
app:titleSize="dimension"
app:titleTypeface="string">
<ambient
app:backgroundColor="color"
app:backgroundDrawable="drawable"
app:borderColor="color"
app:borderDashGap="dimension"
app:borderDashWidth="dimension"
app:borderRadius="dimension"
app:borderStyle="none|solid|dashed"
app:borderWidth="dimension"
app:highlightColor="color"
app:iconColor="color"
app:rangedValuePrimaryColor="color"
app:rangedValueRingWidth="dimension"
app:rangedValueSecondaryColor="color"
app:textColor="color"
app:textSize="dimension"
app:textTypeface="string"
app:titleColor="color"
app:titleSize="dimension"
app:titleTypeface="string" />
</android.support.wearable.complication.rendering.ComplicationDrawable>

Attributes of the top-level tag apply to both active and ambient modes while attributes of the inner ambient tag only apply to ambient mode. As an exception, top-level only rangedValueProgressHidden attribute applies to both modes, and cannot be overridden in ambient mode. To hide ranged value in only one of the active or ambient modes, you may consider setting rangedValuePrimaryColor and rangedValueSecondaryColor to android.graphics.Color.TRANSPARENT instead.

Drawing a ComplicationDrawable

Depending on the size and shape of the bounds, the layout of the complication may change. For instance, a short text complication with an icon that is drawn on square bounds would draw the icon above the short text, but a short text complication with an icon that is drawn on wide rectangular bounds might draw the icon to the left of the short text instead.

Summary

Public constructors

Default constructor.

Creates a ComplicationDrawable using the given context.

Public methods
void
draw(@NonNull Canvas canvas)

Draws the complication for the last known time.
final @NonNull ComplicationStyle

Returns complication style for active mode.
final @NonNull ComplicationStyle

Returns complication style for ambient mode.
final @NonNull ComplicationData

Returns the ComplicationData to be drawn by this ComplicationDrawable.
final Context

Returns the Context used to render the complication.
final @NonNull Instant

The time in milliseconds since the epoch used for rendering ComplicationData with time dependent text.
static final ComplicationDrawable
getDrawable(@NonNull Context context, int id)

Creates a ComplicationDrawable from a resource.
final long

The duration for the complication to stay highlighted after calling the onTap method.
final CharSequence

The text to be rendered when ComplicationData is of type NO_DATA.
int

This method is deprecated. This method is no longer used in graphics optimizations
void
inflate(
    @NonNull Resources r,
    @NonNull XmlPullParser parser,
    @NonNull AttributeSet attrs,
    Resources.Theme theme
)

Inflates this ComplicationDrawable from an XML resource.
final boolean

Whether the complication, when rendering in ambient mode, should apply a style suitable for display on devices with burn in protection.
final boolean

Whether the complication is currently highlighted.
final boolean

Whether the complication is rendered in ambient mode.
final boolean

Whether the complication, when rendering in ambient mode, should apply a style suitable for low bit ambient mode.
final boolean

If the ranged value progress should be hidden when ComplicationData is of type RANGED_VALUE.
final boolean
onTap(@Px int x, @Px int y)

Sends the tap action for the complication if tap coordinates are inside the complication bounds.
void
setAlpha(@IntRange(from = 0, to = 255) int alpha)

This function is not supported in ComplicationDrawable.
final void
setBurnInProtectionOn(boolean isBurnInProtectionOn)

Whether the complication, when rendering in ambient mode, should apply a style suitable for display on devices with burn in protection.
void

This function is not supported in ComplicationDrawable.
final void
setComplicationData(
    @NonNull ComplicationData complicationData,
    boolean loadDrawablesAsync
)

Sets the complication data to be drawn.
final void

Sets the Context used to render the complication.
final void

The time in milliseconds since the epoch used for rendering ComplicationData with time dependent text.
final void
setHighlightDuration(long highlightDuration)

The duration for the complication to stay highlighted after calling the onTap method.
final void
setHighlighted(boolean isHighlighted)

Whether the complication is currently highlighted.
final void
setInAmbientMode(boolean isInAmbientMode)

Whether the complication is rendered in ambient mode.
final void
setLowBitAmbient(boolean isLowBitAmbient)

Whether the complication, when rendering in ambient mode, should apply a style suitable for low bit ambient mode.
final void

The text to be rendered when ComplicationData is of type NO_DATA.
final void
setRangedValueProgressHidden(boolean isRangedValueProgressHidden)

If the ranged value progress should be hidden when ComplicationData is of type RANGED_VALUE.

Protected methods
void

Inherited methods
From android.graphics.drawable.Drawable
void
boolean
void
final @NonNull Rect
final void
int
final @NonNull Rect
@Nullable Drawable.Callback
int
@Nullable ColorFilter
@Nullable Drawable.ConstantState
@NonNull Drawable
@NonNull Rect
void
int
int
int
final int
int
int
@NonNull Insets
void
boolean
@NonNull int[]
@Nullable Region
boolean
void
inflate(
    @NonNull Resources p0,
    @NonNull XmlPullParser p1,
    @NonNull AttributeSet p2
)
void
boolean
boolean
boolean
boolean
final boolean
void
@NonNull Drawable
boolean
boolean
onLevelChange(int p0)
boolean
void
scheduleSelf(@NonNull Runnable p0, long p1)
void
setAutoMirrored(boolean p0)
void
void
setBounds(int p0, int p1, int p2, int p3)
final void
void
void

This method is deprecated. Deprecated in Java
void
setDither(boolean p0)

This method is deprecated. Deprecated in Java
void
setFilterBitmap(boolean p0)
void
setHotspot(float p0, float p1)
void
setHotspotBounds(int p0, int p1, int p2, int p3)
final boolean
final boolean
setLevel(int p0)
boolean
setState(@NonNull int[] p0)
void
setTint(int p0)
void
void
void
boolean
setVisible(boolean p0, boolean p1)
void

Public constructors

ComplicationDrawable

Added in 1.0.0
public ComplicationDrawable()

Default constructor.

ComplicationDrawable

Added in 1.0.0
public ComplicationDrawable(@NonNull Context context)

Creates a ComplicationDrawable using the given context. If this constructor is used, calling setContext may not be necessary.

Parameters
@NonNull Context context

The Context used to render the complication.

ComplicationDrawable

Added in 1.0.0
public ComplicationDrawable(@NonNull ComplicationDrawable drawable)

Public methods

draw

Added in 1.0.0
public void draw(@NonNull Canvas canvas)

Draws the complication for the last known time. Last known time is derived from ComplicationDrawable#setCurrentTimeMillis(long)}.

Parameters
@NonNull Canvas canvas

Canvas for the complication to be drawn onto

getActiveStyle

Added in 1.0.0
public final @NonNull ComplicationStyle getActiveStyle()

Returns complication style for active mode.

getAmbientStyle

Added in 1.0.0
public final @NonNull ComplicationStyle getAmbientStyle()

Returns complication style for ambient mode.

getComplicationData

Added in 1.0.0
public final @NonNull ComplicationData getComplicationData()

Returns the ComplicationData to be drawn by this ComplicationDrawable. This defaults to NoDataComplicationData.

getContext

Added in 1.0.0
public final Context getContext()

Returns the Context used to render the complication.

getCurrentTime

Added in 1.0.0
public final @NonNull Instant getCurrentTime()

The time in milliseconds since the epoch used for rendering ComplicationData with time dependent text.

getDrawable

Added in 1.0.0
public static final ComplicationDrawable getDrawable(@NonNull Context context, int id)

Creates a ComplicationDrawable from a resource.

Parameters
@NonNull Context context

The Context to load the resource from
int id

The id of the resource to load
Returns
ComplicationDrawable

The ComplicationDrawable loaded from the specified resource id or null if it doesn't exist.

getHighlightDuration

Added in 1.0.0
public final long getHighlightDuration()

The duration for the complication to stay highlighted after calling the onTap method. Default value is 300 milliseconds. Setting highlight duration to 0 disables highlighting.

getNoDataText

Added in 1.0.0
public final CharSequence getNoDataText()

The text to be rendered when ComplicationData is of type NO_DATA. If noDataText is null, an empty text will be rendered.

getOpacity

Added in 1.0.0
Deprecated in 1.0.0
public int getOpacity()

inflate

public void inflate(
    @NonNull Resources r,
    @NonNull XmlPullParser parser,
    @NonNull AttributeSet attrs,
    Resources.Theme theme
)

Inflates this ComplicationDrawable from an XML resource. This can't be called more than once for each ComplicationDrawable. Note that framework may have called this once to create the ComplicationDrawable instance from an XML resource.

Parameters
@NonNull Resources r

Resources used to resolve attribute values
@NonNull XmlPullParser parser

XML parser from which to inflate this ComplicationDrawable
@NonNull AttributeSet attrs

Base set of attribute values
Resources.Theme theme

Ignored by ComplicationDrawable

isBurnInProtectionOn

Added in 1.0.0
public final boolean isBurnInProtectionOn()

Whether the complication, when rendering in ambient mode, should apply a style suitable for display on devices with burn in protection.

isHighlighted

Added in 1.0.0
public final boolean isHighlighted()

Whether the complication is currently highlighted. This may be called by a watch face when a complication is tapped.

If watch face is in ambient mode, highlight will not be visible even if this is set to true, because it may cause burn-in or power inefficiency.

isInAmbientMode

Added in 1.0.0
public final boolean isInAmbientMode()

Whether the complication is rendered in ambient mode.

isLowBitAmbient

Added in 1.0.0
public final boolean isLowBitAmbient()

Whether the complication, when rendering in ambient mode, should apply a style suitable for low bit ambient mode.

isRangedValueProgressHidden

Added in 1.0.0
public final boolean isRangedValueProgressHidden()

If the ranged value progress should be hidden when ComplicationData is of type RANGED_VALUE.

ref androidx.wear.watchface.complicationSlots.rendering.R .styleable#ComplicationDrawable_rangedValueProgressHidden

onTap

Added in 1.0.0
public final boolean onTap(@Px int x, @Px int y)

Sends the tap action for the complication if tap coordinates are inside the complication bounds.

This method will also highlight the complication. The highlight duration is 300 milliseconds by default but can be modified using the .setHighlightDuration method.

If ComplicationData has the type NO_PERMISSION, this method will launch an intent to request complication permission for the watch face. This will only work if the context set by getDrawable or the constructor is an instance of WatchFaceService.

Parameters
@Px int x

X coordinate of the tap relative to screen origin
@Px int y

Y coordinate of the tap relative to screen origin
Returns
boolean

true if the action was successful, false if complication data is not set, the complication has no tap action, the tap action (i.e. android.app.PendingIntent) is cancelled, or the given x and y are not inside the complication bounds.

setAlpha

Added in 1.0.0
public void setAlpha(@IntRange(from = 0, to = 255) int alpha)

This function is not supported in ComplicationDrawable.

Throws
kotlin.UnsupportedOperationException

when called.

setBurnInProtectionOn

Added in 1.0.0
public final void setBurnInProtectionOn(boolean isBurnInProtectionOn)

Whether the complication, when rendering in ambient mode, should apply a style suitable for display on devices with burn in protection.

setColorFilter

Added in 1.0.0
public void setColorFilter(ColorFilter colorFilter)

This function is not supported in ComplicationDrawable. Use ComplicationStyle.imageColorFilter instead to apply color filter to small and large images.

Throws
kotlin.UnsupportedOperationException

when called.

setComplicationData

Added in 1.0.0
public final void setComplicationData(
    @NonNull ComplicationData complicationData,
    boolean loadDrawablesAsync
)

Sets the complication data to be drawn.

Parameters
@NonNull ComplicationData complicationData

The ComplicationData to set
boolean loadDrawablesAsync

If true any drawables should be loaded asynchronously, otherwise they will be loaded synchronously.

setContext

Added in 1.0.0
public final void setContext(@NonNull Context context)

Sets the Context used to render the complication. If a context is not set, ComplicationDrawable will throw an IllegalStateException if one of draw, setBounds, or setComplicationData is called.

While this can be called from any context, ideally, a androidx.wear.watchface.WatchFaceService object should be passed here to allow creating permission dialogs by the onTap method, in case current watch face doesn't have the permission to receive complication data.

If this ComplicationDrawable is retrieved using Resources.getDrawable, this method must be called before calling any of the methods mentioned above.

If this ComplicationDrawable is not inflated from an XML file, this method will reset the style to match the default values, so if ComplicationDrawable(drawable: ComplicationDrawable) is used to construct a ComplicationDrawable, this method should be called right after.

Parameters
@NonNull Context context

The Context used to render the complication.

setCurrentTime

Added in 1.0.0
public final void setCurrentTime(@NonNull Instant currentTime)

The time in milliseconds since the epoch used for rendering ComplicationData with time dependent text.

setHighlightDuration

Added in 1.0.0
public final void setHighlightDuration(long highlightDuration)

The duration for the complication to stay highlighted after calling the onTap method. Default value is 300 milliseconds. Setting highlight duration to 0 disables highlighting.

setHighlighted

Added in 1.0.0
public final void setHighlighted(boolean isHighlighted)

Whether the complication is currently highlighted. This may be called by a watch face when a complication is tapped.

If watch face is in ambient mode, highlight will not be visible even if this is set to true, because it may cause burn-in or power inefficiency.

setInAmbientMode

Added in 1.0.0
public final void setInAmbientMode(boolean isInAmbientMode)

Whether the complication is rendered in ambient mode.

setLowBitAmbient

Added in 1.0.0
public final void setLowBitAmbient(boolean isLowBitAmbient)

Whether the complication, when rendering in ambient mode, should apply a style suitable for low bit ambient mode.

setNoDataText

Added in 1.0.0
public final void setNoDataText(CharSequence noDataText)

The text to be rendered when ComplicationData is of type NO_DATA. If noDataText is null, an empty text will be rendered.

setRangedValueProgressHidden

Added in 1.0.0
public final void setRangedValueProgressHidden(boolean isRangedValueProgressHidden)

If the ranged value progress should be hidden when ComplicationData is of type RANGED_VALUE.

ref androidx.wear.watchface.complicationSlots.rendering.R .styleable#ComplicationDrawable_rangedValueProgressHidden

Protected methods

onBoundsChange

protected void onBoundsChange(@NonNull Rect bounds)