Android APIs
public static final class

Notification.WearableExtender

extends Object
implements Notification.Extender
java.lang.Object
   ↳ android.app.Notification.WearableExtender

Class Overview

Helper class to add wearable extensions to notifications.

See Creating Notifications for Android Wear for more information on how to use this class.

To create a notification with wearable extensions:

  1. Create a Notification.Builder, setting any desired properties.
  2. Create a Notification.WearableExtender.
  3. Set wearable-specific properties using the add and set methods of Notification.WearableExtender.
  4. Call extend(Notification.Extender) to apply the extensions to a notification.
  5. Post the notification to the notification system with the NotificationManager.notify(...) methods.
 Notification notif = new Notification.Builder(mContext)
         .setContentTitle("New mail from " + sender.toString())
         .setContentText(subject)
         .setSmallIcon(R.drawable.new_mail)
         .extend(new Notification.WearableExtender()
                 .setContentIcon(R.drawable.new_mail))
         .build();
 NotificationManager notificationManger =
         (NotificationManager) getSystemService(Context.NOTIFICATION_SERVICE);
 notificationManger.notify(0, notif);

Wearable extensions can be accessed on an existing notification by using the WearableExtender(Notification) constructor, and then using the get methods to access values.

 Notification.WearableExtender wearableExtender = new Notification.WearableExtender(
         notification);
 List<Notification> pages = wearableExtender.getPages();

Summary

