ConversationsBloc class
BLoC for managing conversations list
This BLoC manages the conversations list state and handles:
- Loading and pagination of conversations
- Real-time updates via SDK listeners (messages, users, groups, calls)
- Selection management
- Typing indicators
- User presence (online/offline)
- Read/delivery receipts
- Group member events
- Call events
- Connection state
This BLoC uses the ListBase mixin for list management operations. Developers can extend this class and override the hook methods (onItemAdded, onItemRemoved, onItemUpdated, onListCleared, onListReplaced) to add custom logic like sorting, filtering, or validation.
Example:
class CustomConversationsBloc extends ConversationsBloc {
@override
void onItemAdded(Conversation item, List<Conversation> updatedList) {
// Custom sorting logic
final sortedList = _sortWithPinnedFirst(updatedList);
super.onItemAdded(item, sortedList);
}
}
- Mixed-in types
Constructors
- ConversationsBloc({GetLoggedInUserUseCase? getLoggedInUserUseCase, GetConversationUseCase? getConversationUseCase, MarkAsDeliveredUseCase? markAsDeliveredUseCase, DeleteConversationUseCase? deleteConversationUseCase, GetConversationsUseCase? getConversationsUseCase, LoadMoreConversationsUseCase? loadMoreConversationsUseCase, bool disableSoundForMessages = false, String? customSoundForMessages, bool usersStatusVisibility = true, bool receiptsVisibility = true, bool includeBlockedUsers = false, int visibleItemThreshold = 30, bool disableSDKListeners = false, ConversationsRequestBuilder? conversationsRequestBuilder, ConversationsBuilderProtocol? conversationsProtocol})
- Creates a ConversationsBloc.
Properties
- conversationsProtocol → ConversationsBuilderProtocol?
-
Caller-provided builder protocol. If supplied, its
getRequestresult takes precedence over conversationsRequestBuilder.final - conversationsRequestBuilder → ConversationsRequestBuilder?
-
Caller-provided request builder. Its filter fields (tags, userTags,
groupTags, withTags, withUserAndGroupTags, includeBlockedUsers,
withBlockedInfo, conversationType, unread) are applied to the initial
fetch, pagination fetch, and the realtime-add predicate.
final
- customSoundForMessages → String?
-
final
- deleteConversationUseCase → DeleteConversationUseCase
-
final
- disableSDKListeners → bool
-
Whether to disable SDK listeners (for web platform where native SDK is unavailable)
final
- disableSoundForMessages → bool
-
final
- getConversationsUseCase → GetConversationsUseCase?
-
final
- getConversationUseCase → GetConversationUseCase
-
final
- getLoggedInUserUseCase → GetLoggedInUserUseCase
-
final
- hashCode → int
-
The hash code for this object.
no setterinherited
- includeBlockedUsers → bool
-
final
- isClosed → bool
-
Whether the bloc is closed.
no setterinherited
- isEmpty → bool
-
Returns true if the list is empty
no setterinherited
- isNotEmpty → bool
-
Returns true if the list is not empty
no setterinherited
- itemCount → int
-
Returns the number of items in the list
no setterinherited
-
items
→ List<
Conversation> -
Returns an unmodifiable view of the current items
no setterinherited
- loadMoreConversationsUseCase → LoadMoreConversationsUseCase?
-
final
- markAsDeliveredUseCase → MarkAsDeliveredUseCase
-
final
- receiptsVisibility → bool
-
final
- runtimeType → Type
-
A representation of the runtime type of the object.
no setterinherited
- state → ConversationsState
-
The current state.
no setterinherited
-
stream
→ Stream<
ConversationsState> -
The current stream of states.
no setterinherited
- usersStatusVisibility → bool
-
final
- visibleItemThreshold → int
-
Visible item threshold for lazy updates (user status updates skip items beyond this)
final
Methods
-
add(
ConversationsEvent event) → void -
Notifies the
Blocof a neweventwhich triggers all correspondingEventHandlerinstances.inherited -
addAllItems(
List< Conversation> itemsToAdd) → void -
Adds multiple items to the end of the list.
Calls onItemAdded hook for each item.
inherited
-
addAllItemsAtStart(
List< Conversation> itemsToAdd) → void -
Adds items at the beginning of the list.
inherited
-
addError(
Object error, [StackTrace? stackTrace]) → void -
Reports an
errorwhich triggersonErrorwith an optional StackTrace.inherited -
addItem(
Conversation item) → void -
Adds an item to the end of the list.
Calls onItemAdded hook after adding.
inherited
-
addUniqueItem(
Conversation item) → bool -
Adds an item only if it doesn't already exist in the list.
Returns true if item was added.
inherited
-
clearItems(
) → void -
Clears all items from the list.
inherited
-
close(
) → Future< void> -
Closes the
eventandstateStreams. This method should be called when aBlocis no longer needed. Once close is called,eventsthat are added will not be processed. In addition, if close is called whileeventsare still being processed, theBlocwill finish processing the pendingevents. -
containsItem(
Conversation item) → bool -
Checks if the list contains a specified item.
inherited
-
emit(
ConversationsState state) → void -
emitis only for internal use and should never be called directly outside of tests. TheEmitterinstance provided to eachEventHandlershould be used instead.inherited -
filterItems(
bool predicate(Conversation item)) → void -
Filters items based on a predicate.
Removes items that don't match the predicate.
inherited
-
findFirst(
bool predicate(Conversation item)) → Conversation? -
Finds the first item matching the predicate.
Returns null if no item matches.
inherited
-
findIndex(
bool predicate(Conversation item)) → int -
Finds the index of the first item matching the predicate.
Returns -1 if no item matches.
inherited
-
getItemAt(
int index) → Conversation? -
Retrieves an item at a specific index safely.
Returns null if index is out of bounds.
inherited
-
getTypingIndicators(
String conversationId) → List< TypingIndicator> - Get current typing indicators for a conversation (for initial value)
-
getTypingNotifier(
String conversationId) → ValueNotifier< List< TypingIndicator> > - Get or create a typing notifier for a specific conversation. Use this with ValueListenableBuilder in list items for isolated rebuilds. Returns a list of typing indicators (empty if no one is typing).
-
insertItemAt(
int index, Conversation newItem) → bool -
Inserts an item at a specific index.
Returns true if insertion was successful.
inherited
-
moveItem(
int fromIndex, int toIndex) → bool -
Moves an item from one index to another.
Returns true if move was successful.
inherited
-
noSuchMethod(
Invocation invocation) → dynamic -
Invoked when a nonexistent method or property is accessed.
inherited
-
on<
E extends Event> (EventHandler< E, ConversationsState> handler, {EventTransformer<E> ? transformer}) → void -
Register event handler for an event of type
E. There should only ever be one event handler per event typeE.inherited -
onChange(
Change< ConversationsState> change) → void -
Called whenever a
changeoccurs with the givenchange. Achangeoccurs when a newstateis emitted.onChangeis called before thestateof thecubitis updated.onChangeis a great spot to add logging/analytics for a specificcubit.inherited -
onError(
Object error, StackTrace stackTrace) → void -
Called whenever an
erroroccurs and notifiesBlocObserver.onError.inherited -
onEvent(
ConversationsEvent event) → void -
Called whenever an
eventisadded to theBloc. A great spot to add logging/analytics at the individualBloclevel.inherited -
onItemAdded(
Conversation item, List< Conversation> updatedList) → void -
Called when a conversation is added to the list.
override
-
onItemRemoved(
Conversation item, List< Conversation> updatedList) → void -
Called when a conversation is removed from the list.
override
-
onItemUpdated(
Conversation oldItem, Conversation newItem, List< Conversation> updatedList) → void -
Called when a conversation is updated in the list.
override
-
onListCleared(
List< Conversation> previousList) → void -
Called when the conversations list is cleared.
override
-
onListReplaced(
List< Conversation> previousList, List<Conversation> newList) → void -
Called when the entire conversations list is replaced.
This is the only case where full rebuild is necessary.
override
-
onTransition(
Transition< ConversationsEvent, ConversationsState> transition) → void -
Called whenever a
transitionoccurs with the giventransition. Atransitionoccurs when a neweventis added and a new state isemittedfrom a correspondingEventHandler.inherited -
removeIf(
bool predicate(Conversation item)) → void -
Removes items that match the predicate.
inherited
-
removeItem(
Conversation item) → bool -
Removes a specified item from the list.
Calls onItemRemoved hook after removing.
Returns true if item was found and removed.
inherited
-
removeItemAt(
int index) → Conversation? -
Removes an item at a specific index.
Returns the removed item, or null if index is out of bounds.
inherited
-
replaceAll(
List< Conversation> newItems) → void -
Replaces all items with a new list.
inherited
-
replaceFirst(
Conversation oldItem, Conversation newItem) → bool -
Replaces the first occurrence of an item with a new item.
Returns true if replacement was successful.
inherited
-
reverse(
) → void -
Reverses the order of items in the list.
inherited
-
swapItems(
int index1, int index2) → bool -
Swaps two items at the specified indices.
Returns true if swap was successful.
inherited
-
toString(
) → String -
A string representation of this object.
inherited
-
updateItem(
int index, Conversation newItem) → bool -
Updates an item at a specific index.
Returns true if update was successful.
inherited
-
updateItemWhere(
bool predicate(Conversation item), Conversation newItem) → bool -
Updates the first item matching the predicate.
Returns true if update was successful.
inherited
Operators
-
operator ==(
Object other) → bool -
The equality operator.
inherited