MessagingStyle
open class MessagingStyle : Notification.Style
kotlin.Any | ||
↳ | android.app.Notification.Style | |
↳ | android.app.Notification.MessagingStyle |
Helper class for generating large-format notifications that include multiple back-and-forth messages of varying types between any number of people.
If the platform does not provide large-format notifications, this method has no effect. The user will always see the normal notification view.
If the app is targeting Android android.os.Build.VERSION_CODES#P
and above, it is required to use the Person
class in order to get an optimal rendering of the notification and its avatars. For conversations involving multiple people, the app should also make sure that it marks the conversation as a group with setGroupConversation(boolean)
.
From Android android.os.Build.VERSION_CODES#UPSIDE_DOWN_CAKE
, messaging style notifications that are associated with a valid conversation shortcut (via Notification.Builder#setShortcutId(String)
) are displayed in a dedicated conversation section in the shade above non-conversation alerting and silence notifications. To be a valid conversation shortcut, the shortcut must be a ShortcutInfo.Builder#setLongLived(boolean)
dynamic or cached sharing shortcut.
This class is a "rebuilder": It attaches to a Builder object and modifies its behavior. Here's an example of how this may be used:
Person user = new Person.Builder().setIcon(userIcon).setName(userName).build(); MessagingStyle style = new MessagingStyle(user) .addMessage(messages[1].getText(), messages[1].getTime(), messages[1].getPerson()) .addMessage(messages[2].getText(), messages[2].getTime(), messages[2].getPerson()) .setGroupConversation(hasMultiplePeople()); Notification noti = new Notification.Builder() .setContentTitle("2 new messages with " + sender.toString()) .setContentText(subject) .setSmallIcon(R.drawable.new_message) .setLargeIcon(aBitmap) .setStyle(style) .build();
Summary
Nested classes | |
---|---|
Constants | |
---|---|
static Int |
The maximum number of messages that will be retained in the Notification itself (the number displayed is up to the platform). |
Public constructors | |
---|---|
MessagingStyle(userDisplayName: CharSequence) |
|
MessagingStyle(user: Person) |
Public methods | |
---|---|
open Notification.MessagingStyle! |
Adds a |
open Notification.MessagingStyle! |
addMessage(text: CharSequence!, timestamp: Long, sender: CharSequence!) Adds a message for display by this notification. |
open Notification.MessagingStyle! |
addMessage(text: CharSequence, timestamp: Long, sender: Person?) Adds a message for display by this notification. |
open Notification.MessagingStyle! |
addMessage(message: Notification.MessagingStyle.Message!) Adds a |
open CharSequence? |
Return the title to be displayed on this conversation. |
open MutableList<Notification.MessagingStyle.Message!>! |
Gets the list of historic |
open MutableList<Notification.MessagingStyle.Message!>! |
Gets the list of |
open Person |
getUser() |
open CharSequence! |
Returns the name to be displayed for any replies sent by the user |
open Boolean |
Returns |
open Notification.MessagingStyle! |
setConversationTitle(conversationTitle: CharSequence?) Sets the title to be displayed on this conversation. |
open Notification.MessagingStyle! |
setGroupConversation(isGroupConversation: Boolean) Sets whether this conversation notification represents a group. |
Inherited functions | |
---|---|
Inherited properties | |
---|---|
Constants
MAXIMUM_RETAINED_MESSAGES
static val MAXIMUM_RETAINED_MESSAGES: Int
The maximum number of messages that will be retained in the Notification itself (the number displayed is up to the platform).
Value: 25
Public constructors
MessagingStyle
MessagingStyle(userDisplayName: CharSequence)
Deprecated: use MessagingStyle(Person)
Parameters | |
---|---|
userDisplayName |
CharSequence: Required - the name to be displayed for any replies sent by the user before the posting app reposts the notification with those messages after they've been actually sent and in previous messages sent by the user added in addMessage(android.app.Notification.MessagingStyle.Message) This value cannot be null . |
MessagingStyle
MessagingStyle(user: Person)
Parameters | |
---|---|
user |
Person: Required - The person displayed for any messages that are sent by the user. Any messages added with addMessage(android.app.Notification.MessagingStyle.Message) who don't have a Person associated with it will be displayed as if they were sent by this user. The user also needs to have a valid name associated with it, which is enforced starting in Android android.os.Build.VERSION_CODES#P . This value cannot be null . |
Public methods
addHistoricMessage
open fun addHistoricMessage(message: Notification.MessagingStyle.Message!): Notification.MessagingStyle!
Adds a Message
for historic context in this notification.
Messages should be added as historic if they are not the main subject of the notification but may give context to a conversation. The system may choose to present them only when relevant, e.g. when replying to a message through a RemoteInput
.
The messages should be added in chronologic order, i.e. the oldest first, the newest last.
Parameters | |
---|---|
message |
Notification.MessagingStyle.Message!: The historic Message to be added |
Return | |
---|---|
Notification.MessagingStyle! |
this object for method chaining |
addMessage
open funaddMessage(
text: CharSequence!,
timestamp: Long,
sender: CharSequence!
): Notification.MessagingStyle!
Deprecated: use addMessage(java.lang.CharSequence,long,android.app.Person)
Adds a message for display by this notification. Convenience call for a simple Message
in addMessage(android.app.Notification.MessagingStyle.Message)
.
Parameters | |
---|---|
text |
CharSequence!: A CharSequence to be displayed as the message content |
timestamp |
Long: Time in milliseconds at which the message arrived |
sender |
CharSequence!: A CharSequence to be used for displaying the name of the sender. Should be null for messages by the current user, in which case the platform will insert getUserDisplayName() . Should be unique amongst all individuals in the conversation, and should be consistent during re-posts of the notification. |
Return | |
---|---|
Notification.MessagingStyle! |
this object for method chaining |
addMessage
open fun addMessage(
text: CharSequence,
timestamp: Long,
sender: Person?
): Notification.MessagingStyle!
Adds a message for display by this notification. Convenience call for a simple Message
in addMessage(android.app.Notification.MessagingStyle.Message)
.
Parameters | |
---|---|
text |
CharSequence: A CharSequence to be displayed as the message content This value cannot be null . |
timestamp |
Long: Time in milliseconds at which the message arrived |
sender |
Person?: The Person who sent the message. Should be null for messages by the current user, in which case the platform will insert the user set in MessagingStyle(Person) . |
Return | |
---|---|
Notification.MessagingStyle! |
this object for method chaining |
addMessage
open fun addMessage(message: Notification.MessagingStyle.Message!): Notification.MessagingStyle!
Adds a Message
for display in this notification.
The messages should be added in chronologic order, i.e. the oldest first, the newest last.
Multiple Messages in a row with the same timestamp and sender may be grouped as a single message. This means an app should represent a message that has both an image and text as two Message objects, one with the image (and fallback text), and the other with the message text. For consistency, a text message (if any) should be provided after Uri content.
Parameters | |
---|---|
message |
Notification.MessagingStyle.Message!: The Message to be displayed |
Return | |
---|---|
Notification.MessagingStyle! |
this object for method chaining |
getConversationTitle
open fun getConversationTitle(): CharSequence?
Return the title to be displayed on this conversation. May return null
.
getHistoricMessages
open fun getHistoricMessages(): MutableList<Notification.MessagingStyle.Message!>!
Gets the list of historic Message
s in the notification.
getMessages
open fun getMessages(): MutableList<Notification.MessagingStyle.Message!>!
Gets the list of Message
objects that represent the notification.
getUser
open fun getUser(): Person
Return | |
---|---|
Person |
the user to be displayed for any replies sent by the user This value cannot be null . |
getUserDisplayName
open fungetUserDisplayName(): CharSequence!
Deprecated: use getUser()
instead
Returns the name to be displayed for any replies sent by the user
isGroupConversation
open fun isGroupConversation(): Boolean
Returns true
if this notification represents a group conversation, otherwise false
.
If the application that generated this MessagingStyle
targets an SDK version less than Build.VERSION_CODES#P
, this method becomes dependent on whether or not the conversation title is set; returning true
if the conversation title is a non-null value, or false
otherwise. From Build.VERSION_CODES#P
forward, this method returns what's set by setGroupConversation(boolean)
allowing for named, non-group conversations.
See Also
setConversationTitle
open fun setConversationTitle(conversationTitle: CharSequence?): Notification.MessagingStyle!
Sets the title to be displayed on this conversation. May be set to null
.
Starting in Build.VERSION_CODES#R
, this conversation title will be ignored if a valid shortcutId is added via Notification.Builder#setShortcutId(String)
. In this case, ShortcutInfo#getLongLabel()
(or, if missing, ShortcutInfo#getShortLabel()
) will be shown as the conversation title instead.
This API's behavior was changed in SDK version Build.VERSION_CODES#P
. If your application's target version is less than Build.VERSION_CODES#P
, setting a conversation title to a non-null value will make isGroupConversation()
return true
and passing null
will make it return false
. In Build.VERSION_CODES#P
and beyond, use setGroupConversation(boolean)
to set group conversation status.
Parameters | |
---|---|
conversationTitle |
CharSequence?: Title displayed for this conversation This value may be null . |
Return | |
---|---|
Notification.MessagingStyle! |
this object for method chaining |
setGroupConversation
open fun setGroupConversation(isGroupConversation: Boolean): Notification.MessagingStyle!
Sets whether this conversation notification represents a group. If the app is targeting Android P, this is required if the app wants to display the largeIcon set with Notification.Builder#setLargeIcon(Bitmap)
, otherwise it will be hidden.
Parameters | |
---|---|
isGroupConversation |
Boolean: true if the conversation represents a group, false otherwise. |
Return | |
---|---|
Notification.MessagingStyle! |
this object for method chaining |