Constants
int SCREEN_TIMEOUT_LONG Sentinel value for use with setHintScreenTimeout(int) to keep the screen on for a longer amount of time when this notification is displayed on the screen.
int SCREEN_TIMEOUT_SHORT Sentinel value for use with setHintScreenTimeout(int) to keep the screen on for a short amount of time when this notification is displayed on the screen.
int SIZE_DEFAULT Size value for use with setCustomSizePreset(int) to show this notification with default sizing.
int SIZE_FULL_SCREEN Size value for use with setCustomSizePreset(int) to show this notification full screen.
int SIZE_LARGE Size value for use with setCustomSizePreset(int) to show this notification with a large size.
int SIZE_MEDIUM Size value for use with setCustomSizePreset(int) to show this notification with a medium size.
int SIZE_SMALL Size value for use with setCustomSizePreset(int) to show this notification with a small size.
int SIZE_XSMALL Size value for use with setCustomSizePreset(int) to show this notification with an extra small size.
int UNSET_ACTION_INDEX Sentinel value for an action index that is unset.
Public Constructors
Notification.WearableExtender()
Create a Notification.WearableExtender with default options.
Notification.WearableExtender(Notification notif)
Public Methods
Notification.WearableExtender addAction(Notification.Action action)
Add a wearable action to this notification.
Notification.WearableExtender addActions(List<Notification.Action> actions)
Adds wearable actions to this notification.
Notification.WearableExtender addPage(Notification page)
Add an additional page of content to display with this notification.
Notification.WearableExtender addPages(List<Notification> pages)
Add additional pages of content to display with this notification.
Notification.WearableExtender clearActions()
Clear all wearable actions present on this builder.
Notification.WearableExtender clearPages()
Clear all additional pages present on this builder.
Notification.WearableExtender clone()
Creates and returns a copy of this Object.
Notification.Builder extend(Notification.Builder builder)
Apply wearable extensions to a notification that is being built.
List<Notification.Action> getActions()
Get the wearable actions present on this notification.
Bitmap getBackground()
Get a background image to be displayed behind the notification content.
int getContentAction()
Get the index of the notification action, if any, that was specified as being clickable with the content of this notification.
int getContentIcon()
Get an icon that goes with the content of this notification.
int getContentIconGravity()
Get the gravity that the content icon should have within the notification display.
boolean getContentIntentAvailableOffline()
Get whether the content intent is available when the wearable device is not connected to a companion device.
int getCustomContentHeight()
Get the custom height in pixels for the display of this notification's content.
int getCustomSizePreset()
Get the custom size preset for the display of this notification out of the available presets found in Notification.WearableExtender, e.g.
PendingIntent getDisplayIntent()
Get the intent to launch inside of an activity view when displaying this notification.
int getGravity()
Get the gravity that this notification should have within the available viewport space.
boolean getHintAvoidBackgroundClipping()
Get a hint that this notification's background should not be clipped if possible, and should instead be resized to fully display on the screen, retaining the aspect ratio of the image.
boolean getHintHideIcon()
Get a hint that this notification's icon should not be displayed.
int getHintScreenTimeout()
Get the duration, in milliseconds, that the screen should remain on for when this notification is displayed.
boolean getHintShowBackgroundOnly()
Get a visual hint that only the background image of this notification should be displayed, and other semantic content should be hidden.
List<Notification> getPages()
Get the array of additional pages of content for displaying this notification.
boolean getStartScrollBottom()
Get whether the scrolling position for the contents of this notification should start at the bottom of the contents instead of the top when the contents are too long to display within the screen.
Notification.WearableExtender setBackground(Bitmap background)
Set a background image to be displayed behind the notification content.
Notification.WearableExtender setContentAction(int actionIndex)
Set an action from this notification's actions to be clickable with the content of this notification.
Notification.WearableExtender setContentIcon(int icon)
Set an icon that goes with the content of this notification.
Notification.WearableExtender setContentIconGravity(int contentIconGravity)
Set the gravity that the content icon should have within the notification display.
Notification.WearableExtender setContentIntentAvailableOffline(boolean contentIntentAvailableOffline)
Set whether the content intent is available when the wearable device is not connected to a companion device.
Notification.WearableExtender setCustomContentHeight(int height)
Set the custom height in pixels for the display of this notification's content.
Notification.WearableExtender setCustomSizePreset(int sizePreset)
Set the custom size preset for the display of this notification out of the available presets found in Notification.WearableExtender, e.g.
Notification.WearableExtender setDisplayIntent(PendingIntent intent)
Set an intent to launch inside of an activity view when displaying this notification.
Notification.WearableExtender setGravity(int gravity)
Set the gravity that this notification should have within the available viewport space.
Notification.WearableExtender setHintAvoidBackgroundClipping(boolean hintAvoidBackgroundClipping)
Set a hint that this notification's background should not be clipped if possible, and should instead be resized to fully display on the screen, retaining the aspect ratio of the image.
Notification.WearableExtender setHintHideIcon(boolean hintHideIcon)
Set a hint that this notification's icon should not be displayed.
Notification.WearableExtender setHintScreenTimeout(int timeout)
Set a hint that the screen should remain on for at least this duration when this notification is displayed on the screen.
Notification.WearableExtender setHintShowBackgroundOnly(boolean hintShowBackgroundOnly)
Set a visual hint that only the background image of this notification should be displayed, and other semantic content should be hidden.
Notification.WearableExtender setStartScrollBottom(boolean startScrollBottom)
Set whether the scrolling position for the contents of this notification should start at the bottom of the contents instead of the top when the contents are too long to display within the screen.
[Expand]
Inherited Methods
From class java.lang.Object
From interface android.app.Notification.Extender

Constants

public static final int SCREEN_TIMEOUT_LONG

Sentinel value for use with setHintScreenTimeout(int) to keep the screen on for a longer amount of time when this notification is displayed on the screen.

Constant Value: -1 (0xffffffff)

public static final int SCREEN_TIMEOUT_SHORT

Sentinel value for use with setHintScreenTimeout(int) to keep the screen on for a short amount of time when this notification is displayed on the screen. This is the default value.

Constant Value: 0 (0x00000000)

public static final int SIZE_DEFAULT

Added in API level 20

Size value for use with setCustomSizePreset(int) to show this notification with default sizing.

For custom display notifications created using setDisplayIntent(PendingIntent), the default is SIZE_LARGE. All other notifications size automatically based on their content.

Constant Value: 0 (0x00000000)

public static final int SIZE_FULL_SCREEN

Added in API level 20

Size value for use with setCustomSizePreset(int) to show this notification full screen.

This value is only applicable for custom display notifications created using setDisplayIntent(PendingIntent).

Constant Value: 5 (0x00000005)

