stream-chat-android-ui-common/io.getstream.chat.android.ui.common.feature.messages.list/MessageListController

MessageListController

class MessageListController(cid: String, clipboardHandler: ClipboardHandler, val threadLoadOrderOlderToNewer: Boolean, messageId: String? = null, parentMessageId: String? = null, val messageLimit: Int = DEFAULT_MESSAGES_LIMIT, chatClient: ChatClient = ChatClient.instance(), clientState: ClientState = chatClient.clientState, val channelState: StateFlow<ChannelState?>, deletedMessageVisibility: DeletedMessageVisibility = DeletedMessageVisibility.ALWAYS_VISIBLE, showSystemMessages: Boolean = true, messageFooterVisibility: MessageFooterVisibility = MessageFooterVisibility.WithTimeDifference(), enforceUniqueReactions: Boolean = true, dateSeparatorHandler: DateSeparatorHandler = DateSeparatorHandler.getDefaultDateSeparatorHandler(), threadDateSeparatorHandler: DateSeparatorHandler = DateSeparatorHandler.getDefaultThreadDateSeparatorHandler(), messagePositionHandler: MessagePositionHandler = MessagePositionHandler.defaultHandler(), showDateSeparatorInEmptyThread: Boolean = false, showThreadSeparatorInEmptyThread: Boolean = false)

Controller responsible for handling message list state. It acts as a central place for core business logic and state required to show the message list, message thread and handling message actions.

Parameters

cid

The channel id in the format messaging:123.

clipboardHandler

ClipboardHandler used to copy messages.

threadLoadOrderOlderToNewer

Determines the order in which the thread messages are loaded.

messageId

The message id to which we want to scroll to when opening the message list.

parentMessageId

The ID of the parent Message if the message we want to scroll to is in a thread. If the message we want to scroll to is not in a thread, you can pass in a null value.

messageLimit

The limit of messages being fetched with each page od data.

chatClient

The client used to communicate with the API.

clientState

The current state of the SDK.

channelState

The state of the channel.

deletedMessageVisibility

The DeletedMessageVisibility to be applied to the list.

showSystemMessages

Determines if the system messages should be shown or not.

messageFooterVisibility

Determines if and when the message footer is visible or not.

enforceUniqueReactions

Determines whether the user can send only a single or multiple reactions to a message. If it is true the new reaction will override the old reaction.

dateSeparatorHandler

Determines the visibility of date separators inside the message list.

threadDateSeparatorHandler

Determines the visibility of date separators inside the thread.

messagePositionHandler

Determines the position of the message inside a group.

showDateSeparatorInEmptyThread

Configures if we show a date separator when threads are empty. Adds the separator item when the value is true.

showThreadSeparatorInEmptyThread

Configures if we show a thread separator when threads are empty or not. Adds the separator item when the value is true.

Constructors

MessageListController

constructor(cid: String, clipboardHandler: ClipboardHandler, threadLoadOrderOlderToNewer: Boolean, messageId: String? = null, parentMessageId: String? = null, messageLimit: Int = DEFAULT_MESSAGES_LIMIT, chatClient: ChatClient = ChatClient.instance(), clientState: ClientState = chatClient.clientState, channelState: StateFlow<ChannelState?>, deletedMessageVisibility: DeletedMessageVisibility = DeletedMessageVisibility.ALWAYS_VISIBLE, showSystemMessages: Boolean = true, messageFooterVisibility: MessageFooterVisibility = MessageFooterVisibility.WithTimeDifference(), enforceUniqueReactions: Boolean = true, dateSeparatorHandler: DateSeparatorHandler = DateSeparatorHandler.getDefaultDateSeparatorHandler(), threadDateSeparatorHandler: DateSeparatorHandler = DateSeparatorHandler.getDefaultThreadDateSeparatorHandler(), messagePositionHandler: MessagePositionHandler = MessagePositionHandler.defaultHandler(), showDateSeparatorInEmptyThread: Boolean = false, showThreadSeparatorInEmptyThread: Boolean = false)

Types

Companion

object Companion

ErrorEvent

sealed class ErrorEvent

A class designed for error event propagation.

UnreadLabel

data class UnreadLabel(val unreadCount: Int, val lastReadMessageId: String, val buttonVisibility: Boolean)

