dandri/simplex-chat
1
0
Fork 0
mirror of https://github.com/simplex-chat/simplex-chat.git synced 2026-04-01 09:36:10 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
master-android
simplex-chat/apps/multiplatform/spec/client/chat-view.md
spaced4ndy a09acda329 multiplatform: product specification (#6655)
2026-02-26 17:54:44 +00:00

16 KiB
Raw Permalink Blame History

Chat View Specification

Source: common/src/commonMain/kotlin/chat/simplex/common/views/chat/ChatView.kt

Table of Contents

  1. Overview
  2. ChatView Composable
  3. Message List
  4. ChatItemView
  5. Message Types
  6. Context Menu Actions
  7. ChatInfoView
  8. GroupChatInfoView
  9. Source Files

Executive Summary

The Chat View is the primary message display and interaction surface in SimpleX Chat. It is built around the ChatView composable (line ~96 in ChatView.kt), which orchestrates a ChatLayout containing a reverse-scrolling LazyColumn of ChatItemView items and a ComposeView for message input. The view supports direct chats, group chats, local notes, and contact connections, with per-chat theming, search/filter, multi-select, and side-panel info modals. Message rendering is delegated to type-specific composables in the views/chat/item/ package.

1. Overview

ChatView
|-- ChatLayout
|   |-- ChatInfoToolbar            (top/bottom app bar with back, title, call, search, menu)
|   |-- SupportChatsCountToolbar   (reports/support banner, group only)
|   |-- ChatItemsList              (LazyColumnWithScrollBar, reverse layout)
|   |   |-- ChatViewListItem
|   |   |   |-- DateSeparator
|   |   |   |-- MemberNameAndRole  (group received messages)
|   |   |   |-- MemberImage        (group received messages)
|   |   |   +-- ChatItemView       (message type routing)
|   |   |-- ChatBannerView         (first item: chat profile banner)
|   |   +-- FloatingButtons        (scroll-to-bottom, unread counter)
|   |-- ComposeView               (message composition area)
|   |   |-- ContextItemView        (reply/edit/forward/report indicator)
|   |   |-- previewView            (link/media/voice/file preview)
|   |   +-- SendMsgView            (text input + send/voice/timed buttons)
|   |-- GroupMentions              (mention autocomplete popup)
|   |-- CommandsMenuView           (bot commands popup)
|   +-- ChooseAttachmentView       (bottom sheet for attachment type)
|-- ChatInfoView                   (contact info, end modal)
+-- GroupChatInfoView              (group management, end modal)

2. ChatView Composable

Location: ChatView.kt#L97

fun ChatView(
  chatsCtx: ChatModel.ChatsContext,
  staleChatId: State<String?>,
  scrollToItemId: MutableState<Long?>,
  onComposed: suspend (chatId: String) -> Unit
)

State Management

State Variable Type Purpose
showSearch MutableState<Boolean> Controls search bar visibility
searchText MutableState<String> Current search query text
composeState MutableState<ComposeState> Full compose area state (message, preview, context, mentions)
attachmentOption MutableState<AttachmentOption?> Selected attachment type from bottom sheet
selectedChatItems MutableState<Set<Long>?> Multi-select mode item IDs; null = selection off
showCommandsMenu MutableState<Boolean> Bot commands menu visibility
contentFilter MutableState<ContentFilter?> Active content type filter (images, videos, etc.)
availableContent MutableState<List<ContentFilter>> Content types available in this chat
activeChat State<Chat?> Derived from chatModel.chats matching staleChatId
unreadCount State<Int> Unread message count derived from chat stats

Chat Loading

On chat ID change (via snapshotFlow on chatModel.chatId.value, line ~162):

  1. Marks unread chat as read (markUnreadChatAsRead)
  2. Clears group members state
  3. Resets search, content filter, and selection
  4. Fetches available content types (updateAvailableContent)
  5. For direct chats, loads contact info and connection stats
  6. For groups with pending membership, opens member support chat

Chat Type Routing

The outer when (chatInfo) (line ~229) branches:

ChatInfo Type Behavior
ChatInfo.Direct, ChatInfo.Group, ChatInfo.Local Full ChatLayout with compose, search, reactions, per-chat theme
ChatInfo.ContactConnection ModalView wrapping ContactConnectionInfoView
ChatInfo.InvalidJSON ModalView with raw JSON display and share button

3. Message List

Location: ChatView.kt#L1592 (ChatItemsList composable)

The message list is a LazyColumnWithScrollBar with reverseLayout = true, meaning index 0 is the newest message at the bottom of the screen.

Key Behaviors

  • Merged Items: Messages are grouped via MergedItems.create() (line ~1653), which collapses consecutive similar system events into expandable groups. Revealed state is tracked in revealedItems.
  • Pagination: PreloadItems triggers loadMessages with ChatPagination.Before (older) or ChatPagination.Last (newer) when the user scrolls near list boundaries.
  • Scroll To Item: scrollToItem lambda supports animated scrolling to a specific item ID, used by search result taps and quoted message navigation.
  • Unread Marking: MarkItemsReadAfterDelay composable marks newly visible received items as read after a brief delay.
  • Date Separators: DateSeparator composable renders between messages when the date changes (via ItemSeparation.date).
  • Swipe to Reply: SwipeToDismiss modifier on each item (EndToStart direction, 30dp threshold) sets ComposeContextItem.QuotedItem.
  • Selection Mode: When selectedChatItems is non-null, a checkbox overlay appears on each item; a full-width clickable overlay toggles selection.

Item Layout (ChatViewListItem)

  • Group received messages with showAvatar = true: Column layout with MemberNameAndRole header, MemberImage (clickable to showMemberInfo), and message bubble.
  • Group received without avatar: Indented to align with avatar-bearing messages.
  • Sent messages (group or direct): Right-aligned with larger start padding.
  • Direct messages: Symmetric padding (76dp opposite side).

4. ChatItemView

Location: item/ChatItemView.kt#L66

fun ChatItemView(
  chatsCtx, rhId, chat, cItem, composeState, imageProvider,
  useLinkPreviews, linkMode, revealed, highlighted, hoveredItemId,
  range, selectedChatItems, searchIsNotBlank, fillMaxWidth,
  selectChatItem, deleteMessage, deleteMessages, archiveReports,
  receiveFile, cancelFile, joinGroup, acceptCall, acceptFeature,
  openDirectChat, forwardItem, scrollToItem, scrollToItemId,
  scrollToQuotedItemFromItem, setReaction, showItemDetails,
  reveal, showMemberInfo, showChatInfo, developerTools, showViaProxy,
  showTimestamp, itemSeparation, ...
)

The composable routes based on cItem.content and cItem.meta.itemDeleted:

  • Deleted items -> DeletedItemView or MarkedDeletedItemView
  • Message content (SndMsgContent, RcvMsgContent) -> FramedItemView or specialized views depending on msgContent type
  • Call items -> CICallItemView
  • Integrity/decryption errors -> IntegrityErrorItemView, CIRcvDecryptionError
  • Group invitations -> CIGroupInvitationView
  • Events (group/direct/connection events) -> CIEventView
  • Feature changes -> CIChatFeatureView, CIFeaturePreferenceView
  • E2EE info -> CIEventView
  • Chat banner -> handled at list level, not in ChatItemView
  • Invalid JSON -> CIInvalidJSONView

Reactions

ChatItemReactions row renders below each message bubble, showing emoji reaction counts. Tapping own reactions removes them; tapping others' opens a member list dropdown.

Context Menu

Long-press or right-click opens a dropdown menu with context-sensitive actions (see section 6).

5. Message Types

CIContent Variant MsgContent Type View Composable Source File
SndMsgContent / RcvMsgContent MCText FramedItemView -> TextItemView or EmojiItemView TextItemView.kt, EmojiItemView.kt
SndMsgContent / RcvMsgContent MCLink FramedItemView (with link preview) FramedItemView.kt
SndMsgContent / RcvMsgContent MCImage CIImageView (inside FramedItemView) CIImageView.kt
SndMsgContent / RcvMsgContent MCVideo CIVideoView (inside FramedItemView) CIVideoView.kt
SndMsgContent / RcvMsgContent MCVoice CIVoiceView CIVoiceView.kt
SndMsgContent / RcvMsgContent MCFile CIFileView CIFileView.kt
SndMsgContent / RcvMsgContent MCReport FramedItemView (with report styling) FramedItemView.kt
SndCall / RcvCall -- CICallItemView CICallItemView.kt
RcvIntegrityError -- IntegrityErrorItemView IntegrityErrorItemView.kt
RcvDecryptionError -- CIRcvDecryptionError CIRcvDecryptionError.kt
RcvGroupInvitation / SndGroupInvitation -- CIGroupInvitationView CIGroupInvitationView.kt
RcvDirectEventContent -- CIEventView CIEventView.kt
RcvGroupEventContent / SndGroupEventContent -- CIEventView CIEventView.kt
RcvConnEventContent / SndConnEventContent -- CIEventView CIEventView.kt
RcvChatFeature / SndChatFeature -- CIChatFeatureView CIChatFeatureView.kt
RcvChatPreference / SndChatPreference -- CIFeaturePreferenceView CIFeaturePreferenceView.kt
RcvGroupFeature / SndGroupFeature -- CIChatFeatureView CIChatFeatureView.kt
SndModerated / RcvModerated / RcvBlocked -- MarkedDeletedItemView MarkedDeletedItemView.kt
SndDirectE2EEInfo / RcvDirectE2EEInfo -- CIEventView CIEventView.kt
SndGroupE2EEInfo / RcvGroupE2EEInfo -- CIEventView CIEventView.kt
RcvChatFeatureRejected / RcvGroupFeatureRejected -- CIChatFeatureView CIChatFeatureView.kt
ChatBanner -- ChatBannerView (inline in ChatItemsList) ChatView.kt
InvalidJSON -- CIInvalidJSONView CIInvalidJSONView.kt
CIMemberCreatedContact -- CIMemberCreatedContactView CIMemberCreatedContactView.kt

6. Context Menu Actions

Context menu actions are built dynamically in ChatItemView based on message type, direction, chat type, and feature flags.

Action Condition Effect
Reply Message content (not event/deleted), not local notes Sets ComposeContextItem.QuotedItem
Edit Sent message, editable (meta.editable), text/link content Sets ComposeContextItem.EditingItem
Delete for me Any deletable item apiDeleteChatItems with cidmInternal mode
Delete for everyone Sent + within time window, or moderator privilege apiDeleteChatItems with cidmBroadcast mode
Moderate Group moderator + received message apiDeleteMemberChatItems
Forward Message content, not live message Opens share sheet via SharedContent.Forward
Select Any selectable item Enters multi-select mode (selectedChatItems)
React Message content, reactions enabled Opens emoji picker; calls apiChatItemReaction
Report Received group message, reports enabled Sets ComposeContextItem.ReportedItem with reason
Info Any message Opens ChatItemInfoView in end modal
Copy Text content present Copies text to clipboard
Save Image/video/file with completed download Saves media to device
Open File with completed download Opens file with system handler
Reveal / Hide Part of a merged group; expanded or collapsed Toggles revealedItems state

7. ChatInfoView

Location: ChatInfoView.kt

Opened via the info callback when the user taps the toolbar title in a direct chat. Displayed in ModalManager.end.

Preloads apiContactInfo (connection stats, server profile) and apiGetContactCode (verification code) before showing the modal.

Key sections: contact profile, local alias, connection stats, shared media, disappearing messages preference, voice/call/file feature toggles, encryption verification, and contact deletion.

8. GroupChatInfoView

Location: group/GroupChatInfoView.kt

Opened via the info callback for group chats. Displayed in ModalManager.end.

Preloads group members (setGroupMembers) and group link (apiGetGroupLink).

Key sections: group profile, group link, member list with roles, group preferences (disappearing messages, direct messages, full deletion, voice, files, SimpleX links, history), member admission, welcome message, reports view, and group deletion/leave.

9. Source Files

views/chat/

File Description
ChatView.kt Main chat view, ChatLayout, ChatItemsList, ChatInfoToolbar
ChatInfoView.kt Contact info modal
ChatItemInfoView.kt Individual message delivery/read info
ChatItemsLoader.kt Pagination and message loading logic
ChatItemsMerger.kt MergedItems grouping of consecutive events
CommandsMenuView.kt Bot /command menu popup
ComposeContextContactRequestActionsView.kt Contact request action buttons in compose area
ComposeContextGroupDirectInvitationActionsView.kt Group direct invitation compose actions
ComposeContextPendingMemberActionsView.kt Pending member compose actions
ComposeContextProfilePickerView.kt Profile picker in compose context
ComposeFileView.kt File attachment preview in compose
ComposeImageView.kt Image/video attachment preview in compose
ComposeView.kt Main compose area (ComposeState, send logic)
ComposeVoiceView.kt Voice recording preview in compose
ContactPreferences.kt Per-contact feature preferences
ContextItemView.kt Reply/edit/forward context indicator
ScanCodeView.kt QR code scanner
SelectableChatItemToolbars.kt Multi-select toolbar (delete, forward, moderate)
SendMsgView.kt Text input field, send button, voice record button
VerifyCodeView.kt Contact/member encryption verification

views/chat/item/

File Description
ChatItemView.kt Message type routing, context menu, reactions
CIBrokenComposableView.kt Fallback for rendering errors
CICallItemView.kt Call event display (incoming/outgoing/missed)
CIChatFeatureView.kt Chat feature change event
CIEventView.kt Generic event display (group/direct/connection)
CIFeaturePreferenceView.kt Feature preference change event
CIFileView.kt File message (download/upload progress)
CIGroupInvitationView.kt Group invitation card
CIImageView.kt Image message (thumbnail + fullscreen)
CIInvalidJSONView.kt Invalid JSON fallback display
CIMemberCreatedContactView.kt Member-created contact event
CIMetaView.kt Message metadata (time, status indicators)
CIRcvDecryptionError.kt Decryption error display
CIVideoView.kt Video message (thumbnail + player)
CIVoiceView.kt Voice message (waveform + player)
DeletedItemView.kt Deleted message placeholder
EmojiItemView.kt Large emoji-only message
FramedItemView.kt Message bubble frame (quoted item, text, media)
ImageFullScreenView.kt Fullscreen image gallery
IntegrityErrorItemView.kt Message integrity error
MarkedDeletedItemView.kt Marked-as-deleted / moderated message
TextItemView.kt Plain text message with markdown

views/chat/group/

File Description
AddGroupMembersView.kt Add members to group
GroupChatInfoView.kt Group info and management
GroupLinkView.kt Group link display and management
GroupMemberInfoView.kt Individual member info
GroupMembersToolbar.kt Members toolbar in group info
GroupMentions.kt @mention autocomplete
GroupPreferences.kt Group feature preferences
GroupProfileView.kt Group profile editor
GroupReportsView.kt Group reports list view
MemberAdmission.kt Member admission settings
MemberSupportChatView.kt Member support chat (scoped context)
MemberSupportView.kt Support chat list for moderators
WelcomeMessageView.kt Group welcome message editor
Reference in New Issue View Git Blame Copy Permalink