Google is committed to advancing racial equity for Black communities. See how.

ComplicationDrawable

class ComplicationDrawable : Drawable
kotlin.Any
   ↳ android.graphics.drawable.Drawable
   ↳ androidx.wear.watchface.complications.rendering.ComplicationDrawable

A styleable drawable object that draws complications. 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 constructor. Afterwards, styling attributes you want to modify can be set via set methods.

public void onCreate(SurfaceHolder holder) {
    ...
    ComplicationDrawable complicationDrawable = new ComplicationDrawable(WatchFaceService.this);
    complicationDrawable.setBackgroundColorActive(backgroundColor);
    complicationDrawable.setTextColorActive(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.complications.rendering.ComplicationDrawable
    xmlns:app="http://schemas.android.com/apk/res-auto"
    app:textColor="#FFFF0000"
    app:titleColor="#FFFFFFFF">
    <ambient
      app:textColor="#FFFFFFFF" />
  </android.support.wearable.complications.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.complications.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(Context, int) 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.complications.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.complications.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 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.

<init>(@NonNull context: Context)

Creates a ComplicationDrawable using the given context.

<init>(@NonNull drawable: ComplicationDrawable)

Public methods
Unit
draw(@NonNull canvas: Canvas)

Draws the complication for the last known time.

ComplicationStyle

Returns complication style for active mode.

ComplicationStyle

Returns complication style for ambient mode.

ComplicationData?

Returns the ComplicationData to be drawn by this ComplicationDrawable.

ComplicationRenderer?

Returns complication renderer.

Context?

Returns the Context used to render the complication.

Long

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

static ComplicationDrawable?
getDrawable(@NonNull context: Context, id: Int)

Creates a ComplicationDrawable from a resource.

Long

Returns the highlight duration.

CharSequence?

Int

Unit
inflate(@NonNull r: Resources, @NonNull parser: XmlPullParser, @NonNull attrs: AttributeSet, @Nullable theme: Theme?)

Inflates this ComplicationDrawable from an XML resource.

Boolean

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

Boolean

Returns whether the complication is currently highlighted.

Boolean

Returns whether the complication is rendered in ambient mode.

Boolean

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

Boolean

Returns true if the ranged value progress is hidden, false otherwise.

Boolean
onTap(x: Int, y: Int)

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

Unit
setAlpha(alpha: Int)

Does nothing.

Unit
setBurnInProtection(burnInProtection: Boolean)

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

Unit
setColorFilter(@Nullable colorFilter: ColorFilter?)

Does nothing.

Unit
setComplicationData(@Nullable complicationData: ComplicationData?)

Sets the complication data to be drawn.

Unit
setContext(@NonNull context: Context)

Sets the context used to render the complication.

Unit
setCurrentTimeMillis(currentTimeMillis: Long)

Sets the current time in mulliseconds since the epoch.

Unit
setHighlightDuration(highlightDurationMillis: Long)

Sets the duration for the complication to stay highlighted after calling the method.

Unit
setHighlighted(isHighlighted: Boolean)

Sets whether the complication is currently highlighted.

Unit
setInAmbientMode(inAmbientMode: Boolean)

Sets whether the complication should be rendered in ambient mode.

Unit
setLowBitAmbient(lowBitAmbient: Boolean)

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

Unit
setNoDataText(@Nullable noDataText: CharSequence?)

Sets the text to be rendered when ComplicationData is of type .

Unit
setRangedValueProgressHidden(rangedValueProgressHidden: Boolean)

Sets if the ranged value progress should be hidden when ComplicationData is of type ComplicationData#TYPE_RANGED_VALUE.

Protected methods
Unit
onBoundsChange(@NonNull bounds: Rect)

Public constructors

<init>

ComplicationDrawable()

Default constructor.

<init>

ComplicationDrawable(@NonNull context: Context)

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

<init>

ComplicationDrawable(@NonNull drawable: ComplicationDrawable)

Public methods

draw

fun draw(@NonNull canvas: Canvas): Unit

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

Parameters
canvas Canvas: Canvas for the complication to be drawn onto

getActiveStyle

@NonNull fun getActiveStyle(): ComplicationStyle

Returns complication style for active mode.

getAmbientStyle

@NonNull fun getAmbientStyle(): ComplicationStyle

Returns complication style for ambient mode.

getComplicationData

@Nullable fun getComplicationData(): ComplicationData?

Returns the ComplicationData to be drawn by this ComplicationDrawable.

getComplicationRenderer

@Nullable fun getComplicationRenderer(): ComplicationRenderer?

Returns complication renderer.

getContext

@Nullable fun getContext(): Context?

Returns the Context used to render the complication.

getCurrentTimeMillis

fun getCurrentTimeMillis(): Long

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

getDrawable

@Nullable static fun getDrawable(
    @NonNull context: Context,
    id: Int
): ComplicationDrawable?

Creates a ComplicationDrawable from a resource.

Parameters
context Context: The Context to load the resource from
id Int: The id of the resource to load
Return
ComplicationDrawable? The ComplicationDrawable loaded from the specified resource id or null if it doesn't exist.

getHighlightDuration

fun getHighlightDuration(): Long

Returns the highlight duration.

getNoDataText

@Nullable fun getNoDataText(): CharSequence?

getOpacity

fun getOpacity(): Int

Deprecated: This method is no longer used in graphics optimizations

inflate

fun inflate(
    @NonNull r: Resources,
    @NonNull parser: XmlPullParser,
    @NonNull attrs: AttributeSet,
    @Nullable theme: Theme?
): Unit

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
r Resources: Resources used to resolve attribute values
parser XmlPullParser: XML parser from which to inflate this ComplicationDrawable
attrs AttributeSet: Base set of attribute values
theme Theme?: Ignored by ComplicationDrawable

isBurnInProtectionOn

fun isBurnInProtectionOn(): Boolean

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

isHighlighted

fun isHighlighted(): Boolean

Returns whether the complication is currently highlighted.

isInAmbientMode

fun isInAmbientMode(): Boolean

Returns whether the complication is rendered in ambient mode.

isLowBitAmbient

fun isLowBitAmbient(): Boolean

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

isRangedValueProgressHidden

fun isRangedValueProgressHidden(): Boolean

Returns true if the ranged value progress is hidden, false otherwise.

onTap

fun onTap(
    x: Int,
    y: Int
): Boolean

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(long) method.

If ComplicationData has the type ComplicationData#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
x Int: X coordinate of the tap relative to screen origin
y Int: Y coordinate of the tap relative to screen origin
Return
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. ) is cancelled, or the given x and y are not inside the complication bounds.

setAlpha

fun setAlpha(alpha: Int): Unit

Does nothing.

setBurnInProtection

fun setBurnInProtection(burnInProtection: Boolean): Unit

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

setColorFilter

fun setColorFilter(@Nullable colorFilter: ColorFilter?): Unit

Does nothing. Use ComplicationStyle#setImageColorFilter(ColorFilter) instead to apply color filter to small and large images.

setComplicationData

fun setComplicationData(@Nullable complicationData: ComplicationData?): Unit

Sets the complication data to be drawn. If complicationData is null, nothing will be drawn when draw(Canvas) is called.

setContext

fun setContext(@NonNull context: Context): Unit

Sets the context used to render the complication. If a context is not set, ComplicationDrawable will throw an IllegalStateException if one of draw(Canvas), setBounds(Rect), or 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(int, int) method, in case current watch face doesn't have the permission to receive complication data.

If this ComplicationDrawable is retrieved using Resources#getDrawable(int, Theme), 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() is used to construct a ComplicationDrawable, this method should be called right after.

setCurrentTimeMillis

fun setCurrentTimeMillis(currentTimeMillis: Long): Unit

Sets the current time in mulliseconds since the epoch. This will be used to render ComplicationData with time dependent text.

Parameters
currentTimeMillis Long: time in milliseconds since the epoch

setHighlightDuration

fun setHighlightDuration(highlightDurationMillis: Long): Unit

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

Parameters
highlightDurationMillis Long: highlight duration in milliseconds

setHighlighted

fun setHighlighted(isHighlighted: Boolean): Unit

Sets 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

fun setInAmbientMode(inAmbientMode: Boolean): Unit

Sets whether the complication should be rendered in ambient mode.

setLowBitAmbient

fun setLowBitAmbient(lowBitAmbient: Boolean): Unit

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

setNoDataText

fun setNoDataText(@Nullable noDataText: CharSequence?): Unit

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

setRangedValueProgressHidden

fun setRangedValueProgressHidden(rangedValueProgressHidden: Boolean): Unit

Sets if the ranged value progress should be hidden when ComplicationData is of type ComplicationData#TYPE_RANGED_VALUE.

Parameters
rangedValueProgressHidden Boolean: true if progress should be hidden, false otherwise

Protected methods

onBoundsChange

protected fun onBoundsChange(@NonNull bounds: Rect): Unit