Skip to content

Most visited

Recently visited

navigation

WatchFaceService.Engine

public abstract class WatchFaceService.Engine
extends WallpaperService.Engine

java.lang.Object
   ↳ android.service.wallpaper.WallpaperService.Engine
     ↳ android.support.wearable.watchface.WatchFaceService.Engine
Known Direct Subclasses


The actual implementation of a watch face. You must implement onCreateEngine() to return your concrete Engine implementation.

Summary

Public constructors

WatchFaceService.Engine()

Public methods

final int getInterruptionFilter()

Returns interruption filter selected by the user.

final int getNotificationCount()

Returns the total number of notification cards in the stream.

final Rect getPeekCardPosition()

This method is deprecated. Wear 2.0 doesn't have peeking cards

final int getUnreadCount()

Returns the number of unread notification cards in the stream.

final boolean isInAmbientMode()

Returns whether the watch face is in ambient mode.

void onAmbientModeChanged(boolean inAmbientMode)

Called when the device enters or exits ambient mode.

Bundle onCommand(String action, int x, int y, int z, Bundle extras, boolean resultRequested)
void onComplicationDataUpdate(int watchFaceComplicationId, ComplicationData data)

Called when new complication data is received.

void onCreate(SurfaceHolder holder)
void onDestroy()
void onInterruptionFilterChanged(int interruptionFilter)

Called when the user changes interruption filter.

void onNotificationCountChanged(int count)

Called when the total number of notification cards in the stream has changed.

void onPeekCardPositionUpdate(Rect rect)

This method is deprecated. Wear 2.0 doesn't have peeking cards

void onPropertiesChanged(Bundle properties)

Called when the properties of the device are determined.

void onTapCommand(int tapType, int x, int y, long eventTime)

Called when a tap or touch related event occurs.

void onTimeTick()

Called periodically to update the time shown by the watch face.

void onTouchEvent(MotionEvent event)

This method is deprecated. Do not use this to receive touch events on a watch face. Instead, use setAcceptsTapEvents(boolean) and then override onTapCommand(int, int, int, long). This method will cease to function in a future release.

void onUnreadCountChanged(int count)

Called when the number of unread notification cards in the stream has changed.

void onVisibilityChanged(boolean visible)

Called to inform you of the watch face becoming visible or hidden.

void setActiveComplications(int... watchFaceComplicationIds)

Sets the complications which are active in the watchface.

void setDefaultComplicationProvider(int watchFaceComplicationId, ComponentName provider, int type)

Sets a custom provider as the default provider for the specified watch face complication id.

void setDefaultSystemComplicationProvider(int watchFaceComplicationId, int systemProvider, int type)

Sets a system provider as the default provider for the specified watch face complication id.

void setTouchEventsEnabled(boolean enabled)

This method is deprecated. Do not use this to receive touch events on a watch face. Instead, use setAcceptsTapEvents(boolean) and then override onTapCommand(int, int, int, long). This method will cease to function in a future release.

void setWatchFaceStyle(WatchFaceStyle watchFaceStyle)

Sets the watch face style.

Inherited methods

From class android.service.wallpaper.WallpaperService.Engine
From class java.lang.Object

Public constructors

WatchFaceService.Engine

WatchFaceService.Engine ()

Public methods

getInterruptionFilter

int getInterruptionFilter ()

Returns interruption filter selected by the user.

Returns
int INTERRUPTION_FILTER_NONE, INTERRUPTION_FILTER_PRIORITY, INTERRUPTION_FILTER_ALL, INTERRUPTION_FILTER_ALARMS, or INTERRUPTION_FILTER_UNKNOWN.

getNotificationCount

int getNotificationCount ()

Returns the total number of notification cards in the stream.

Returns
int

getPeekCardPosition

Rect getPeekCardPosition ()

This method is deprecated.
Wear 2.0 doesn't have peeking cards

Returns the location of the first peeking card. This doesn't provide information about all movements of the card, only about its location when it's peeking at the bottom and allowing the watch face to be exposed.

Returns
Rect

getUnreadCount

int getUnreadCount ()

