Summary: Ctors | Methods | Protected Methods | Inherited Methods

ComplicationDrawable

Kotlin |Java

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 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 ComplicationDrawable(Context) 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 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
`ComplicationDrawable()` Default constructor.
`ComplicationDrawable(Context context)` Creates a ComplicationDrawable using the given context.
`ComplicationDrawable(ComplicationDrawable drawable)`

Public methods
`void`	`draw(Canvas canvas)` Draws the complication for the last known time.
`ComplicationStyle`	`getActiveStyle()` Returns complication style for active mode.
`ComplicationStyle`	`getAmbientStyle()` Returns complication style for ambient mode.
`ComplicationData`	`getComplicationData()` Returns the `ComplicationData` to be drawn by this ComplicationDrawable.
`ComplicationRenderer`	`getComplicationRenderer()` Returns complication renderer.
`Context`	`getContext()` Returns the `Context` used to render the complication.
`long`	`getCurrentTimeMillis()` Returns the time in milliseconds since the epoch used for rendering `ComplicationData` with time dependent text.
`static ComplicationDrawable`	`getDrawable(Context context, int id)` Creates a ComplicationDrawable from a resource.
`long`	`getHighlightDuration()` Returns the highlight duration.
`CharSequence`	`getNoDataText()`
`int`	`getOpacity()` This method is deprecated. This method is no longer used in graphics optimizations
`void`	`inflate(Resources r, XmlPullParser parser, AttributeSet attrs, Resources.Theme theme)` Inflates this ComplicationDrawable from an XML resource.
`boolean`	`isBurnInProtectionOn()` Whether the complication, when rendering in ambient mode, should apply a style suitable for display on devices with burn in protection.
`boolean`	`isHighlighted()` Returns whether the complication is currently highlighted.
`boolean`	`isInAmbientMode()` Returns whether the complication is rendered in ambient mode.
`boolean`	`isLowBitAmbient()` Returns whether the complication, when rendering in ambient mode, should apply a style suitable for low bit ambient mode.
`boolean`	`isRangedValueProgressHidden()` Returns `true` if the ranged value progress is hidden, `false` otherwise.
`boolean`	`onTap(int x, int y)` Sends the tap action for the complication if tap coordinates are inside the complication bounds.
`void`	`setAlpha(int alpha)` Does nothing.
`void`	`setBurnInProtection(boolean burnInProtection)` Sets whether the complication, when rendering in ambient mode, should apply a style suitable for display on devices with burn in protection.
`void`	`setColorFilter(ColorFilter colorFilter)` Does nothing.
`void`	`setComplicationData(ComplicationData complicationData, boolean loadDrawablesAsync)` Sets the complication data to be drawn.
`void`	`setContext(Context context)` Sets the context used to render the complication.
`void`	`setCurrentTimeMillis(long currentTimeMillis)` Sets the current time in mulliseconds since the epoch.
`void`	`setHighlightDuration(long highlightDurationMillis)` Sets the duration for the complication to stay highlighted after calling the `onTap(int, int)` method.
`void`	`setHighlighted(boolean isHighlighted)` Sets whether the complication is currently highlighted.
`void`	`setInAmbientMode(boolean inAmbientMode)` Sets whether the complication should be rendered in ambient mode.
`void`	`setLowBitAmbient(boolean lowBitAmbient)` Sets whether the complication, when rendering in ambient mode, should apply a style suitable for low bit ambient mode.
`void`	`setNoDataText(CharSequence noDataText)` Sets the text to be rendered when `ComplicationData` is of type `ComplicationData.TYPE_NO_DATA`.
`void`	`setRangedValueProgressHidden(boolean rangedValueProgressHidden)` Sets if the ranged value progress should be hidden when `ComplicationData` is of type `ComplicationData.TYPE_RANGED_VALUE`.

Protected methods
`void`	`onBoundsChange(Rect bounds)`

Inherited methods

From class


        
          android.graphics.drawable.Drawable