public static final int SIZE_LARGE

Added in API level 20

Size value for use with setCustomSizePreset(int) to show this notification with a large size.

This value is only applicable for custom display notifications created using setDisplayIntent(PendingIntent).

Constant Value: 4 (0x00000004)

public static final int SIZE_MEDIUM

Added in API level 20

Size value for use with setCustomSizePreset(int) to show this notification with a medium size.

This value is only applicable for custom display notifications created using setDisplayIntent(PendingIntent).

Constant Value: 3 (0x00000003)

public static final int SIZE_SMALL

Added in API level 20

Size value for use with setCustomSizePreset(int) to show this notification with a small size.

This value is only applicable for custom display notifications created using setDisplayIntent(PendingIntent).

Constant Value: 2 (0x00000002)

public static final int SIZE_XSMALL

Added in API level 20

Size value for use with setCustomSizePreset(int) to show this notification with an extra small size.

This value is only applicable for custom display notifications created using setDisplayIntent(PendingIntent).

Constant Value: 1 (0x00000001)

public static final int UNSET_ACTION_INDEX

Added in API level 20

Sentinel value for an action index that is unset.

Constant Value: -1 (0xffffffff)

Public Constructors

public Notification.WearableExtender ()

Added in API level 20

Create a Notification.WearableExtender with default options.

public Notification.WearableExtender (Notification notif)

Added in API level 20

Public Methods

public Notification.WearableExtender addAction (Notification.Action action)

Added in API level 20

Add a wearable action to this notification.

When wearable actions are added using this method, the set of actions that show on a wearable device splits from devices that only show actions added using addAction(Notification.Action). This allows for customization of which actions display on different devices.

Parameters
action the action to add to this notification
Returns
  • this object for method chaining

public Notification.WearableExtender addActions (List<Notification.Action> actions)

Added in API level 20

Adds wearable actions to this notification.

When wearable actions are added using this method, the set of actions that show on a wearable device splits from devices that only show actions added using addAction(Notification.Action). This allows for customization of which actions display on different devices.

Parameters
actions the actions to add to this notification
Returns
  • this object for method chaining

public Notification.WearableExtender addPage (Notification page)

Added in API level 20

Add an additional page of content to display with this notification. The current notification forms the first page, and pages added using this function form subsequent pages. This field can be used to separate a notification into multiple sections.

Parameters
page the notification to add as another page
Returns
  • this object for method chaining
See Also

public Notification.WearableExtender addPages (List<Notification> pages)

Added in API level 20

Add additional pages of content to display with this notification. The current notification forms the first page, and pages added using this function form subsequent pages. This field can be used to separate a notification into multiple sections.

Parameters
pages a list of notifications
Returns
  • this object for method chaining
See Also

public Notification.WearableExtender clearActions ()

Added in API level 20

Clear all wearable actions present on this builder.

Returns
  • this object for method chaining.

public Notification.WearableExtender clearPages ()

Added in API level 20

Clear all additional pages present on this builder.

Returns
  • this object for method chaining.

public Notification.WearableExtender clone ()

Added in API level 20

Creates and returns a copy of this Object. The default implementation returns a so-called "shallow" copy: It creates a new instance of the same class and then copies the field values (including object references) from this instance to the new instance. A "deep" copy, in contrast, would also recursively clone nested objects. A subclass that needs to implement this kind of cloning should call super.clone() to create the new instance and then create deep copies of the nested, mutable objects.

Returns
  • a copy of this object.

public Notification.Builder extend (Notification.Builder builder)

Added in API level 20

Apply wearable extensions to a notification that is being built. This is typically called by the extend(Notification.Extender) method of Notification.Builder.

Parameters
builder the builder to be modified.
Returns
  • the build object for chaining.

public List<Notification.Action> getActions ()

Added in API level 20

Get the wearable actions present on this notification.

public Bitmap getBackground ()

Added in API level 20

Get a background image to be displayed behind the notification content. Contrary to the Notification.BigPictureStyle, this background will work with any notification style.

Returns
  • the background image

public int getContentAction ()

Added in API level 20