Returns the number of unread notification cards in the stream.

Returns
int

isInAmbientMode

boolean isInAmbientMode ()

Returns whether the watch face is in ambient mode. When true, the watch face should display in white on black.

Returns
boolean

onAmbientModeChanged

void onAmbientModeChanged (boolean inAmbientMode)

Called when the device enters or exits ambient mode. The watch face should switch to a black and white display in ambient mode. If the watch face displays seconds, it should hide them in ambient mode.

Parameters
inAmbientMode boolean

onCommand

Bundle onCommand (String action, 
                int x, 
                int y, 
                int z, 
                Bundle extras, 
                boolean resultRequested)

Parameters
action String

x int

y int

z int

extras Bundle

resultRequested boolean

Returns
Bundle

onComplicationDataUpdate

void onComplicationDataUpdate (int watchFaceComplicationId, 
                ComplicationData data)

Called when new complication data is received.

Parameters
watchFaceComplicationId int: The id of the complication that the data relates to. This will be an id that was previously sent in a call to setActiveComplications(int...).

data ComplicationData: The data that should be displayed in the complication.

onCreate

void onCreate (SurfaceHolder holder)

Parameters
holder SurfaceHolder

onDestroy

void onDestroy ()

onInterruptionFilterChanged

void onInterruptionFilterChanged (int interruptionFilter)

Called when the user changes interruption filter. The watch face should adjust the amount of information it displays. For example, if it displays the number of pending emails, it should hide it if interruptionFilter is equal to INTERRUPTION_FILTER_NONE. interruptionFilter can be INTERRUPTION_FILTER_NONE, INTERRUPTION_FILTER_PRIORITY, INTERRUPTION_FILTER_ALL, INTERRUPTION_FILTER_ALARMS, or INTERRUPTION_FILTER_UNKNOWN.

Parameters
interruptionFilter int

onNotificationCountChanged

void onNotificationCountChanged (int count)

Called when the total number of notification cards in the stream has changed.

Parameters
count int: total number of the notification cards in the stream

onPeekCardPositionUpdate

void onPeekCardPositionUpdate (Rect rect)

This method is deprecated.
Wear 2.0 doesn't have peeking cards

Called when the first, peeking card positions itself on the screen. This is where the watch face can change its appearance depending on where the card is on the screen. This doesn't provide information about all movements of the card, only about its location when it's peeking at the bottom and allowing the watch face to be exposed.

Parameters
rect Rect

onPropertiesChanged

void onPropertiesChanged (Bundle properties)

Called when the properties of the device are determined. These include PROPERTY_BURN_IN_PROTECTION and PROPERTY_LOW_BIT_AMBIENT.

Parameters
properties Bundle: a bundle containing the hardware properties

onTapCommand

void onTapCommand (int tapType, 
                int x, 
                int y, 
                long eventTime)

Called when a tap or touch related event occurs.

Parameters
tapType int: Value representing the event sent to the wallpaper.

x int: X coordinate of the event.

y int: Y coordinate of the event.

eventTime long: The time the tap occurred, in the uptimeMillis() time base

onTimeTick

void onTimeTick ()

Called periodically to update the time shown by the watch face. This method is called:

  • at least once per minute in both ambient and interactive modes
  • when date or time has changed
  • when timezone has changed

onTouchEvent

void onTouchEvent (MotionEvent event)

This method is deprecated.
Do not use this to receive touch events on a watch face. Instead, use setAcceptsTapEvents(boolean) and then override onTapCommand(int, int, int, long). This method will cease to function in a future release.

Parameters
event MotionEvent

onUnreadCountChanged

void onUnreadCountChanged (int count)

Called when the number of unread notification cards in the stream has changed.

Parameters
count int: number of the notification cards in the stream that haven't yet been seen by the user

onVisibilityChanged

void onVisibilityChanged (boolean visible)

Called to inform you of the watch face becoming visible or hidden. If you decide to override this method, you must call super.onVisibilityChanged(visible) as the first statement in your override.

Parameters
visible boolean

setActiveComplications

void setActiveComplications (int... watchFaceComplicationIds)