`void`	`applyTheme(Resources.Theme arg0)`
`boolean`	`canApplyTheme()`
`void`	`clearColorFilter()`
`final Rect`	`copyBounds()`
`final void`	`copyBounds(Rect arg0)`
`static Drawable`	`createFromPath(String arg0)`
`static Drawable`	`createFromResourceStream(Resources arg0, TypedValue arg1, InputStream arg2, String arg3, BitmapFactory.Options arg4)`
`static Drawable`	`createFromResourceStream(Resources arg0, TypedValue arg1, InputStream arg2, String arg3)`
`static Drawable`	`createFromStream(InputStream arg0, String arg1)`
`static Drawable`	`createFromXml(Resources arg0, XmlPullParser arg1)`
`static Drawable`	`createFromXml(Resources arg0, XmlPullParser arg1, Resources.Theme arg2)`
`static Drawable`	`createFromXmlInner(Resources arg0, XmlPullParser arg1, AttributeSet arg2, Resources.Theme arg3)`
`static Drawable`	`createFromXmlInner(Resources arg0, XmlPullParser arg1, AttributeSet arg2)`
`abstract void`	`draw(Canvas arg0)`
`int`	`getAlpha()`
`final Rect`	`getBounds()`
`Drawable.Callback`	`getCallback()`
`int`	`getChangingConfigurations()`
`ColorFilter`	`getColorFilter()`
`Drawable.ConstantState`	`getConstantState()`
`Drawable`	`getCurrent()`
`Rect`	`getDirtyBounds()`
`void`	`getHotspotBounds(Rect arg0)`
`int`	`getIntrinsicHeight()`
`int`	`getIntrinsicWidth()`
`int`	`getLayoutDirection()`
`final int`	`getLevel()`
`int`	`getMinimumHeight()`
`int`	`getMinimumWidth()`
`abstract int`	`getOpacity()`
`Insets`	`getOpticalInsets()`
`void`	`getOutline(Outline arg0)`
`boolean`	`getPadding(Rect arg0)`
`int[]`	`getState()`
`Region`	`getTransparentRegion()`
`void`	`inflate(Resources arg0, XmlPullParser arg1, AttributeSet arg2, Resources.Theme arg3)`
`void`	`inflate(Resources arg0, XmlPullParser arg1, AttributeSet arg2)`
`void`	`invalidateSelf()`
`boolean`	`isAutoMirrored()`
`boolean`	`isFilterBitmap()`
`boolean`	`isProjected()`
`boolean`	`isStateful()`
`final boolean`	`isVisible()`
`void`	`jumpToCurrentState()`
`Drawable`	`mutate()`
`void`	`onBoundsChange(Rect arg0)`
`boolean`	`onLayoutDirectionChanged(int arg0)`
`boolean`	`onLevelChange(int arg0)`
`boolean`	`onStateChange(int[] arg0)`
`static int`	`resolveOpacity(int arg0, int arg1)`
`void`	`scheduleSelf(Runnable arg0, long arg1)`
`abstract void`	`setAlpha(int arg0)`
`void`	`setAutoMirrored(boolean arg0)`
`void`	`setBounds(int arg0, int arg1, int arg2, int arg3)`
`void`	`setBounds(Rect arg0)`
`final void`	`setCallback(Drawable.Callback arg0)`
`void`	`setChangingConfigurations(int arg0)`
`void`	`setColorFilter(int arg0, PorterDuff.Mode arg1)`
`abstract void`	`setColorFilter(ColorFilter arg0)`
`void`	`setDither(boolean arg0)`
`void`	`setFilterBitmap(boolean arg0)`
`void`	`setHotspot(float arg0, float arg1)`
`void`	`setHotspotBounds(int arg0, int arg1, int arg2, int arg3)`
`final boolean`	`setLayoutDirection(int arg0)`
`final boolean`	`setLevel(int arg0)`
`boolean`	`setState(int[] arg0)`
`void`	`setTint(int arg0)`
`void`	`setTintBlendMode(BlendMode arg0)`
`void`	`setTintList(ColorStateList arg0)`
`void`	`setTintMode(PorterDuff.Mode arg0)`
`boolean`	`setVisible(boolean arg0, boolean arg1)`
`void`	`unscheduleSelf(Runnable arg0)`

From class


        
          java.lang.Object

`Object`	`clone()`
`boolean`	`equals(Object arg0)`
`void`	`finalize()`
`final Class<?>`	`getClass()`
`int`	`hashCode()`
`final void`	`notify()`
`final void`	`notifyAll()`
`String`	`toString()`
`final void`	`wait(long arg0, int arg1)`
`final void`	`wait(long arg0)`
`final void`	`wait()`

Public constructors

ComplicationDrawable

public ComplicationDrawable ()