Properties

channel

val channel: StateFlow<Channel>

The information for the current Channel.

channelState

val channelState: StateFlow<ChannelState?>

connectionState

val connectionState: StateFlow<ConnectionState>

Gives us information about the online state of the device.

deletedMessageVisibilityState

val deletedMessageVisibilityState: StateFlow<DeletedMessageVisibility>

errorEvents

val errorEvents: StateFlow<MessageListController.ErrorEvent?>

isInsideSearch

val isInsideSearch: StateFlow<Boolean>

Whether the user is inside search or not.

isInThread

val isInThread: Boolean

Gives us information if we're currently in the MessageMode.MessageThread mode.

listState

val listState: StateFlow<MessageListState>

Current state of the message list depending on the MessageMode the list is in.

messageActions

val messageActions: StateFlow<Set<MessageAction>>

messageFooterVisibilityState

val messageFooterVisibilityState: StateFlow<MessageFooterVisibility>

messageLimit

val messageLimit: Int

messageListState

val messageListState: StateFlow<MessageListState>

mode

val mode: StateFlow<MessageMode>

ownCapabilities

val ownCapabilities: StateFlow<Set<String>>

Holds information about the abilities the current user is able to exercise in the given channel.

pollState

val pollState: StateFlow<PollState>

showSystemMessagesState

val showSystemMessagesState: StateFlow<Boolean>

threadListState

val threadListState: StateFlow<MessageListState>

threadLoadOrderOlderToNewer

val threadLoadOrderOlderToNewer: Boolean

typingUsers

val typingUsers: StateFlow<List<User>>

The list of typing users.

unreadCount

val unreadCount: StateFlow<Int>

unreadLabelState

val unreadLabelState: MutableStateFlow<MessageListController.UnreadLabel?>

Holds information about the unread label state.

user

val user: StateFlow<User?>

Gives us information about the logged in user state.

Functions

addPollOption

fun addPollOption(poll: Poll, option: String)

banUser

fun banUser(userId: String, reason: String? = null, timeout: Int? = null)

Bans the given user inside this channel.

blockUser

fun blockUser(userId: String)

Block a user. Unlike ban the block is not channel related but rather directly to the user.

castAnswer

fun castAnswer(messageId: String, pollId: String, answer: String)

Cast an answer for a poll in a message.

castVote

fun castVote(messageId: String, pollId: String, option: Option)

Cast a vote for a poll in a message.

clearNewMessageState

fun clearNewMessageState()

Clears the new messages state and drops the unread count to 0 after the user scrolls to the newest message.

closePoll

fun closePoll(poll: Poll)

Closes the given poll.

fun closePoll(pollId: String)

Close a poll in a message.

deleteMessage

fun deleteMessage(message: Message, hard: Boolean = false)

Deletes the given message.

disableUnreadLabelButton

fun disableUnreadLabelButton()

Disable the unread label button.

dismissAllMessageActions

fun dismissAllMessageActions()

Dismisses all message actions, when we cancel them in the rest of the UI.

dismissMessageAction

fun dismissMessageAction(messageAction: MessageAction)

Used to dismiss a specific message action, such as delete, reply, edit or something similar.

displayPollMoreOptions

fun displayPollMoreOptions(selectedPoll: SelectedPoll?)

Triggered when the user taps the show more options button on the poll message.

enterNormalMode

fun enterNormalMode()

Leaves the thread we're in and switches to MessageMode.Normal.

enterThreadMode

suspend fun enterThreadMode(parentMessage: Message, messageLimit: Int = this.messageLimit)

Changes the current _mode to be MessageMode.MessageThread and uses ChatClient to get the ThreadState for the current thread.

flagMessage

fun flagMessage(message: Message, reason: String?, customData: Map<String, String>, onResult: (Result<Flag>) -> Unit = {})

Flags the selected message.

flagUser

fun flagUser(userId: String, reason: String? = null, customData: Map<String, String> = emptyMap())

Flags a user identified by the provided ID.

getMessageFromListStateById

fun getMessageFromListStateById(messageId: String): Message?

Gets the message if it is inside the list.

loadMessageById

fun loadMessageById(messageId: String, onResult: (Result<Message>) -> Unit = {})