Sets the complications which are active in the watchface. Complication data will be received for these ids.

Any ids not in the provided ids will be considered inactive.

If providers and complication data types have been configured, the data received will match the type chosen by the user. If no provider has been configured, data of type TYPE_NOT_CONFIGURED will be received.

Ids here are chosen by the watch face to represent each complication and can be any integer.

Parameters
watchFaceComplicationIds int

setDefaultComplicationProvider

void setDefaultComplicationProvider (int watchFaceComplicationId, 
                ComponentName provider, 
                int type)

Sets a custom provider as the default provider for the specified watch face complication id. This may be used to set a non-system provider as a default, if the component name of the provider is known. To set a system provider as a default, use setDefaultSystemComplicationProvider(int, int, int) instead.

This will do nothing if the provider is not installed, or if the specified type is not supported by the provider, or if the user has already selected a provider for the complication.

Note that if the watch face has not yet been granted the RECEIVE_COMPLICATION_DATA permission, it will not be able to receive data from the provider unless the provider is from the same app package as the watch face, or the provider lists the watch face as a safe watch face. For system providers that may be used before your watch face has the permission, use setDefaultSystemComplicationProvider(int, int, int) with a safe provider instead.

A provider not satisfying the above conditions may still be set as a default using this method, but the watch face will receive dummy data of type TYPE_NO_PERMISSION until the permission has been granted.

To set an 'empty' default, this method may be used with provider equal to null, and type equal to TYPE_EMPTY. It is not required to do this for all complications - any complications with no default set and no user-selected provider will receive data of TYPE_NOT_CONFIGURED.

Parameters
watchFaceComplicationId int

provider ComponentName

type int

setDefaultSystemComplicationProvider

void setDefaultSystemComplicationProvider (int watchFaceComplicationId, 
                int systemProvider, 
                int type)

Sets a system provider as the default provider for the specified watch face complication id.

The chosen provider must be one listed in the SystemProviders class.

This will do nothing if the provider is not installed, or if the specified type is not supported by the provider, or if the user has already selected a provider for the complication.

Note that if the watch face has not yet been granted the RECEIVE_COMPLICATION_DATA permission, it will not be able to receive data from the provider unless it is a safe provider (see the provider descriptions in the SystemProviders class).

A non-safe provider may still be set as a default using this method, but the watch face will receive dummy data of type TYPE_NO_PERMISSION until the permission has been granted.

It is not required to do this for all complications - any complications with no default set and no user-selected provider will receive data of TYPE_NOT_CONFIGURED.

To set a non-system provider as a default, or to clear a default, use setDefaultComplicationProvider(int, ComponentName, int).

Parameters
watchFaceComplicationId int

systemProvider int

type int

setTouchEventsEnabled

void setTouchEventsEnabled (boolean enabled)

This method is deprecated.
Do not use this to receive touch events on a watch face. Instead, use setAcceptsTapEvents(boolean) and then override onTapCommand(int, int, int, long). This method will cease to function in a future release.

Parameters
enabled boolean

setWatchFaceStyle

void setWatchFaceStyle (WatchFaceStyle watchFaceStyle)

Sets the watch face style. This affects how UI elements such as the battery indicator are drawn on top of the watch face. Typically called in onCreate(SurfaceHolder) but may be called at any time, e.g. in response to the user changing the watch face configuration. Must be called from the wallpaper thread.

Parameters
watchFaceStyle WatchFaceStyle

This site uses cookies to store your preferences for site-specific language and display options.

Get the latest Android developer news and tips that will help you find success on Google Play.

* Required Fields

Hooray!

Follow Google Developers on WeChat

Browse this site in ?

You requested a page in , but your language preference for this site is .

Would you like to change your language preference and browse this site in ? If you want to change your language preference later, use the language menu at the bottom of each page.

This class requires API level or higher

This doc is hidden because your selected API level for the documentation is . You can change the documentation API level with the selector above the left navigation.

For more information about specifying the API level your app requires, read Supporting Different Platform Versions.

Take a short survey?
Help us improve the Android developer experience. (Dec 2017 Android Platform & Tools Survey)