Default constructor.

ComplicationDrawable

public ComplicationDrawable (Context context)

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

Parameters
`context`	`Context`

ComplicationDrawable

public ComplicationDrawable (ComplicationDrawable drawable)

Parameters
`drawable`	`ComplicationDrawable`

Public methods

draw

public void draw (Canvas canvas)

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

public ComplicationStyle getActiveStyle ()

Returns complication style for active mode.

Returns
`ComplicationStyle`

getAmbientStyle

public ComplicationStyle getAmbientStyle ()

Returns complication style for ambient mode.

Returns
`ComplicationStyle`

getComplicationData

public ComplicationData getComplicationData ()

Returns the ComplicationData to be drawn by this ComplicationDrawable.

Returns
`ComplicationData`

getComplicationRenderer

public ComplicationRenderer getComplicationRenderer ()

Returns complication renderer.

Returns
`ComplicationRenderer`

getContext

public Context getContext ()

Returns the Context used to render the complication.

Returns
`Context`

getCurrentTimeMillis

public long getCurrentTimeMillis ()

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

Returns
`long`

getDrawable

public static ComplicationDrawable getDrawable (Context context, 
                int id)

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

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

getHighlightDuration

public long getHighlightDuration ()

Returns the highlight duration.

Returns
`long`

getNoDataText

public CharSequence getNoDataText ()

Returns
`CharSequence`

getOpacity

public int getOpacity ()

This method is deprecated.
This method is no longer used in graphics optimizations

Returns
`int`

inflate

public void inflate (Resources r, 
                XmlPullParser parser, 
                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
`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`	`Resources.Theme`: Ignored by ComplicationDrawable

Throws
`XmlPullParserException`
`IOException`

isBurnInProtectionOn

public boolean isBurnInProtectionOn ()

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

Returns
`boolean`

isHighlighted

public boolean isHighlighted ()

Returns whether the complication is currently highlighted.

Returns
`boolean`

isInAmbientMode

public boolean isInAmbientMode ()

Returns whether the complication is rendered in ambient mode.

Returns
`boolean`

isLowBitAmbient

public boolean isLowBitAmbient ()

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

Returns
`boolean`

isRangedValueProgressHidden

public boolean isRangedValueProgressHidden ()

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

Returns
`boolean`

onTap

public boolean onTap (int x, 
                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(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(Context, int) 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

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. `PendingIntent`) is cancelled, or the given x and y are not inside the complication bounds.

setAlpha

public void setAlpha (int alpha)

Does nothing.

Parameters
`alpha`	`int`

setBurnInProtection

public void setBurnInProtection (boolean burnInProtection)

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

Parameters
`burnInProtection`	`boolean`

setColorFilter

public void setColorFilter (ColorFilter colorFilter)

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

Parameters
`colorFilter`	`ColorFilter`

setComplicationData

public void setComplicationData (ComplicationData complicationData, 
                boolean loadDrawablesAsync)

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

Parameters
`complicationData`	`ComplicationData`: The [ComplicationData] to set
`loadDrawablesAsync`	`boolean`: If true any drawables should be loaded asynchronously, otherwise they will be loaded synchronously.

setContext

public void setContext (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(Canvas), Drawable.setBounds(Rect), or setComplicationData(ComplicationData, boolean) 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.

Parameters
`context`	`Context`

setCurrentTimeMillis

public void setCurrentTimeMillis (long currentTimeMillis)

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

public void setHighlightDuration (long highlightDurationMillis)

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

Parameters
`highlightDurationMillis`	`long`: highlight duration in milliseconds

setHighlighted

public void setHighlighted (boolean isHighlighted)

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.

Parameters
`isHighlighted`	`boolean`

setInAmbientMode

public void setInAmbientMode (boolean inAmbientMode)

Sets whether the complication should be rendered in ambient mode.

Parameters
`inAmbientMode`	`boolean`

setLowBitAmbient

public void setLowBitAmbient (boolean lowBitAmbient)

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

Parameters
`lowBitAmbient`	`boolean`

setNoDataText

public void setNoDataText (CharSequence noDataText)

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

Parameters
`noDataText`	`CharSequence`

setRangedValueProgressHidden

public void setRangedValueProgressHidden (boolean rangedValueProgressHidden)

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 void onBoundsChange (Rect bounds)

Parameters
`bounds`	`Rect`