ComplicationDrawable
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 |
ComplicationRenderer
|
getComplicationRenderer()
Returns complication renderer. |
Context
|
getContext()
Returns the |
long
|
getCurrentTimeMillis()
Returns the time in milliseconds since the epoch used for rendering |
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 |
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 |
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 |
void
|
setRangedValueProgressHidden(boolean rangedValueProgressHidden)
Sets if the ranged value progress should be hidden when |
Protected methods | |
---|---|
void
|
onBoundsChange(Rect bounds)
|
Inherited methods | |
---|---|
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 |