Loads a given Message with a single page around it.

loadNewerMessages

fun loadNewerMessages(baseMessageId: String, messageLimit: Int = this.messageLimit)

Loads newer messages of a channel following the currently newest loaded message. In case of threads this will do nothing.

loadOlderMessages

fun loadOlderMessages(messageLimit: Int = this.messageLimit)

Loads more messages if we have reached the oldest message currently loaded.

markLastMessageRead

fun markLastMessageRead()

Marks that the last message in the list as read. This also sets the unread count to 0.

markUnread

fun markUnread(message: Message, onResult: (Result<Unit>) -> Unit = {})

Marks the selected message as unread.

muteUser

fun muteUser(user: User)

Mutes the given user.

fun muteUser(userId: String, timeout: Int? = null)

Mutes the given user inside this channel.

onCleared

fun onCleared()

Cancels any pending work when the parent ViewModel is about to be destroyed.

openRelatedThread

suspend fun openRelatedThread(message: Message)

Open the thread for the given message. If the message is a thread start, it will open the thread. If the message is a reply, it will open the thread for the parent message.

performGiphyAction

fun performGiphyAction(action: GiphyAction)

Executes one of the actions for the given ephemeral giphy message.

performMessageAction

suspend fun performMessageAction(messageAction: MessageAction)

Triggered when the user selects a new message action, in the message overlay.

pinMessage

@JvmOverloads

fun pinMessage(message: Message, expiresAt: Date? = null)

Pins the message from the current channel.

reactToMessage

fun reactToMessage(reaction: Reaction, message: Message)

Triggered when the user selects a reaction for the currently selected message. If the message already has that reaction, from the current user, we remove it. Otherwise we add a new reaction.

removeAttachment

fun removeAttachment(messageId: String, attachmentToBeDeleted: Attachment)

Removes a single Attachment from a Message.

removeOverlay

fun removeOverlay()

Resets the MessagesStates, to remove the message overlay, by setting 'selectedMessageState' to null.

removeShadowBanFromUser

fun removeShadowBanFromUser(userId: String)

Removes the shadow ban for the given user inside this channel.

removeVote

fun removeVote(messageId: String, pollId: String, vote: Vote)

Remove a vote for a poll in a message.

resendMessage

fun resendMessage(message: Message)

Resends a failed message.

scrollToBottom

fun scrollToBottom(messageLimit: Int = this.messageLimit, scrollToBottom: () -> Unit)

When the user clicks the scroll to bottom button we need to take the user to the bottom of the newest messages. If the messages are not loaded we need to load them first and then scroll to the bottom of the list.

scrollToFirstUnreadMessage

fun scrollToFirstUnreadMessage()

Scrolls to the first unread message in the channel.

scrollToMessage

fun scrollToMessage(messageId: String, parentMessageId: String?)

Scrolls to the selected message. If the message is not currently in the list it will first load a page with the message in the middle of it, add it to the list and then notify to scroll to the message.

selectExtendedReactions

fun selectExtendedReactions(message: Message?)

Triggered when the user taps the show more reactions button.

selectMessage

fun selectMessage(message: Message?)

Triggered when the user long taps on and selects a message.

selectReactions

fun selectReactions(message: Message?)

Triggered when the user taps on and selects message reactions.

setDateSeparatorHandler

fun setDateSeparatorHandler(dateSeparatorHandler: DateSeparatorHandler?)

Sets the date separator handler which determines when to add date separators. By default, a date separator will be added if the difference between two messages' dates is greater than 4h.

setDeletedMessageVisibility

fun setDeletedMessageVisibility(deletedMessageVisibility: DeletedMessageVisibility)

Sets the value used to filter deleted messages.

setMessageFooterVisibility

fun setMessageFooterVisibility(messageFooterVisibility: MessageFooterVisibility)

Sets the value used to determine if message footer content is shown.

setMessagePositionHandler

fun setMessagePositionHandler(messagePositionHandler: MessagePositionHandler)

Sets the MessagePositionHandler that determines the message position inside a group.

setSystemMessageVisibility

fun setSystemMessageVisibility(areSystemMessagesVisible: Boolean)

Sets whether the system messages should be visible.