class ComplicationDrawable : Drawable


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 companion functions

ComplicationDrawable?
getDrawable(context: Context, id: Int)

Creates a ComplicationDrawable from a resource.

Public constructors

Default constructor.

Creates a ComplicationDrawable using the given context.

Public functions

open Unit
draw(canvas: Canvas)

Draws the complication for the last known time.

open Int

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

open Unit
inflate(
    r: Resources,
    parser: XmlPullParser,
    attrs: AttributeSet,
    theme: Resources.Theme?
)

Inflates this ComplicationDrawable from an XML resource.

Boolean
onTap(x: @Px Int, y: @Px Int)

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

open Unit
setAlpha(alpha: @IntRange(from = 0, to = 255) Int)

This function is not supported in ComplicationDrawable.

open Unit
setColorFilter(colorFilter: ColorFilter?)

This function is not supported in ComplicationDrawable.

Unit
setComplicationData(
    complicationData: ComplicationData,
    loadDrawablesAsync: Boolean
)

Sets the complication data to be drawn.

Unit
setContext(context: Context)

Sets the Context used to render the complication.

Protected functions

open Unit

Public properties

ComplicationStyle

Returns complication style for active mode.

ComplicationStyle

Returns complication style for ambient mode.

ComplicationData

Returns the ComplicationData to be drawn by this ComplicationDrawable.

Context?

Returns the Context used to render the complication.

Instant

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

Long

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

Boolean

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

Boolean

Whether the complication is currently highlighted.

Boolean

Whether the complication is rendered in ambient mode.

Boolean

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

Boolean

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

CharSequence?

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

Inherited functions

From android.graphics.drawable.Drawable
open Unit
open Boolean
open Unit
Rect
Unit
open Int
Rect
open Drawable.Callback?
open Int
open ColorFilter?
open Drawable.ConstantState?
open Drawable
open Rect
open Unit
open Int
open Int
open Int
Int
open Int
open Int
open Insets
open Unit
open Boolean
open IntArray
open Region?
open Boolean
open Unit
open Unit
open Boolean
open Boolean
open Boolean
open Boolean
Boolean
open Unit
open Drawable
open Boolean
open Boolean
open Boolean
open Unit
open Unit
open Unit
open Unit
setBounds(p0: Int, p1: Int, p2: Int, p3: Int)
Unit
open Unit
open Unit

This function is deprecated. Deprecated in Java

open Unit

This function is deprecated. Deprecated in Java

open Unit
open Unit
setHotspot(p0: Float, p1: Float)
open Unit
setHotspotBounds(p0: Int, p1: Int, p2: Int, p3: Int)
Boolean
Boolean
open Boolean
open Unit
setTint(p0: Int)
open Unit
open Unit
open Unit
open Boolean
open Unit

Public companion functions

getDrawable

Added in 1.0.0
fun getDrawable(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

Returns
ComplicationDrawable?

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

Public constructors

ComplicationDrawable

Added in 1.0.0
ComplicationDrawable()

Default constructor.

ComplicationDrawable

Added in 1.0.0
ComplicationDrawable(context: Context)

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

Parameters
context: Context

The Context used to render the complication.

ComplicationDrawable

Added in 1.0.0
ComplicationDrawable(drawable: ComplicationDrawable)

Public functions

draw

Added in 1.0.0
open fun draw(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

getOpacity

Added in 1.0.0
Deprecated in 1.0.0
open fun getOpacity(): Int

inflate

open fun inflate(
    r: Resources,
    parser: XmlPullParser,
    attrs: AttributeSet,
    theme: Resources.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: Resources.Theme?

Ignored by ComplicationDrawable

onTap

Added in 1.0.0
fun onTap(x: @Px Int, y: @Px 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 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
x: @Px Int

X coordinate of the tap relative to screen origin

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

setAlpha

Added in 1.0.0
open fun setAlpha(alpha: @IntRange(from = 0, to = 255) Int): Unit

This function is not supported in ComplicationDrawable.

setColorFilter

Added in 1.0.0
open fun setColorFilter(colorFilter: ColorFilter?): Unit

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

setComplicationData

Added in 1.0.0
fun setComplicationData(
    complicationData: ComplicationData,
    loadDrawablesAsync: Boolean
): Unit

Sets the complication data to be drawn.

Parameters
complicationData: ComplicationData

The ComplicationData to set

loadDrawablesAsync: Boolean

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

setContext

Added in 1.0.0
fun setContext(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, 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
context: Context

The Context used to render the complication.

Protected functions

onBoundsChange

protected open fun onBoundsChange(bounds: Rect): Unit

Public properties

activeStyle

Added in 1.0.0
val activeStyleComplicationStyle

Returns complication style for active mode.

ambientStyle

Added in 1.0.0
val ambientStyleComplicationStyle

Returns complication style for ambient mode.

complicationData

Added in 1.0.0
val complicationDataComplicationData

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

context

Added in 1.0.0
val contextContext?

Returns the Context used to render the complication.

currentTime

Added in 1.0.0
var currentTimeInstant

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

highlightDuration

Added in 1.0.0
var highlightDurationLong

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.

isBurnInProtectionOn

Added in 1.0.0
var isBurnInProtectionOnBoolean

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
var isHighlightedBoolean

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
var isInAmbientModeBoolean

Whether the complication is rendered in ambient mode.

isLowBitAmbient

Added in 1.0.0
var isLowBitAmbientBoolean

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

isRangedValueProgressHidden

Added in 1.0.0
var isRangedValueProgressHiddenBoolean

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

noDataText

Added in 1.0.0
var noDataTextCharSequence?

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