java.lang.Object
↳androidx.core.app.NotificationCompat.WearableExtender
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:
- Create a NotificationCompat.Builder, setting any desired
properties.
- Create a NotificationCompat.WearableExtender.
- Set wearable-specific properties using the
add and set methods of NotificationCompat.WearableExtender.
- Call NotificationCompat.Builder.extend(NotificationCompat.Extender) to apply the extensions to a
notification.
- Post the notification to the notification
system with the NotificationManagerCompat.notify(...) methods
and not the NotificationManager.notify(...) methods.
Notification notification = new NotificationCompat.Builder(mContext)
.setContentTitle("New mail from " + sender.toString())
.setContentText(subject)
.setSmallIcon(R.drawable.new_mail)
.extend(new NotificationCompat.WearableExtender()
.setContentIcon(R.drawable.new_mail))
.build();
NotificationManagerCompat.from(mContext).notify(0, notification);
Wearable extensions can be accessed on an existing notification by using the
WearableExtender(Notification) constructor,
and then using the get methods to access values.
NotificationCompat.WearableExtender wearableExtender =
new NotificationCompat.WearableExtender(notification);
List<Notification> pages = wearableExtender.getPages();
Summary
Methods |
---|
public NotificationCompat.WearableExtender | addAction(NotificationCompat.Action action)
Add a wearable action to this notification. |
public NotificationCompat.WearableExtender | addActions(java.util.List<NotificationCompat.Action> actions)
Adds wearable actions to this notification. |
public NotificationCompat.WearableExtender | addPage(Notification page)
Add an additional page of content to display with this notification. |
public NotificationCompat.WearableExtender | addPages(java.util.List<Notification> pages)
Add additional pages of content to display with this notification. |
public NotificationCompat.WearableExtender | clearActions()
Clear all wearable actions present on this builder. |
public NotificationCompat.WearableExtender | clearPages()
Clear all additional pages present on this builder. |
public NotificationCompat.WearableExtender | clone()
|
public NotificationCompat.Builder | extend(NotificationCompat.Builder builder)
Apply wearable extensions to a notification that is being built. |
public java.util.List<NotificationCompat.Action> | getActions()
Get the wearable actions present on this notification. |
public Bitmap | getBackground()
Get a background image to be displayed behind the notification content. |
public java.lang.String | getBridgeTag()
Returns the bridge tag of the notification. |
public int | getContentAction()
Get the index of the notification action, if any, that was specified as the primary
action. |
public int | getContentIcon()
Get an icon that goes with the content of this notification. |
public int | getContentIconGravity()
Get the gravity that the content icon should have within the notification display. |
public boolean | getContentIntentAvailableOffline()
Get whether the content intent is available when the wearable device is not connected
to a companion device. |
public int | getCustomContentHeight()
Get the custom height in pixels for the display of this notification's content. |
public int | getCustomSizePreset()
Get the custom size preset for the display of this notification out of the available
presets found in NotificationCompat.WearableExtender, e.g. |
public java.lang.String | getDismissalId()
Returns the dismissal id of the notification. |
public PendingIntent | getDisplayIntent()
Get the intent to launch inside of an activity view when displaying this
notification. |
public int | getGravity()
Get the gravity that this notification should have within the available viewport space. |
public boolean | getHintAmbientBigPicture()
Get a hint that this notification's NotificationCompat.BigPictureStyle (if present) should be
converted to low-bit and displayed in ambient mode, especially useful for barcodes and
qr codes, as well as other simple black-and-white tickets. |
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. |
public boolean | getHintContentIntentLaunchesActivity()
Get a hint that this notification's content intent will launch an
directly, telling the platform that it can generate the appropriate transitions |
public boolean | getHintHideIcon()
Get a hint that this notification's icon should not be displayed. |
public int | getHintScreenTimeout()
Get the duration, in milliseconds, that the screen should remain on for
when this notification is displayed. |
public boolean | getHintShowBackgroundOnly()
Get a visual hint that only the background image of this notification should be
displayed, and other semantic content should be hidden. |
public java.util.List<Notification> | getPages()
Get the array of additional pages of content for displaying this notification. |
public 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. |
public NotificationCompat.WearableExtender | setBackground(Bitmap background)
Set a background image to be displayed behind the notification content. |
public NotificationCompat.WearableExtender | setBridgeTag(java.lang.String bridgeTag)
Sets a bridge tag for this notification. |
public NotificationCompat.WearableExtender | setContentAction(int actionIndex)
Set an action from this notification's actions as the primary action. |
public NotificationCompat.WearableExtender | setContentIcon(int icon)
Set an icon that goes with the content of this notification. |
public NotificationCompat.WearableExtender | setContentIconGravity(int contentIconGravity)
Set the gravity that the content icon should have within the notification display. |
public NotificationCompat.WearableExtender | setContentIntentAvailableOffline(boolean contentIntentAvailableOffline)
Set whether the content intent is available when the wearable device is not connected
to a companion device. |
public NotificationCompat.WearableExtender | setCustomContentHeight(int height)
Set the custom height in pixels for the display of this notification's content. |
public NotificationCompat.WearableExtender | setCustomSizePreset(int sizePreset)
Set the custom size preset for the display of this notification out of the available
presets found in NotificationCompat.WearableExtender, e.g. |
public NotificationCompat.WearableExtender | setDismissalId(java.lang.String dismissalId)
Sets the dismissal id for this notification. |
public NotificationCompat.WearableExtender | setDisplayIntent(PendingIntent intent)
Set an intent to launch inside of an activity view when displaying
this notification. |
public NotificationCompat.WearableExtender | setGravity(int gravity)
Set the gravity that this notification should have within the available viewport space. |
public NotificationCompat.WearableExtender | setHintAmbientBigPicture(boolean hintAmbientBigPicture)
Set a hint that this notification's NotificationCompat.BigPictureStyle (if present) should be
converted to low-bit and displayed in ambient mode, especially useful for barcodes and
qr codes, as well as other simple black-and-white tickets. |
public NotificationCompat.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. |
public NotificationCompat.WearableExtender | setHintContentIntentLaunchesActivity(boolean hintContentIntentLaunchesActivity)
Set a hint that this notification's content intent will launch an
directly, telling the platform that it can generate the appropriate transitions. |
public NotificationCompat.WearableExtender | setHintHideIcon(boolean hintHideIcon)
Set a hint that this notification's icon should not be displayed. |
public NotificationCompat.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. |
public NotificationCompat.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. |
public NotificationCompat.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. |
from java.lang.Object | equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Fields
public static final int
UNSET_ACTION_INDEXSentinel value for an action index that is unset.
public static final int
SIZE_DEFAULTDeprecated: Display intents are no longer supported.
Size value for use with NotificationCompat.WearableExtender.setCustomSizePreset(int) to show this notification with
default sizing.
For custom display notifications created using NotificationCompat.WearableExtender.setDisplayIntent(PendingIntent),
the default is NotificationCompat.WearableExtender.SIZE_MEDIUM. All other notifications size automatically based
on their content.
public static final int
SIZE_XSMALLDeprecated: Display intents are no longer supported.
Size value for use with NotificationCompat.WearableExtender.setCustomSizePreset(int) to show this notification
with an extra small size.
This value is only applicable for custom display notifications created using
NotificationCompat.WearableExtender.setDisplayIntent(PendingIntent).
public static final int
SIZE_SMALLDeprecated: Display intents are no longer supported.
Size value for use with NotificationCompat.WearableExtender.setCustomSizePreset(int) to show this notification
with a small size.
This value is only applicable for custom display notifications created using
NotificationCompat.WearableExtender.setDisplayIntent(PendingIntent).
public static final int
SIZE_MEDIUMDeprecated: Display intents are no longer supported.
Size value for use with NotificationCompat.WearableExtender.setCustomSizePreset(int) to show this notification
with a medium size.
This value is only applicable for custom display notifications created using
NotificationCompat.WearableExtender.setDisplayIntent(PendingIntent).
public static final int
SIZE_LARGEDeprecated: Display intents are no longer supported.
Size value for use with NotificationCompat.WearableExtender.setCustomSizePreset(int) to show this notification
with a large size.
This value is only applicable for custom display notifications created using
NotificationCompat.WearableExtender.setDisplayIntent(PendingIntent).
public static final int
SIZE_FULL_SCREENDeprecated: Display intents are no longer supported.
Size value for use with NotificationCompat.WearableExtender.setCustomSizePreset(int) to show this notification
full screen.
This value is only applicable for custom display notifications created using
NotificationCompat.WearableExtender.setDisplayIntent(PendingIntent).
public static final int
SCREEN_TIMEOUT_SHORTDeprecated: This feature is no longer supported.
Sentinel value for use with NotificationCompat.WearableExtender.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.
public static final int
SCREEN_TIMEOUT_LONGDeprecated: This feature is no longer supported.
Sentinel value for use with NotificationCompat.WearableExtender.setHintScreenTimeout(int) to keep the screen on
for a longer amount of time when this notification is displayed on the screen.
Constructors
public
WearableExtender()
Create a NotificationCompat.WearableExtender with default
options.
public
WearableExtender(Notification notification)
Methods
Apply wearable extensions to a notification that is being built. This is typically
called by the NotificationCompat.Builder.extend(NotificationCompat.Extender) method of
NotificationCompat.Builder.
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 NotificationCompat.Builder.addAction(int, CharSequence, PendingIntent). 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
See also: NotificationCompat.Action
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 NotificationCompat.Builder.addAction(int, CharSequence, PendingIntent). 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
See also: NotificationCompat.Action
Clear all wearable actions present on this builder.
Returns:
this object for method chaining.
See also: NotificationCompat.WearableExtender.addAction(NotificationCompat.Action)
public java.util.List<NotificationCompat.Action>
getActions()
Get the wearable actions present on this notification.
Deprecated: Display intents are no longer supported.
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 notification = new NotificationCompat.Builder(context)
.extend(new NotificationCompat.WearableExtender()
.setDisplayIntent(displayPendingIntent)
.setCustomSizePreset(NotificationCompat.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
See also: NotificationCompat.WearableExtender.getDisplayIntent()
public PendingIntent
getDisplayIntent()
Deprecated: Display intents are no longer supported.
Get the intent to launch inside of an activity view when displaying this
notification. This PendingIntent should be for an activity.
Deprecated: Multiple content pages are no longer supported.
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: NotificationCompat.WearableExtender.getPages()
Deprecated: Multiple content pages are no longer supported.
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: NotificationCompat.WearableExtender.getPages()
Deprecated: Multiple content pages are no longer supported.
Clear all additional pages present on this builder.
Returns:
this object for method chaining.
See also: NotificationCompat.WearableExtender.addPage(Notification)
public java.util.List<Notification>
getPages()
Deprecated: Multiple content pages are no longer supported.
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
Deprecated: Background images are no longer supported.
Set a background image to be displayed behind the notification content.
Contrary to the NotificationCompat.BigPictureStyle, this background
will work with any notification style.
Parameters:
background: the background bitmap
Returns:
this object for method chaining
See also: NotificationCompat.WearableExtender.getBackground()
public Bitmap
getBackground()
Deprecated: Background images are no longer supported.
Get a background image to be displayed behind the notification content.
Contrary to the NotificationCompat.BigPictureStyle, this background
will work with any notification style.
Returns:
the background image
See also: NotificationCompat.WearableExtender.setBackground(Bitmap)
Deprecated: This method has no effect starting with Wear 2.0.
Set an icon that goes with the content of this notification.
public int
getContentIcon()
Deprecated: This method has no effect starting with Wear 2.0.
Get an icon that goes with the content of this notification.
Deprecated: This method has no effect starting with Wear 2.0.
Set the gravity that the content icon should have within the notification display.
Supported values include and
. The default value is .
See also: NotificationCompat.WearableExtender.setContentIcon(int)
public int
getContentIconGravity()
Deprecated: This method has no effect starting with Wear 2.0.
Get the gravity that the content icon should have within the notification display.
Supported values include and
. The default value is .
See also: NotificationCompat.WearableExtender.getContentIcon()
Set an action from this notification's actions as the primary action. If the action has a
RemoteInput associated with it, shortcuts to the options for that input are shown
directly on the notification.
Parameters:
actionIndex: The index of the primary action.
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 int
getContentAction()
Get the index of the notification action, if any, that was specified as the primary
action.
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:
the action index or NotificationCompat.WearableExtender.UNSET_ACTION_INDEX if no action was selected.
Deprecated: This method has no effect starting with Wear 2.0.
Set the gravity that this notification should have within the available viewport space.
Supported values include ,
and .
The default value is .
Deprecated: This method has no effect starting with Wear 2.0.
Get the gravity that this notification should have within the available viewport space.
Supported values include ,
and .
The default value is .
Deprecated: This method has no effect starting with Wear 2.0.
Set the custom size preset for the display of this notification out of the available
presets found in NotificationCompat.WearableExtender, e.g.
NotificationCompat.WearableExtender.SIZE_LARGE.
Some custom size presets are only applicable for custom display notifications created
using NotificationCompat.WearableExtender.setDisplayIntent(PendingIntent). Check the
documentation for the preset in question. See also
NotificationCompat.WearableExtender.setCustomContentHeight(int) and NotificationCompat.WearableExtender.getCustomSizePreset().
public int
getCustomSizePreset()
Deprecated: This method has no effect starting with Wear 2.0.
Get the custom size preset for the display of this notification out of the available
presets found in NotificationCompat.WearableExtender, e.g.
NotificationCompat.WearableExtender.SIZE_LARGE.
Some custom size presets are only applicable for custom display notifications created
using NotificationCompat.WearableExtender.setDisplayIntent(PendingIntent). Check the documentation for the preset in question.
See also NotificationCompat.WearableExtender.setCustomContentHeight(int) and NotificationCompat.WearableExtender.setCustomSizePreset(int).
Deprecated: This method has no effect starting with Wear 2.0.
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 NotificationCompat.WearableExtender.setDisplayIntent(PendingIntent). See also
NotificationCompat.WearableExtender.setCustomSizePreset(int) and
NotificationCompat.WearableExtender.getCustomContentHeight().
public int
getCustomContentHeight()
Deprecated: This method has no effect starting with Wear 2.0.
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 NotificationCompat.WearableExtender.setDisplayIntent(PendingIntent). See also NotificationCompat.WearableExtender.setCustomSizePreset(int) and
NotificationCompat.WearableExtender.setCustomContentHeight(int).
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).
public 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. Default is false (start scroll at the top).
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 boolean
getContentIntentAvailableOffline()
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.
Deprecated: This method has no effect starting with Wear 2.0.
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 boolean
getHintHideIcon()
Deprecated: This method has no effect starting with Wear 2.0.
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.
Deprecated: This method has no effect starting with Wear 2.0.
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 NotificationCompat.WearableExtender.addPage(Notification).
public boolean
getHintShowBackgroundOnly()
Deprecated: This method has no effect starting with Wear 2.0.
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 NotificationCompat.WearableExtender.addPage(Notification).
Deprecated: This method has no effect starting with Wear 2.0.
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 boolean
getHintAvoidBackgroundClipping()
Deprecated: This method has no effect starting with Wear 2.0.
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.
Deprecated: This method has no effect.
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
NotificationCompat.WearableExtender.SCREEN_TIMEOUT_SHORT or NotificationCompat.WearableExtender.SCREEN_TIMEOUT_LONG.
Returns:
this object for method chaining
public int
getHintScreenTimeout()
Deprecated: This method has no effect starting with Wear 2.0.
Get the duration, in milliseconds, that the screen should remain on for
when this notification is displayed.
Returns:
the duration in milliseconds if > 0, or either one of the sentinel values
NotificationCompat.WearableExtender.SCREEN_TIMEOUT_SHORT or NotificationCompat.WearableExtender.SCREEN_TIMEOUT_LONG.
Deprecated: This feature is no longer supported.
Set a hint that this notification's NotificationCompat.BigPictureStyle (if present) should be
converted to low-bit and displayed in ambient mode, especially useful for barcodes and
qr codes, as well as other simple black-and-white tickets.
Parameters:
hintAmbientBigPicture: true to enable converstion and ambient.
Returns:
this object for method chaining
public boolean
getHintAmbientBigPicture()
Deprecated: This feature is no longer supported.
Get a hint that this notification's NotificationCompat.BigPictureStyle (if present) should be
converted to low-bit and displayed in ambient mode, especially useful for barcodes and
qr codes, as well as other simple black-and-white tickets.
Returns:
true if it should be displayed in ambient, false otherwise
otherwise. The default value is false if this was never set.
Set a hint that this notification's content intent will launch an
directly, telling the platform that it can generate the appropriate transitions.
Parameters:
hintContentIntentLaunchesActivity: true if the content intent will launch
an activity and transitions should be generated, false otherwise.
Returns:
this object for method chaining
public boolean
getHintContentIntentLaunchesActivity()
Get a hint that this notification's content intent will launch an
directly, telling the platform that it can generate the appropriate transitions
Returns:
true if the content intent will launch an activity and transitions should
be generated, false otherwise. The default value is false if this was never set.
Sets the dismissal id for this notification. If a notification is posted with a
dismissal id, then when that notification is canceled, notifications on other wearables
and the paired Android phone having that same dismissal id will also be canceled. See
Adding Wearable Features to
Notifications for more information.
Parameters:
dismissalId: the dismissal id of the notification.
Returns:
this object for method chaining
public java.lang.String
getDismissalId()
Returns the dismissal id of the notification.
Returns:
the dismissal id of the notification or null if it has not been set.
Sets a bridge tag for this notification. A bridge tag can be set for notifications
posted from a phone to provide finer-grained control on what notifications are bridged
to wearables. See Adding Wearable
Features to Notifications for more information.
Parameters:
bridgeTag: the bridge tag of the notification.
Returns:
this object for method chaining
public java.lang.String
getBridgeTag()
Returns the bridge tag of the notification.
Returns:
the bridge tag or null if not present.