public static class Notification.Builder extends Object
Notification
objects.
Provides a convenient way to set the various fields of a Notification
and generate
content views using the platform's notification layout template. If your app supports
versions of Android as old as API level 4, you can instead use
NotificationCompat.Builder
,
available in the Android Support
library.
Example:
Notification noti = new Notification.Builder(mContext) .setContentTitle("New mail from " + sender.toString()) .setContentText(subject) .setSmallIcon(R.drawable.new_mail) .setLargeIcon(aBitmap) .build();
Modifier and Type | Field and Description |
---|---|
static String |
EXTRA_REBUILD_BIG_CONTENT_VIEW_ACTION_COUNT |
static String |
EXTRA_REBUILD_CONTENT_VIEW_ACTION_COUNT |
static String |
EXTRA_REBUILD_HEADS_UP_CONTENT_VIEW_ACTION_COUNT |
Constructor and Description | |||
---|---|---|---|
Builder(Context context)
Constructs a new Builder with the defaults:
priority
| Notification.PRIORITY_DEFAULT
when
now ( | System.currentTimeMillis() )
audio stream
| Notification.STREAM_DEFAULT
|
Builder(Context context,
Notification toAdopt) |
Modifier and Type | Method and Description |
---|---|
Notification.Builder |
addAction(int icon,
CharSequence title,
PendingIntent intent)
Deprecated.
Use
#addAction(Action) instead. |
Notification.Builder |
addAction(Notification.Action action)
Add an action to this notification.
|
Notification.Builder |
addExtras(Bundle extras)
Merge additional metadata into this notification.
|
Notification.Builder |
addPerson(String uri)
Add a person that is relevant to this notification.
|
Notification |
build()
Combine all of the options that have been set and return a new
Notification
object. |
Notification |
buildInto(Notification n)
Apply this Builder to an existing
Notification object. |
Notification |
buildUnstyled()
Apply the unstyled operations and return a new
Notification object. |
RemoteViews |
createBigContentView()
Construct a RemoteViews for the final big notification layout.
|
RemoteViews |
createContentView()
Construct a RemoteViews for the final 1U notification layout.
|
RemoteViews |
createHeadsUpContentView()
Construct a RemoteViews for the final heads-up notification layout.
|
Notification.Builder |
extend(Notification.Extender extender)
Apply an extender to this notification builder.
|
Bundle |
getExtras()
Get the current metadata Bundle used by this notification Builder.
|
Notification |
getNotification()
Deprecated.
Use
build() instead. |
String |
loadHeaderAppName() |
RemoteViews |
makeNotificationHeader()
Construct a RemoteViews for the final notification header only
|
RemoteViews |
makePublicContentView()
Construct a RemoteViews for the display in public contexts like on the lockscreen.
|
static Notification |
maybeCloneStrippedForDelivery(Notification n)
Removes RemoteViews that were created for compatibility from , if they did not
change.
|
static Notification.Builder |
recoverBuilder(Context context,
Notification n)
Creates a Builder from an existing notification so further changes can be made.
|
Notification.Builder |
setActions(Notification.Action... actions)
Alter the complete list of actions attached to this notification.
|
Notification.Builder |
setAutoCancel(boolean autoCancel)
Make this notification automatically dismissed when the user touches it.
|
Notification.Builder |
setCategory(String category)
Set the notification category.
|
Notification.Builder |
setChronometerCountDown(boolean countDown)
Sets the Chronometer to count down instead of counting up.
|
Notification.Builder |
setColor(int argb)
Sets
Notification.color . |
Notification.Builder |
setContent(RemoteViews views)
Deprecated.
|
Notification.Builder |
setContentInfo(CharSequence info)
Deprecated.
use
setSubText(CharSequence) instead to set a text in the header.
For legacy apps targeting a version below Build.VERSION_CODES.N this
field will still show up, but the subtext will take precedence. |
Notification.Builder |
setContentIntent(PendingIntent intent)
Supply a
PendingIntent to be sent when the notification is clicked. |
Notification.Builder |
setContentText(CharSequence text)
Set the second line of text in the platform notification template.
|
Notification.Builder |
setContentTitle(CharSequence title)
Set the first line of text in the platform notification template.
|
Notification.Builder |
setCustomBigContentView(RemoteViews contentView)
Supply custom RemoteViews to use instead of the platform template in the expanded form.
|
Notification.Builder |
setCustomContentView(RemoteViews contentView)
Supply custom RemoteViews to use instead of the platform template.
|
Notification.Builder |
setCustomHeadsUpContentView(RemoteViews contentView)
Supply custom RemoteViews to use instead of the platform template in the heads up dialog.
|
Notification.Builder |
setDefaults(int defaults)
Set which notification properties will be inherited from system defaults.
|
Notification.Builder |
setDeleteIntent(PendingIntent intent)
Supply a
PendingIntent to send when the notification is cleared explicitly by the user. |
Notification.Builder |
setExtras(Bundle extras)
Set metadata for this notification.
|
Notification.Builder |
setFlag(int mask,
boolean value) |
Notification.Builder |
setFullScreenIntent(PendingIntent intent,
boolean highPriority)
An intent to launch instead of posting the notification to the status bar.
|
Notification.Builder |
setGroup(String groupKey)
Set this notification to be part of a group of notifications sharing the same key.
|
Notification.Builder |
setGroupSummary(boolean isGroupSummary)
Set this notification to be the group summary for a group of notifications.
|
Notification.Builder |
setLargeIcon(Bitmap b)
Add a large icon to the notification content view.
|
Notification.Builder |
setLargeIcon(Icon icon)
Add a large icon to the notification content view.
|
Notification.Builder |
setLights(int argb,
int onMs,
int offMs)
Set the desired color for the indicator LED on the device, as well as the
blink duty cycle (specified in milliseconds).
|
Notification.Builder |
setLocalOnly(boolean localOnly)
Set whether or not this notification should not bridge to other devices.
|
Notification.Builder |
setNumber(int number)
Deprecated.
this number is not shown anywhere anymore
|
Notification.Builder |
setOngoing(boolean ongoing)
Set whether this is an "ongoing" notification.
|
Notification.Builder |
setOnlyAlertOnce(boolean onlyAlertOnce)
Set this flag if you would only like the sound, vibrate
and ticker to be played if the notification is not already showing.
|
Notification.Builder |
setPriority(int pri)
Set the priority of this notification.
|
Notification.Builder |
setProgress(int max,
int progress,
boolean indeterminate)
Set the progress this notification represents.
|
Notification.Builder |
setPublicVersion(Notification n)
Supply a replacement Notification whose contents should be shown in insecure contexts
(i.e. atop the secure lockscreen).
|
Notification.Builder |
setRemoteInputHistory(CharSequence[] text)
Set the remote input history.
|
Notification.Builder |
setShowWhen(boolean show)
Control whether the timestamp set with
setWhen is shown
in the content view. |
Notification.Builder |
setSmallIcon(Icon icon)
Set the small icon, which will be used to represent the notification in the
status bar and content view (unless overriden there by a
large icon ). |
Notification.Builder |
setSmallIcon(int icon)
Set the small icon resource, which will be used to represent the notification in the
status bar.
|
Notification.Builder |
setSmallIcon(int icon,
int level)
A variant of
setSmallIcon(int) that takes an additional
level parameter for when the icon is a LevelListDrawable . |
Notification.Builder |
setSortKey(String sortKey)
Set a sort key that orders this notification among other notifications from the
same package.
|
Notification.Builder |
setSound(Uri sound)
Set the sound to play.
|
Notification.Builder |
setSound(Uri sound,
AudioAttributes audioAttributes)
Set the sound to play, along with specific
audio attributes to
use during playback. |
Notification.Builder |
setSound(Uri sound,
int streamType)
Deprecated.
use
setSound(Uri, AudioAttributes) instead. |
Notification.Builder |
setStyle(Notification.Style style)
Add a rich notification style to be applied at build time.
|
Notification.Builder |
setSubText(CharSequence text)
This provides some additional information that is displayed in the notification.
|
Notification.Builder |
setTicker(CharSequence tickerText)
Set the "ticker" text which is sent to accessibility services.
|
Notification.Builder |
setTicker(CharSequence tickerText,
RemoteViews views)
Deprecated.
|
Notification.Builder |
setUsesChronometer(boolean b)
Show the
Notification.when field as a stopwatch. |
Notification.Builder |
setVibrate(long[] pattern)
Set the vibration pattern to use.
|
Notification.Builder |
setVisibility(int visibility)
Specify the value of
Notification.visibility . |
Notification.Builder |
setWhen(long when)
Add a timestamp pertaining to the notification (usually the time the event occurred).
|
public static final String EXTRA_REBUILD_CONTENT_VIEW_ACTION_COUNT
public static final String EXTRA_REBUILD_BIG_CONTENT_VIEW_ACTION_COUNT
public static final String EXTRA_REBUILD_HEADS_UP_CONTENT_VIEW_ACTION_COUNT
public Builder(Context context)
priority | Notification.PRIORITY_DEFAULT |
---|---|
when | now (System.currentTimeMillis() ) |
audio stream | Notification.STREAM_DEFAULT |
context
- A Context
that will be used by the Builder to construct the
RemoteViews. The Context will not be held past the lifetime of this Builder
object.public Builder(Context context, Notification toAdopt)
public Notification.Builder setWhen(long when)
Build.VERSION_CODES.N
and above, this time is not
shown anymore by default and must be opted into by using
setShowWhen(boolean)
Notification.when
public Notification.Builder setShowWhen(boolean show)
setWhen
is shown
in the content view.
For apps targeting Build.VERSION_CODES.N
and above, this defaults to
false
. For earlier apps, the default is true
.public Notification.Builder setUsesChronometer(boolean b)
Notification.when
field as a stopwatch.
Instead of presenting when
as a timestamp, the notification will show an
automatically updating display of the minutes and seconds since when
.
Useful when showing an elapsed time (like an ongoing phone call).
The counter can also be set to count down to when
when using
setChronometerCountDown(boolean)
.public Notification.Builder setChronometerCountDown(boolean countDown)
This is only relevant if setUsesChronometer(boolean)
has been set to true.
If it isn't set the chronometer will count up.
setUsesChronometer(boolean)
public Notification.Builder setSmallIcon(@DrawableRes int icon)
large icon
has also been specified, in which case the small
icon will be moved to the right-hand side.icon
- A resource ID in the application's package of the drawable to use.Notification.icon
public Notification.Builder setSmallIcon(@DrawableRes int icon, int level)
setSmallIcon(int)
that takes an additional
level parameter for when the icon is a LevelListDrawable
.icon
- A resource ID in the application's package of the drawable to use.level
- The level to use for the icon.Notification.icon
,
Notification.iconLevel
public Notification.Builder setSmallIcon(Icon icon)
large icon
).icon
- An Icon object to use.Notification.icon
public Notification.Builder setContentTitle(CharSequence title)
public Notification.Builder setContentText(CharSequence text)
public Notification.Builder setSubText(CharSequence text)
This information should only be provided if it provides an essential benefit to the understanding of the notification. The more text you provide the less readable it becomes. For example, an email client should only provide the account name here if more than one email account has been added.
As of Build.VERSION_CODES.N
this information is displayed in the
notification header area.
On Android versions before Build.VERSION_CODES.N
this will be shown in the third line of text in the platform notification template.
You should not be using setProgress(int, int, boolean)
at the
same time on those versions; they occupy the same place.
public Notification.Builder setRemoteInputHistory(CharSequence[] text)
RemoteInput
of this Notification and cleared once the it is no
longer relevant (e.g. for chat notifications once the other party has responded).
The most recent input must be stored at the 0 index, the second most recent at the
1 index, etc. Note that the system will limit both how far back the inputs will be shown
and how much of each individual input is shown.
Note: The reply text will only be shown on notifications that have least one action
with a RemoteInput
.
public Notification.Builder setNumber(int number)
public Notification.Builder setContentInfo(CharSequence info)
setSubText(CharSequence)
instead to set a text in the header.
For legacy apps targeting a version below Build.VERSION_CODES.N
this
field will still show up, but the subtext will take precedence.public Notification.Builder setProgress(int max, int progress, boolean indeterminate)
ProgressBar
.@Deprecated public Notification.Builder setContent(RemoteViews views)
setCustomContentView(RemoteViews)
instead.public Notification.Builder setCustomContentView(RemoteViews contentView)
public Notification.Builder setCustomBigContentView(RemoteViews contentView)
public Notification.Builder setCustomHeadsUpContentView(RemoteViews contentView)
public Notification.Builder setContentIntent(PendingIntent intent)
PendingIntent
to be sent when the notification is clicked.
As of Build.VERSION_CODES.HONEYCOMB
, if this field is unset and you
have specified a custom RemoteViews with setContent(RemoteViews)
, you can use
RemoteViews.setOnClickPendingIntent(int,PendingIntent)
to assign PendingIntents to individual views in that custom layout (i.e., to create
clickable buttons inside the notification view).Notification.contentIntent
public Notification.Builder setDeleteIntent(PendingIntent intent)
PendingIntent
to send when the notification is cleared explicitly by the user.Notification.deleteIntent
public Notification.Builder setFullScreenIntent(PendingIntent intent, boolean highPriority)
The system UI may choose to display a heads-up notification, instead of launching this intent, while the user is using the device.
intent
- The pending intent to launch.highPriority
- Passing true will cause this notification to be sent
even if other notifications are suppressed.Notification.fullScreenIntent
public Notification.Builder setTicker(CharSequence tickerText)
Notification.tickerText
@Deprecated public Notification.Builder setTicker(CharSequence tickerText, RemoteViews views)
setTicker(CharSequence)
.public Notification.Builder setLargeIcon(Bitmap b)
small icon
(which will be placed in a small
badge atop the large icon).public Notification.Builder setLargeIcon(Icon icon)
small icon
(which will be placed in a small
badge atop the large icon).public Notification.Builder setSound(Uri sound)
default audio attributes
for notifications.
A notification that is noisy is more likely to be presented as a heads-up notification.
Notification.sound
@Deprecated public Notification.Builder setSound(Uri sound, int streamType)
setSound(Uri, AudioAttributes)
instead.AudioManager
for the STREAM_
constants.
A notification that is noisy is more likely to be presented as a heads-up notification.
Notification.sound
public Notification.Builder setSound(Uri sound, AudioAttributes audioAttributes)
audio attributes
to
use during playback.
A notification that is noisy is more likely to be presented as a heads-up notification.
Notification.sound
public Notification.Builder setVibrate(long[] pattern)
Vibrator.vibrate(long[], int)
for a discussion of the
pattern
parameter.
A notification that vibrates is more likely to be presented as a heads-up notification.
Notification.vibrate
public Notification.Builder setLights(int argb, int onMs, int offMs)
public Notification.Builder setOngoing(boolean ongoing)
public Notification.Builder setOnlyAlertOnce(boolean onlyAlertOnce)
Notification.FLAG_ONLY_ALERT_ONCE
public Notification.Builder setAutoCancel(boolean autoCancel)
setDeleteIntent(android.app.PendingIntent)
will be sent when this happens.Notification.FLAG_AUTO_CANCEL
public Notification.Builder setLocalOnly(boolean localOnly)
Some notifications can be bridged to other devices for remote display. This hint can be set to recommend this notification not be bridged.
public Notification.Builder setDefaults(int defaults)
The value should be one or more of the following fields combined with
bitwise-or:
Notification.DEFAULT_SOUND
, Notification.DEFAULT_VIBRATE
, Notification.DEFAULT_LIGHTS
.
For all default values, use Notification.DEFAULT_ALL
.
public Notification.Builder setPriority(int pri)
Notification.priority
public Notification.Builder setCategory(String category)
Notification.category
public Notification.Builder addPerson(String uri)
Depending on user preferences, this annotation may allow the notification to pass through interruption filters, and to appear more prominently in the user interface.
The person should be specified by the String
representation of a
ContactsContract.Contacts.CONTENT_LOOKUP_URI
.
The system will also attempt to resolve mailto:
and tel:
schema
URIs. The path part of these URIs must exist in the contacts database, in the
appropriate column, or the reference will be discarded as invalid. Telephone schema
URIs will be resolved by ContactsContract.PhoneLookup
.
uri
- A URI for the person.Notification.EXTRA_PEOPLE
public Notification.Builder setGroup(String groupKey)
To make this notification the summary for its group, also call
setGroupSummary(boolean)
. A sort order can be specified for group members by using
setSortKey(java.lang.String)
.
groupKey
- The group key of the group.public Notification.Builder setGroupSummary(boolean isGroupSummary)
setGroup(java.lang.String)
.isGroupSummary
- Whether this notification should be a group summary.public Notification.Builder setSortKey(String sortKey)
This sort key can also be used to order members of a notification group. See
setGroup(java.lang.String)
.
String.compareTo(String)
public Notification.Builder addExtras(Bundle extras)
Values within the Bundle will replace existing extras values in this Builder.
Notification.extras
public Notification.Builder setExtras(Bundle extras)
A reference to the Bundle is held for the lifetime of this Builder, and the Bundle's
current contents are copied into the Notification each time build()
is
called.
Replaces any existing extras values with those from the provided Bundle.
Use addExtras(android.os.Bundle)
to merge in metadata instead.
Notification.extras
public Bundle getExtras()
The returned Bundle is shared with this Builder.
The current contents of this Bundle are copied into the Notification each time
build()
is called.
Notification.extras
@Deprecated public Notification.Builder addAction(int icon, CharSequence title, PendingIntent intent)
#addAction(Action)
instead.
Every action must have an icon (32dp square and matching the
Holo
Dark action bar visual style), a textual label, and a PendingIntent
.
A notification in its expanded form can display up to 3 actions, from left to right in
the order they were added. Actions will not be displayed when the notification is
collapsed, however, so be sure that any essential functions may be accessed by the user
in some other way (for example, in the Activity pointed to by Notification.contentIntent
).
icon
- Resource ID of a drawable that represents the action.title
- Text describing the action.intent
- PendingIntent to be fired when the action is invoked.public Notification.Builder addAction(Notification.Action action)
Every action must have an icon (32dp square and matching the
Holo
Dark action bar visual style), a textual label, and a PendingIntent
.
A notification in its expanded form can display up to 3 actions, from left to right in
the order they were added. Actions will not be displayed when the notification is
collapsed, however, so be sure that any essential functions may be accessed by the user
in some other way (for example, in the Activity pointed to by Notification.contentIntent
).
action
- The action to add.public Notification.Builder setActions(Notification.Action... actions)
actions
- #addAction(Action).
public Notification.Builder setStyle(Notification.Style style)
style
- Object responsible for modifying the notification style.public Notification.Builder setVisibility(int visibility)
Notification.visibility
.visibility
- One of Notification.VISIBILITY_PRIVATE
(the default),
Notification.VISIBILITY_SECRET
, or Notification.VISIBILITY_PUBLIC
.public Notification.Builder setPublicVersion(Notification n)
Notification.visibility
and Notification.VISIBILITY_PUBLIC
.n
- A replacement notification, presumably with some or all info redacted.public Notification.Builder extend(Notification.Extender extender)
public Notification.Builder setFlag(int mask, boolean value)
public Notification.Builder setColor(int argb)
Notification.color
.argb
- The accent color to usepublic String loadHeaderAppName()
public RemoteViews createContentView()
public RemoteViews createBigContentView()
public RemoteViews makeNotificationHeader()
public RemoteViews createHeadsUpContentView()
public RemoteViews makePublicContentView()
public Notification buildUnstyled()
Notification
object.public static Notification.Builder recoverBuilder(Context context, Notification n)
context
- The context for your application / activity.n
- The notification to create a Builder from.@Deprecated public Notification getNotification()
build()
instead.public Notification build()
Notification
object.public Notification buildInto(Notification n)
Notification
object.public static Notification maybeCloneStrippedForDelivery(Notification n)