Get the index of the notification action, if any, that was specified as being clickable with the content of this notification. This action will no longer display separately from the notification's content.

For notifications with multiple pages, child pages can also have content actions set, although the list of available actions comes from the main notification and not from the child page's notification.

If wearable specific actions were added to the main notification, this index will apply to that list, otherwise it will apply to the regular actions list.

Returns

public int getContentIcon ()

Added in API level 20

Get an icon that goes with the content of this notification.

public int getContentIconGravity ()

Added in API level 20

Get the gravity that the content icon should have within the notification display. Supported values include START and END. The default value is END.

See Also

public boolean getContentIntentAvailableOffline ()

Added in API level 20

Get whether the content intent is available when the wearable device is not connected to a companion device. The user can still trigger this intent when the wearable device is offline, but a visual hint will indicate that the content intent may not be available. Defaults to true.

public int getCustomContentHeight ()

Added in API level 20

Get the custom height in pixels for the display of this notification's content.

This option is only available for custom display notifications created using setDisplayIntent(PendingIntent). See also setCustomSizePreset(int) and setCustomContentHeight(int).

public int getCustomSizePreset ()

Added in API level 20

Get the custom size preset for the display of this notification out of the available presets found in Notification.WearableExtender, e.g. SIZE_LARGE.

Some custom size presets are only applicable for custom display notifications created using setDisplayIntent(PendingIntent). Check the documentation for the preset in question. See also setCustomContentHeight(int) and setCustomSizePreset(int).

public PendingIntent getDisplayIntent ()

Added in API level 20

Get the intent to launch inside of an activity view when displaying this notification. This PendingIntent should be for an activity.

public int getGravity ()

Added in API level 20

Get the gravity that this notification should have within the available viewport space. Supported values include TOP, CENTER_VERTICAL and BOTTOM. The default value is BOTTOM.

public boolean getHintAvoidBackgroundClipping ()

Get a hint that this notification's background should not be clipped if possible, and should instead be resized to fully display on the screen, retaining the aspect ratio of the image. This can be useful for images like barcodes or qr codes.

Returns
  • true if it's ok if the background is clipped on the screen, false otherwise. The default value is false if this was never set.

public boolean getHintHideIcon ()

Added in API level 20

Get a hint that this notification's icon should not be displayed.

Returns
  • true if this icon should not be displayed, false otherwise. The default value is false if this was never set.

public int getHintScreenTimeout ()

Get the duration, in milliseconds, that the screen should remain on for when this notification is displayed.

Returns

public boolean getHintShowBackgroundOnly ()

Added in API level 20

Get a visual hint that only the background image of this notification should be displayed, and other semantic content should be hidden. This hint is only applicable to sub-pages added using addPage(Notification).

public List<Notification> getPages ()

Added in API level 20

Get the array of additional pages of content for displaying this notification. The current notification forms the first page, and elements within this array form subsequent pages. This field can be used to separate a notification into multiple sections.

Returns
  • the pages for this notification

public boolean getStartScrollBottom ()

Added in API level 20

Get whether the scrolling position for the contents of this notification should start at the bottom of the contents instead of the top when the contents are too long to display within the screen. Default is false (start scroll at the top).

public Notification.WearableExtender setBackground (Bitmap background)

Added in API level 20

Set a background image to be displayed behind the notification content. Contrary to the Notification.BigPictureStyle, this background will work with any notification style.

Parameters
background the background bitmap
Returns
  • this object for method chaining
See Also

public Notification.WearableExtender setContentAction (int actionIndex)

Added in API level 20

Set an action from this notification's actions to be clickable with the content of this notification. This action will no longer display separately from the notification's content.

For notifications with multiple pages, child pages can also have content actions set, although the list of available actions comes from the main notification and not from the child page's notification.

Parameters
actionIndex The index of the action to hoist onto the current notification page. If wearable actions were added to the main notification, this index will apply to that list, otherwise it will apply to the regular actions list.

public Notification.WearableExtender setContentIcon (int icon)

Added in API level 20

Set an icon that goes with the content of this notification.

public Notification.WearableExtender setContentIconGravity (int contentIconGravity)

Added in API level 20

Set the gravity that the content icon should have within the notification display. Supported values include START and END. The default value is END.

public Notification.WearableExtender setContentIntentAvailableOffline (boolean contentIntentAvailableOffline)

Added in API level 20

Set whether the content intent is available when the wearable device is not connected to a companion device. The user can still trigger this intent when the wearable device is offline, but a visual hint will indicate that the content intent may not be available. Defaults to true.

public Notification.WearableExtender setCustomContentHeight (int height)

Added in API level 20

Set the custom height in pixels for the display of this notification's content.

This option is only available for custom display notifications created using setDisplayIntent(PendingIntent). See also setCustomSizePreset(int) and getCustomContentHeight().

public Notification.WearableExtender setCustomSizePreset (int sizePreset)

Added in API level 20

Set the custom size preset for the display of this notification out of the available presets found in Notification.WearableExtender, e.g. SIZE_LARGE.

Some custom size presets are only applicable for custom display notifications created using setDisplayIntent(PendingIntent). Check the documentation for the preset in question. See also setCustomContentHeight(int) and getCustomSizePreset().

public Notification.WearableExtender setDisplayIntent (PendingIntent intent)

Added in API level 20

Set an intent to launch inside of an activity view when displaying this notification. The PendingIntent provided should be for an activity.

 Intent displayIntent = new Intent(context, MyDisplayActivity.class);
 PendingIntent displayPendingIntent = PendingIntent.getActivity(context,
         0, displayIntent, PendingIntent.FLAG_UPDATE_CURRENT);
 Notification notif = new Notification.Builder(context)
         .extend(new Notification.WearableExtender()
                 .setDisplayIntent(displayPendingIntent)
                 .setCustomSizePreset(Notification.WearableExtender.SIZE_MEDIUM))
         .build();

The activity to launch needs to allow embedding, must be exported, and should have an empty task affinity. It is also recommended to use the device default light theme.

Example AndroidManifest.xml entry:

 <activity android:name="com.example.MyDisplayActivity"
     android:exported="true"
     android:allowEmbedded="true"
     android:taskAffinity=""
     android:theme="@android:style/Theme.DeviceDefault.Light" />

Parameters
intent the PendingIntent for an activity
Returns
  • this object for method chaining

public Notification.WearableExtender setGravity (int gravity)

Added in API level 20

Set the gravity that this notification should have within the available viewport space. Supported values include TOP, CENTER_VERTICAL and BOTTOM. The default value is BOTTOM.

public Notification.WearableExtender setHintAvoidBackgroundClipping (boolean hintAvoidBackgroundClipping)

Set a hint that this notification's background should not be clipped if possible, and should instead be resized to fully display on the screen, retaining the aspect ratio of the image. This can be useful for images like barcodes or qr codes.

Parameters
hintAvoidBackgroundClipping true to avoid clipping if possible.
Returns
  • this object for method chaining

public Notification.WearableExtender setHintHideIcon (boolean hintHideIcon)

Added in API level 20

Set a hint that this notification's icon should not be displayed.

Parameters
hintHideIcon true to hide the icon, false otherwise.
Returns
  • this object for method chaining

public Notification.WearableExtender setHintScreenTimeout (int timeout)

Set a hint that the screen should remain on for at least this duration when this notification is displayed on the screen.

Parameters
timeout The requested screen timeout in milliseconds. Can also be either SCREEN_TIMEOUT_SHORT or SCREEN_TIMEOUT_LONG.
Returns
  • this object for method chaining

public Notification.WearableExtender setHintShowBackgroundOnly (boolean hintShowBackgroundOnly)

Added in API level 20

Set a visual hint that only the background image of this notification should be displayed, and other semantic content should be hidden. This hint is only applicable to sub-pages added using addPage(Notification).

public Notification.WearableExtender setStartScrollBottom (boolean startScrollBottom)

Added in API level 20

Set whether the scrolling position for the contents of this notification should start at the bottom of the contents instead of the top when the contents are too long to display within the screen. Default is false (start scroll at the top).