* plan: mcp-flat-sessions * plan: mcp-flat-sessions, the user's answers * plan: mcp-flat-sessions, image widths and times per platform * plan: mcp-flat-sessions, one flat media width and smaller avatars * plan: mcp-flat-sessions, list breaks * plan: mcp-flat-sessions, visible avatar gaps and the gap below the sender row * plan: mcp-flat-sessions, equal gaps around the name * plan: mcp-flat-sessions, restore the approved gaps * mcp: open the groups of new sessions in the Flat layout * ui: avatar on the name line and full-width messages in the flat layout * ui: record the snapshot references of the flat layout * ui: flat media beside the go-to button, text below tall name lines * mcp: source of the session image, Main group check in the e2e test * plan: mcp-flat-sessions, as implemented * plans: flat sessions, the tests run on master * android, desktop: keep the width limit of the media box in intrinsic measurement * android, desktop: test the intrinsic height of media at an unbounded width * ui: flat name rows close to their messages, cards at the text edge * desktop: flat group snapshot references, the media scene * plans: flat sessions, avatars and flat-layout defects * desktop: avatar snapshot scenes with photos and placeholders * ios: flat snapshot references, the deleted items scene * desktop: avatar snapshot scenes of share, contact and user lists, calls, channel members * android, desktop: avatars without inner padding, each in its former box * ios: snapshot scenes of hidden integrity errors in Flat rows and bubbles * desktop: avatar snapshot references, recorded before the inset removal * android, desktop: snapshot scenes of hidden integrity errors in Flat rows and bubbles * ios: hidden integrity errors take no space in the chat * plans: flat sessions, the user's answers, avatar call sites as implemented, hidden rows * ios: scenes of the time before deleted items, unread users, appearance * ios: avatars in Flat rows pass the letters' edge by 2 pt * ios: 6 pt from the avatar to the message below it in Flat rows * ios: time on the last line of messages ending with empty lines in Flat * ios: code cards as wide as the code, the time beside them, in Flat rows * ios: delivery status only with the time in Flat rows * ios: time shown on a message before a deleted or hidden item * ios: no gap below a reactions row between one sender's messages in Flat * ios: no early wrap of the last word before the time in Flat rows * ios: name the condition that shows the time before deleted items * ios: spec links to the moved lines of TerminalItemView * ios: test of the delivery status without the time in Flat rows * desktop: snapshot references after the inset removal, hidden integrity error scenes * android, desktop: blur of blocked members' photos as on iOS * ios: user picker scene with the chat running, as in the app * android, desktop: snapshot scenes of the Flat defects and the chat banner * ios: status without the time only for partial delivery and errors * ios: snapshot references of the Flat avatar overshoot, gap and defect fixes * ios: snapshot references without the empty line after a hidden time * android, desktop: hidden integrity errors take no space; the time before deleted and hidden items * android, desktop: chat banner 20 dp above its avatar and 10 dp below * android, desktop: Flat avatars 2 dp past the letters, 6 dp above the text, four layout defects * android, desktop: share list shows each chat's own avatar * android, desktop: business, bot and agent placeholders as on iOS * plans: flat sessions, the decisions as implemented on Android and desktop * ios: scene of a hidden item between two messages of one sender * ios: sender name 12 pt after the visible avatar in Flat rows * ios: rows around hidden items grouped as if the hidden items were absent * ios: full time in a deleted message bubble * android, desktop: rows skip hidden items as neighbours; the time before deleted items in Flat rows only * android, desktop: Flat sender names 12 dp after the avatar * android, desktop: avatar placeholders from their own assets; unused icons removed * plans: flat sessions, questions numbered as answered, neighbours of hidden rows, overshoot note * ios: snapshot references of rows around hidden items and the name start * android, desktop: hidden rows keep one date separator; marked deleted errors shown; rows rebuilt on the developer setting * desktop: snapshot references of the Flat decisions, defects, banner and rows around hidden items * spec, plans: Flat row layout, hidden rows and their neighbours, status with the time; avatar assets as implemented * android, desktop: new, unread and read statuses only with the time in Flat rows, as on iOS * desktop: snapshot references of the Flat defects scene with an unread message; plans: partial delivery wording * mcp: session image with the Flat row geometry: avatar 2 pt past the letters, text 6 pt below it * mcp: session image with a shorter answer, so the first row shows in full * ios: user picker snapshot scenes at the height of the sheet * plans: flat sessions, an avatar column with tighter paddings * ios: snapshot references of the user picker at the height of the sheet * plans: flat sessions, the avatar column with only the gap open * ui: Flat avatar column, the avatar 2 into the padding, text 10 after it Names, items, later rows of one sender, events and deleted cards sit in the message column; media widths are measured from it. Chats without avatars keep 12 on both sides. The session scene on both platforms; the README image redrawn with the column. * ui: snapshot references of the Flat avatar column and the session scene * ui: Flat cards and pills take their corners from the roundness setting Deleted, marked deleted, moderated, blocked, error and decryption error cards and group invitations: 18 × roundness without a tail, as media, on iOS and Android/desktop. A scene of each platform at roundness 0.3. * ui: Flat pill text on the text start, sender rows at master's pitch Deleted, marked deleted, moderated, blocked and error pills start at the message column, so their text lines up with the messages, as on master; in chats without avatars they keep 12 from the screen edge. The name line of a sender row starts at the row gap, as on master; the avatar is centred on it and reaches into the gap above, on both platforms. * android, desktop: avatars in a box drawn at exactly 5/6 of it, as master's padded placeholders centeredIn scales its child to 5/6 of the box and centres it with fractional placement, so placeholder edges match master at the pixel at every font scale. Photos and the incognito icon take the same size, up to 1 px larger than master's rounded photo padding. The chat-link thumbnail of the chat list uses the same box, 44 sp. * android, desktop: avatars in a box at whole pixels, photos fill the drawn box centeredIn places its child at box/12 rounded down and sizes it to the box less twice that, so placeholders keep master's first and last ink pixel and stay sharp. Photos take their rounded square from the drawn box in pixels. * ui: photo corners from the nominal size; iOS references of pills, corners and sender rows The rounded square of a photo keeps its corner radius from the size argument. iOS references for the pill alignment, the corner radius from the roundness setting with a 0.3 scene, and sender rows at master's pitch. * android, desktop: snapshot references of pills, corners, sender rows and avatars at whole pixels
71 KiB
Chat View Specification
Source: common/src/commonMain/kotlin/chat/simplex/common/views/chat/ChatView.kt
Table of Contents
- Overview
- ChatView Composable
- Message List
- ChatItemView
- Message Types
- Context Menu Actions
- ChatInfoView
- GroupChatInfoView
- Source Files
- Terminal Layout
Executive Summary
The Chat View is the primary message display and interaction surface in SimpleX Chat. It is built around the ChatView composable, 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)
| | | +-- TerminalChatItemRow (terminal layout, replaces the three lines above)
| | | |-- sender row, avatar in groups
| | | +-- ChatItemView
| | |-- 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#L98
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):
- Marks unread chat as read (
markUnreadChatAsRead) - Clears group members state
- Resets search, content filter, and selection
- Fetches available content types (
updateAvailableContent) - For direct chats, loads contact info and connection stats
- For groups with pending membership, opens member support chat
Chat Type Routing
The outer when (chatInfo) 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#L1768 (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(), which collapses consecutive similar system events into expandable groups. Revealed state is tracked inrevealedItems;MergedItem.revealedis true for a single item and for a revealed group row. The newer and older neighbours of a list item (ListItem.prevItem,nextItem) are the nearest shown items (shownNeighbour); the grouping bymergeCategoryuses the adjacent items. Sender rows, row gaps and the time grouping read these neighbours, so a hidden item between two messages of one sender leaves one sender row.ChatItemsListcreates the merged items again when the developer tools setting changes. - Hidden Items: an integrity error that is not marked deleted is hidden while developer tools are off (
ChatItem.hiddenInChat(developerTools)). Its row draws nothing in both layouts; as the oldest loaded row, it draws only the date separator at its top, with the date of the nearest shown newer item. The shown rows around it draw the date separator between them. With developer tools the error is drawn byIntegrityErrorItemView; a marked deleted error is shown as other marked deleted items, also without developer tools. - Pagination:
PreloadItemstriggersloadMessageswithChatPagination.Before(older) orChatPagination.Last(newer) when the user scrolls near list boundaries. - Scroll To Item:
scrollToItemlambda supports animated scrolling to a specific item ID, used by search result taps and quoted message navigation. - Unread Marking:
MarkItemsReadAfterDelaycomposable marks newly visible received items as read after a brief delay. - Date Separators:
DateSeparatorcomposable renders between messages when the date changes (viaItemSeparation.date). - Swipe to Reply:
SwipeToDismissmodifier on each item (EndToStart direction, 30dp threshold) setsComposeContextItem.QuotedItem. - Selection Mode: When
selectedChatItemsis 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 withMemberNameAndRoleheader,MemberImage(clickable toshowMemberInfo), and message bubble. The name starts at the bubble edge, 4dp after the avatar, as the bubble (user, as iOS). - 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).
- Terminal layout: When
LocalTerminalLayout.currentis true, all chat types render throughTerminalChatItemRow, which wrapsChatItemView, instead of the branches above (see section 10). The selection offset applies to sent items too.
4. ChatItemView
Location: item/ChatItemView.kt#L71
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, showViaProxy,
showTimestamp, itemSeparation, ...
)
The composable routes based on cItem.content and cItem.meta.itemDeleted:
- Deleted items ->
DeletedItemVieworMarkedDeletedItemView - Message content (
SndMsgContent,RcvMsgContent) ->FramedItemViewor specialized views depending onmsgContenttype - Call items ->
CICallItemView - Integrity/decryption errors ->
IntegrityErrorItemView,CIRcvDecryptionError; the row of a hidden integrity error draws nothing (section 3) - 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).
Terminal Layout Adjustments
When LocalTerminalLayout.current is true, ChatItemView and the item views it calls keep their content and start at one text edge, CHAT_ITEM_TEXT_PADDING (12dp) inside the item; messages are drawn without the bubble fill and tail:
- Items are start-aligned for both directions (
alignEnd). The item click has no indication; the row draws it (section 10).GoToItemButtonis placed as described in section 10 (L345, L817). Voice items use the arrangement of received items for both directions. chatItemTailEnabled()returns false, soshapeStyledraws no tail.FramedItemViewhas a transparent background. Headers (report, moderated, blocked, deleted, live, forwarded) and the quote have no background and start at the text edge. The quote has the bar of Markdown quotes (Modifier.quoteBar), its text inonSurfaceat 70%, 15sp. The quote is a card (cards, below),terminalQuoteTop(item)below the part above it:TERMINAL_PARAGRAPH_GAPbelow a report, deletion or live header, otherwise 0. The bar spans the whole quote row, including an image or video thumbnail; the thumbnail has the message corner clip of media (thumbnailClip,clipChatItem, rounded by thechatItemRoundnesspreference, square at 0) and stands 12dp after the quote text, or 12dp after the bar when the quote has no text and no sender (QuotedMsgOrGap,QUOTE_BAR_GAP); the file, voice and chat link icons of the quote have no top padding. Headers:TERMINAL_HEADER_TOP_GAP(2.5sp) above,TERMINAL_HEADER_BOTTOM_GAP(1.5sp) below; the header text useschatTextStyleat its size insecondary, and the icon is centred on it and takes no height (Modifier.inlineIcon()).- Images, videos, link previews and chat link cards are cards (below), start at the text edge,
terminalCardTop(item)below the part above them (TERMINAL_PARAGRAPH_GAPbelow a header or the quote, otherwise 0), and keep the message corner clip (mediaModifier). Link previews and chat links are cards in the quote colour (cardModifier). An image, a video or the image of a link preview is as wide asflatMediaWidthof the width it is given (Modifier.mediaWidth,CIImageView.kt): that width up toDEFAULT_MAX_IMAGE_WIDTH(500dp) when the media is wide, 0.75 of it when it is tall or square (isTallMedia: width × 0.97 ≤ height); classic:fixedMediaWidth, 0.75 of min(500dp, the window less 100dp) for tall media (imageViewFullWidth). The image and the player inside the media box fill it (Modifier.mediaContentWidth). The box's layout takes at mostfixedMediaWidth, orDEFAULT_MAX_IMAGE_WIDTHin flat rows, also when an intrinsic measurement gives it an unbounded width. The maximum intrinsic width of the media isDEFAULT_MAX_IMAGE_WIDTH, so thewidth(IntrinsicSize.Max)column of a captioned item is the wider of 524dp (the media and its two text edges) and the caption, at most the row, and the media is given the same width as without a caption. The column of an image or video without caption is as wide as the media, so the time is placed beside tall media when it fits. The item itself is not clipped (clipChatItemofFramedItemViewandChatItemViewis skipped), so headings and emoji are drawn whole. Captions are selected by the classic conditions. - Captions (user, D30): the text below an image, video, link preview, chat link card, voice message or file is laid out as the text of a close follow-up message, the time on it only.
PriorityLayoutmeasures it in the full width of the item (limitToPriorityWidth = false; classic: the width of the media) and places the elements at the start edge in both directions (placeRelative), the caption of a link preview has no width limit (classic:DEFAULT_MAX_IMAGE_WIDTH), and a chat link card keeps its own width (width(IntrinsicSize.Max)). Its gap below the media is the gap from the same media without text to a close follow-up message. An image or video without caption keeps the classic limit (limitToPriorityWidth = true): a quote or header above it takes the width of the media, so the white time over the media stays on its bottom end corner. CIMarkdownText: top paddingterminalTextTop(item):TERMINAL_PARAGRAPH_GAPbelow a card (the quote, or content other than text: an image, video, voice message, file, link preview or chat link card) and below a header when the text starts with a code block, table or rule; 0 instead when the text starts with empty lines (block Markdown:leadingEmptyLines; other text: a line break at its start, except in reports, whose first line holds the reason), which are then the gap (the larger of the two; cards, below); below a header (forwarded, deleted, live, report) and no quote,TERMINAL_LEVEL_STEPwhen the text starts with a heading; otherwise 0. No bottom padding. Its text style:body1inmessageTextColor(), merged withchatTextStyleat thebody1size. The default style ofMarkdownTextis classic and is used outside the rows (the compose context preview).- Code block cards, table cards and rules of
MarkdownBlocksare cards (below) without margins; the gap between a card and the block next to it is the larger ofTERMINAL_PARAGRAPH_GAPand the empty lines typed between them (bubbles:TERMINAL_BLOCK_TOP_GAP(5.75sp) above,TERMINAL_BLOCK_BOTTOM_GAP(5sp) below). The last block of a message without a meta line (marksLastBlock; a live message has the meta line with the typing indicator) is also marked withmessageLastLine(): the time moved under it isTERMINAL_META_GAPbelow its edge (section 10). The typing line under a last card isTERMINAL_PARAGRAPH_GAPbelow it. In a message of rules only, the rules are at least as wide as the copy of the time (ruleMinWidthofMarkdownBlocks, measured byMarkdownText; user, D31), as in classic, where the meta line sets the width; the time stays beside them unless a wider quote or header widens the item so that the rule leaves no room for the time. - Text blocks of
MarkdownBlocks: a heading that does not start the text addsTERMINAL_LEVEL_STEP(4.75sp), also in bubbles (outside chats: no gap); above a heading that starts the text, the gap is the row gap (terminalRowGap) orterminalTextTop. A block after a heading, other than a heading, hasTERMINAL_HEADING_BOTTOM_GAP(half ofTERMINAL_LEVEL_STEP, 2.375sp) above it instead, so a heading is nearer to its own text than to the text above it. Each empty line typed before or between blocks and list entries (emptyLines; before the first blockleadingEmptyLines) addsemptyLineHeight: in terminal rowsTERMINAL_PARAGRAPH_GAP, the gap between messages (user); in bubbles and outside chats one line of the text style, its line height in proportion to the font size in px, as Android sets text line heights above font scale 1.05. The core sendsmarkdownBlocksfor text with block syntax or an empty line, up to 2000 markup tokens; text without them is one text in all layouts, each of its empty lines one line of the text style. After the last block, in bubbles, the empty lines are the line breaks of the tokens after it (the core removes one final line break of the text), less one when the text does not end with a line break (trailingEmptyLines), as in plain text, where the last line holds the time; when there are any, the meta line follows them. Terminal rows draw no empty lines after the last block, so the time is beside the last line when it fits (user). A gap has at mostMAX_EMPTY_LINES(100) empty lines. - Text styles:
chatTextStyle(fontSize, color)sets the line height to font size ×CHAT_LINE_HEIGHT_RATIO(22/16) × f(w) andLineHeightStyle(Proportional, Trim.None), in terminal rows and in bubbles (usesChatTypography():LocalTerminalLayoutorLocalBubbleLayout); outside chats it returnsTextStyle.Default. Every line takes the full line height, one-line texts included. The space added to a line is split in the ratio of the font's ascent to its descent. On desktop each run of a line is given its own line box; with this alignment, runs of different sizes (the 12sp time in the copy of the meta) are placed on one baseline in a line of the body line height. f(w) = 1 −CHAT_LINE_HEIGHT_CONTRAST_SLOPE(0.1515) × (1 − w); w: the L* contrast of the text colour againstMaterialTheme.colors.background, divided by that ofmessageTextColor(), limited to 0…1, and 1 when the message text has no contrast. Used for message text and captions (the style ofCIMarkdownText), Markdown quotes (text colour at 70%), code, headings (body line height × scale), quote text and the quote's sender (inbody1, Inter), the sender name and role, event texts (chatEventTextStyle(base): 12sp,secondary, merged intobase, by defaultLocalTextStyle.current; in both layouts the text direction is left unspecified, which Compose resolves to the layout direction, so that an event starting with a name in the opposite direction keeps the copy of the time at the end of the row), header texts and the time. For names and the white time over media (lineHeightColorofCIMetaView), f is computed with the message text colour. Line heights in the light and dark themes: message text 22sp, quote text 19.6sp and 19.9sp, event text and time 15.1sp and 15.4sp. - Headings: body size ×
TERMINAL_HEADING_RATIO(1.25) to the power 2, 1, 0 for levels 1, 2, 3, 25, 20 and 16sp for 16sp text; levels 4–6 also at the body size; all bold (also in bubbles; Markdown outside chats: 1.5, 1.3, 1.15); line heights scaled the same.Modifier.headingBoxlays a heading out with the space of a body line above its capitals and below its last baseline (Inter cap height 2048/2816 em). It uses the px ratio of the body and heading font sizes: Android scales font sizes non-linearly from font scale 1.03 and, above 1.05, sets line heights in proportion to the font size in px, so the capitals are placed as body capitals at every font scale (within 1px at 1, 1.15 and 1.3). - Files and voice messages are cards (below):
terminalCardTop(item)above them (terminalTopofCIFileView, passed byFramedItemView; the top padding ofCIVoiceView), no padding below, no padding of the file icon. Voice messages drawn byFramedItemView(with a caption, a quote or a header;hasText = true): the layout of a voice message drawn alone (its indicator), without its own time; no padding below the item. - Emoji-only items, also under a quote or a header, are cards (below):
terminalCardTop(item)above, no padding below (classic: 8dp; under a quote or header the text paddings of a bubble). Under a quote or a header the emoji is not stretched to the item width, so its reported last line is the emoji itself;PriorityLayoutplaces it at the start edge in both directions. - Item gaps: one gap above each row,
terminalRowGap(item, older, separated, largeGap, hasSenderRow), passed byChatItemsListastopGapof the row. It isTERMINAL_PARAGRAPH_GAPwhen an older item exists, the rows are not separated and one of these holds: the gap to the older item is large; the row shows a sender row; either item is not one-line (isOneLine: text or unknown content without a file, without quote, header, deletion, live state or report, without block Markdown and without a line break in the text, so that a large emoji is one-line and an event is not; user). Otherwise it is 0, also below a reactions row, so that close one-line messages of one sender have no gap between them when one has reactions (user).separated(terminalRowsSeparated): a date separator is drawn between the two rows (the older row is revealed, a single item or a revealed group row, and its date differs from that of the oldest item of the row), or the older item is the chat banner.olderis the nearest shown older item (section 3); for a collapsed group, the nearest shown item older than the group, andlargeGapis computed against the oldest item of the group. The bottom of a row isTERMINAL_LEVEL_STEPwhen a date separator is drawn below it, 8dp for the newest row, as classic, otherwise 0 (ChatItemBox(top, bottom); classic: half ofBUBBLE_CLOSE_GAPorBUBBLE_FAR_GAPabove and below). The sender row has no gap of its own below it, other than the gap above a card (cards, below), and none above it: the avatar reaches into the gap above (section 10, Row Layout). The gaps are constants in sp at the top ofTerminalItemView.kt, converted to dp with the font scale. The bottom padding of call items (8dp) and the 6dp between the two rows of the forwarded-from header are classic. - Vertical gaps, between line boxes and block edges, are multiples of the paragraph unit
TERMINAL_PARAGRAPH_GAP(P: a third of the line height of 16sp text, 7.33sp; user):
0 lines of a message; close one-line messages of one sender, also below a reactions row; the sender name and the line under it; reactions under a line of text
n × P n empty lines typed in a message; headings add TERMINAL_LEVEL_STEP above and TERMINAL_HEADING_BOTTOM_GAP below
P other messages, also of one sender; a sender change, above the name; above and below an event; next to a card
P + H/2 a sender change in a group, above the avatar (H: TERMINAL_LEVEL_STEP)
In chats with avatars the item is in the message column, after the avatar column (section 10, Row Layout).
- Cards: images and videos, link previews, chat link cards, code blocks, tables and rules, files, voice messages, the quote, large emoji, group invitations, and the rounded cards of deleted and error items (
ItemTextCard,DecryptionErrorCard). Each is marked withModifier.messageCard(); the marks are read in terminal rows only. A card hasTERMINAL_PARAGRAPH_GAPnext to text or another card of its item, as the top padding of the lower part. At the top of an item it has none above it:TerminalChatItemRowaddsTERMINAL_PARAGRAPH_GAPunder the sender row when the item reports a card at its top. At the bottom of an item it has none below it:ItemWithMetaaddsgapBelowCardwhen the content reports a card at its bottom,terminalReactionsGap(item),TERMINAL_PARAGRAPH_GAPwhen reactions follow as a line of text, otherwise 0. - Event, feature and member-created items use
chatEventPadding(): in terminal rows the text edge at the sides and no padding above and below, so that the row gap,TERMINAL_PARAGRAPH_GAP, separates an event from the rows above and below it (classic: 6dp at the sides, above and below). The icons of feature and preference items are centred on the text and take no height (Modifier.inlineIcon()); the row of merged feature icons is one event text line high; both also in bubbles.CIEventViewhas no line limit in terminal rows, so the copy of the time stays at the end of the text (user, D23; classic: 4 lines). Voice and call items, reactions and group invitations start at the text edge. The rounded cards of deleted and error items (ItemTextCard,DecryptionErrorCard) startterminalPillStart()into the message column:CHAT_ITEM_TEXT_PADDINGless the gutter of the row, at least 0, read fromLocalTerminalGutter, whichTerminalChatItemRowprovides. In groups the card starts at the column and its text, 12dp inside, is on the text edge of the messages, as on master (user); in chats without avatars the card starts at the text edge, 12dp from the screen edge. The voice play button and file status circle are filled with the quote colour (sentQuote,receivedQuote; classic:sentMessage,receivedMessage). - Time and status: placed at the end of the row by
ItemWithMeta, the baseline of the time on the last baseline of the content (section 10). Message text ends withmetaReserveCopy, in both layouts: a transparent copy of the meta with no-break spaces, inFontWeight.Normal. The copy starts with a breaking space (breakBefore, user) when text precedes it in its paragraph, so the time alone moves to the next line when it does not fit; the copy of the meta line under a last card or rule (rangeempty) and the copy measured forruleMinWidthstart with a word joiner (U+2060), which forbids a line break before the copy. The direction mark of its paragraph follows (U+200E left-to-right, U+200F right-to-left), so that the bidirectional algorithm places the copy at the end of the line, also after words in the other direction on a wrapped last line. Its spaces and texts are appended byreserveSpaceForMeta, which has the conditions ofCIMetaText, except that the timer is reserved for every timed message, and returns the classic string unchanged, through span parameters: icon spaces and the spaces between them are no-break spaces at thebody1size in dp (16dp converted to sp with the density, so that they keep their width at every font scale, as the icons do; also after a heading and in event text), 18dp for each icon, wider than a 12dp icon with its spacer (15dp or 16dp); after the 17dp icons one more space is added (22.5dp against 21dp): the sent and received status icons (tallStatusIcon, also used byCIMetaText) and the via-proxy icon; the time and the timer text of a disappearing message are at 12sp. The copy includes the file encryption and signature icons (encryptedandsignedFileVerifiedofMarkdownText, passed byCIMarkdownTextfrom the item). Text whose paragraph direction (textLayoutDirection: right-to-left when the first 50 characters of the message text hold a right-to-left character; all blocks and lines of a message take it) differs from the outer direction (parentDirection, passed by the blocks and by the meta line of a live message; otherwiseLocalLayoutDirection) ends with a line break instead of the copy, so the time is placed on an added empty line. Emoji, and the last code block, table or rule of a message, report their width (Modifier.messageLastLine()); the time moves under them when the row leaves no room for it beside them. The meta line with the time is drawn under such a block only for live messages, for the typing indicator. In terminal rows the status of an item being sent (SndNew), completely sent (SndSent, complete), delivered (SndRcvd, receipt ok, complete), unread (RcvNew) or read (RcvRead) is drawn only with the time (terminalShowsStatus(status, showTimestamp)), as on iOS; the status of a partial delivery, an error or a warning is drawn without the time too.CIMetaView,metaReserveCopyand the size line of files (CIFileView) apply it throughshownStatus(showStatus, meta, showTimestamp); in bubblesshowStatusis unchanged. File text keeps the space reserved for the time at the end of its size line. Images and videos without a caption (captionlessMedia) keep the meta insecondarybeside the media when it fits in the row, otherwise the meta is drawn over the bottom end of the media in white, as in the classic layout (overlayMeta). Event items are wrapped inChatEventWithMeta, which passes the separator and the end of the event text apart (separator,ts): in the classic layout two spaces and the time without a style, in the terminal layout three transparent no-break spaces inchatEventStyleand the transparentmetaReserveCopyof the meta without status and edit icons, so the last word of the event text is moved to the next line with the time when they do not fit. Each view puts the separator where the classic layout has two spaces (user, D28): after the event text, or in the "Open" and "Accept" links, so the classic output is unchanged. - Group invitations, deleted items and error items (
IntegrityErrorItemView,CIRcvDecryptionError) keep their rounded coloured card. Its shape isterminalCardShape(): 18dp × thechatItemRoundnesspreference, without a tail, as the clip of media (user); square at 0.
Bubbles
When LocalBubbleLayout.current is true (classic chats, provided by ChatView with LocalTerminalLayout, the classic theme preview, and the chat item and chat view previews through BubblePreview), bubbles follow one inset (plans/2026-10-25-classic-bubbles.md). The previews of deleted and error items clip them as ChatItemView does (clipChatItem).
- Texts use
chatTextStyle, as terminal rows: message text, captions, Markdown blocks, quote text and sender (body1, Inter), headers, the time, event texts; the texts ofDeletedItemViewand error items throughbubbleTextStyle(fontSize, color),chatTextStylein bubbles only, so the cards of terminal rows keep their style (the one-line text ofMarkedDeletedItemViewkeeps its style, its line height rounded bybubbleLineHeight). Call items are drawn as in master:ChatItemViewprovidesLocalBubbleLayoutfalse for them. Markdown blocks in bubbles have the heading gaps, heading sizes andheadingBoxof terminal rows; cards and rules haveTERMINAL_BLOCK_TOP_GAP(5.75sp) above andTERMINAL_BLOCK_BOTTOM_GAP(5sp) below, and each empty line typed is one line of the text style. - On desktop,
bubbleLineHeight(lineHeight)rounds a line height in bubbles to whole pixels, with the proportional alignment ofchatTextStyle:chatTextStyleapplies it in bubbles, and so do the last text of a group invitation (18sp, or "Tap to join" at the line height of Inter,INTER_LINE_HEIGHT), "Fix connection" of decryption errors and the size line of files (the line height of Inter) and the text ofMarkedDeletedItemView(22sp); on Android the line heights are unchanged. Skia draws the baseline of a line at its top plus the rounded ascent and reports the rounded line height less the descent, which Compose rounds intoFirstBaselineandLastBaseline; both are one pixel row only when ascent and descent add up to whole pixels, so the time, placed by reported baselines, is drawn on the baseline of the text (owner report). BUBBLE_TEXT_INSET(11dp, user) is the distance from a bubble or band edge to the capitals of the text under it, and from the last baseline to the edge under it; in dp, so it keeps its size at larger fonts (user). Message text, captions and an emoji under a quote or header havebubbleTextBoxPadding(): that inset less the space of 16sp text with the full line height above its capitals (BUBBLE_LINE_ABOVE_CAPS, 6sp) and under its last baseline (BUBBLE_LINE_BELOW_BASELINE, 4.375sp), at least 0; 5dp and 6.625dp at font scale 1.BUBBLE_SIDE_INSET(14dp, user) is the distance from the bubble sides to message text, captions, an emoji under a quote or header and the end of the time. Header bands, the quote band and deleted and error items useModifier.bubbleTextPadding(firstLineFontSize, bottom):BUBBLE_SIDE_INSETat the sides and the inset by the first and last baselines; a header followed by a quote or a forwarded header has no inset below. The header starts atBUBBLE_SIDE_INSETand its icon takes no height. Deleted and error items are drawn byItemTextCard(DeletedItemView,MarkedDeletedItemView,CIMsgError) and the privateDecryptionErrorCard(the decryption error items), each with one switch between the bubble and the rounded card of terminal rows: in bubbles they fill the shape ofclipChatItem(Surfacewith its defaultRectangleShape, user). That shape has no tail for items without message content (shapeStyleWithTail:msgContentnull; user): deleted, moderated, blocked, error, decryption error and invalid JSON items.chatItemTailRendered(chatItem, tailVisible, revealed)tells whether the tail is drawn, from the shape style of the item asclipChatItemcomputes it;FramedItemView,chatItemOffsetand the sender rows ofChatItemsListuse it. The file row endsBUBBLE_TEXT_INSETunder the baseline of its size line; the ink bottom of the file icon is aligned to that baseline (fileIconOnBaseline: the icon size ×FILE_ICON_INK_INSET, the space under the ink ofic_draft_filled, rounded down).- The time:
Modifier.bubbleMeta()places the baseline of the timeBUBBLE_TEXT_INSETabove the bubble bottom, on the last baseline of the text; ticks without a time where they stand next to a time (metaBaseline, shared withTerminalMetaLayout). In deleted and error items the time follows the text on its last baseline (bubbleMetaOnBaseline, the text aligned byLastBaseline), so a wrapped text keeps the time on its last line; in group invitationsMetaOnLastBaseline(meta, content)places it at the end of the card on its last baseline (the card bottom without a baseline, in intrinsic measurement; user). Message text, an emoji under a quote or header, decryption errors and group invitations end withmetaReserveCopy; after text it starts with a breaking space (breakBefore), so the time alone moves to the next line, except in group invitations, where the word joiner keeps the time with the last word (user); the size line of a file keeps the string ofreserveSpaceForMeta. - Gaps between rows:
BUBBLE_CLOSE_GAP(2sp) between close messages,BUBBLE_FAR_GAP(8sp) at a large gap, half above and half below each row. Event rows (isEvent: items without a sender,hasTerminalSenderfalse, other than the chat banner: event, feature, preference and end-to-end encryption items, also collapsed) form runs (user):eventRunLargeGapmakes the gap between two events close and the gap between an event and another row large;ChatItemsListapplies it to the gap above a row (eventGapAbove) and to the separation below it (eventGapBelow, a large gap with the time), so a message above an event shows its tail and time. The avatar column of an event has no 8dp top padding.
Both layouts: MarkdownText draws message text in messageTextColor(), onSurface at 95% in dark themes. A report whose blocks have no text ranges (only rules) is drawn as one text: the reason, then the source text of the rules.
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; hidden without developer tools unless marked deleted (section 3) |
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 |
Animated Images
SimpleAndAnimatedImageView is expect/actual. Android delegates to coil, which drives the animation
itself. Desktop decodes frames with Skia's Codec in platform/AnimatedImage.desktop.kt, where
rememberAnimatedImage(data, still, hidden) returns the frame to draw and falls back to the still image when
the data is not an animation, exceeds the decode bounds, or fails before showing a frame. Decoding runs off the UI thread
on two threads of the shared pool, and pauses while the window is minimized or hidden, while the image is behind the
privacy blur, and while a full screen modal covers the chat. An animation whose frames cost too much to
decode stops on the frame it reached rather than falling back to the still. The chat list preview (smallView) stays a
still image. Only GIF reaches this path: desktop decodes stills with ImageIO, which has no WebP reader, so a
received .webp renders only as the sender's preview and never opens full screen.
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; below a file's expiry, for a user without a badge, a button opening the badges view |
ChatItemsLoader.kt |
Pagination and message loading logic |
ChatItemsMerger.kt |
MergedItems grouping of consecutive events; nearest shown neighbours of each item; hidden integrity errors |
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; ItemTextCard, the card of deleted and error items |
EmojiItemView.kt |
Large emoji-only message |
FramedItemView.kt |
Message bubble frame (quoted item, text, media) |
ImageFullScreenView.kt |
Fullscreen image gallery |
MarkdownFileView.kt |
Markdown file viewer, formatted or as text |
IntegrityErrorItemView.kt |
Message integrity error |
MarkedDeletedItemView.kt |
Marked-as-deleted / moderated message |
TerminalItemView.kt |
Terminal layout: LocalTerminalLayout, sender row rule, TerminalChatItemRow, ItemWithMeta |
TextItemView.kt |
Plain text message with markdown; blocks of markdownBlocks drawn as a column of views by MarkdownBlocks (MarkdownBlocks.kt) |
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; MemberProfileImage, the member's avatar: its image, otherwise the placeholder of its peer type (peerTypeIcon: person, agent or cube) |
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 |
ChannelRelaysView.kt |
Channel relay list. Owner-only Add relay entry opens AddGroupRelayView with existingRelayIds = groupRelays.mapNotNull { it.userChatRelay.chatRelayId }.toSet() — every relay currently in groupRelays is excluded regardless of relayStatus, mirroring the backend APIAddGroupRelays gate. Long-press menu offers Remove relay for relays that can be removed. |
AddGroupRelayView.kt |
Sheet to pick relays to add to a channel |
Relay Rejection Surface
When a relay operator runs /leave #channel, the relay sends x.grp.relay.reject over the owner-relay direct contact channel. Owner-side handling: the corresponding GroupRelay.relayStatus transitions RSInvited → RSRejected; the relay's GroupMember.memberStatus is set to MemLeft so the owner UI renders the rejected relay identically to one that explicitly ran /leave (MemRejected is reserved for the knocking-admission flow). In GroupMemberInfoView, an additional "Status: rejected by relay operator" InfoRow appears when groupRelay?.relayStatus == RelayStatus.RsRejected. The status is final on the owner side — clearable only by the relay operator running /group allow #<channel>, which has no owner-facing event.
The RelayStatusIndicator composable in AddChannelView.kt renders RsRejected with a red dot and "rejected" text, matching the connFailed/removed rendering.
10. Terminal Layout
Location: item/TerminalItemView.kt
Rendering of a chat whose ChatInfo.activeChatLayout is ChatLayoutMode.Terminal: full-width start-aligned rows, the sender name once per group of messages, avatars in groups only, messages without bubbles (item-level changes: section 4). Android and desktop; iOS: apps/ios/spec/client/chat-view.md, section 9.
Activation
| Step | Location |
|---|---|
terminal = chatInfo.activeChatLayout(user) == ChatLayoutMode.Terminal |
ChatView |
LocalTerminalLayout provides terminal and LocalBubbleLayout provides !terminal, next to LocalAppBarHandler and LocalSelectionManager |
ChatView |
drawWallpaperImage = false of chatViewBackgroundModifier |
ChatLayout composable |
LocalTerminalLayout is false outside ChatView and the theme screens (below); chat item info keeps the classic look. The value applies to every ChatView of the chat: main view, member support chats and reports.
Colours: the app, user and chat themes apply as in the classic layout. Wallpaper: chatViewBackgroundModifier fills the chat with the background colour of the wallpaper (preset or custom) and omits the image.
Functions
| Function | Purpose |
|---|---|
chatTextStyle(fontSize, color) |
Terminal rows and bubbles (usesChatTypography()): line height and line height style of a text (section 4); outside chats: TextStyle.Default, so that merging it changes nothing |
terminalItemShowsSender(item, older) |
Whether a row shows the sender row (sender rule below). older: the nearest shown older item (section 3) |
sameSender(item, older) |
Private; same sender for grouping |
terminalRowGap(item, older, separated, largeGap, hasSenderRow) |
The gap above a row (section 4, item gaps): TERMINAL_PARAGRAPH_GAP or 0. Used by ChatItemsList and the theme preview |
terminalTextTop(item) |
The top padding of CIMarkdownText (section 4) |
terminalCardTop(item) |
TERMINAL_PARAGRAPH_GAP above the first card of the content (an image, video, link preview, chat link card, file, voice message or large emoji) when a header or the quote is above it, otherwise 0 |
terminalQuoteTop(item) |
TERMINAL_PARAGRAPH_GAP above the quote below a report, deletion or live header, otherwise 0 |
terminalReactionsGap(item) |
gapBelowCard of ItemWithMeta for FramedItemView, EmojiItemView and CIVoiceView: TERMINAL_PARAGRAPH_GAP when the item has reactions, otherwise 0 |
terminalShowsStatus(status, showTimestamp) |
Whether a terminal row draws the status: with the time only for SndNew, RcvNew, RcvRead, a complete SndSent and a complete SndRcvd with an ok receipt; always for other statuses (section 4, time and status) |
ChatItem.isOneLine |
The one-line test of the row gap (section 4, item gaps) |
ChatItem.hasQuoteOrHeader |
A quote, a forwarded header, a deletion, the live state or a report: the item is drawn by FramedItemView with a quote or header above its content. Used by ChatItemView to choose EmojiItemView or CIVoiceView and by the gaps above cards and text |
CIContent.hasTerminalSender |
Also used by the event runs of bubbles (isEvent in ChatView: false and not the chat banner). True for sent messages, sent deleted and moderated items, sent calls and group invitations, and received content with showMemberName (messages, deleted, moderated and blocked items, calls, errors, group invitations, invalid JSON); false for events, feature and preference changes, E2EE info and the chat banner |
TerminalRowInteractionSource |
Interaction source of the row and its item: press interactions are emitted at the position where the pointer went down in the row, so the ripple starts there |
Modifier.terminalRowIndication(source) |
Records the pointer-down position; hover and press indication of the whole row |
Modifier.terminalStartOffset(offset) |
Shifts the row by the selection offset and narrows it by the same amount |
Modifier.messageLastLine(), Modifier.messageCard() |
messageLastLine() sets the private alignment lines LastLineLeft and LastLineRight to the left and right edges of the element: emoji, and the last code block, table or rule of a message without a meta line. messageCard() sets the private alignment lines CardTop and CardBottom to the top and bottom edges of a card (section 4, cards) |
Modifier.inlineIcon() |
Terminal: lays the element out with no height, centred on its position, so that a row with Alignment.CenterVertically takes the height of its text and centres the element on it: icons of feature and preference items and of message headers. Also in bubbles; outside chats: the modifier unchanged |
ItemWithMeta(meta, overlayMeta, metaReserved, endButton, gapBelowCard, content) |
Classic: content with the meta passed as inlineMeta. Terminal: content without meta, and the meta in a box with 12dp end padding at the end of the available width, the row (private TerminalMetaLayout). endButton, in a box with the same end padding, is placed at the end of the row, centred vertically between the content top and the top of the time box (the whole content when the time is over media); the content is measured in the width less the wider of this box and, without metaReserved, the time box. The meta is measured first. Without metaReserved and overlayMeta, the content is measured in the width less the width of the box, so that it does not reach under the time. metaReserved is true for content with its own reserve of the space or a reported last line: text with the transparent copy (metaReserved of FramedItemView), files, emoji and event items. The first baseline of the box (the baseline of the time; without a time, the baseline of a 12sp time centred in the box) is placed on the last baseline of the content. When the content reports its last line and the line and the box together are wider than the row, the box is placed TERMINAL_META_GAP (6sp) under the content and the bottom of the row moves down by that gap and the height of the box. When the content reports a card at its bottom (CardBottom at the content height), gapBelowCard is added below the content (section 4, cards). Content without a baseline (a message of a rule only, a failed call), and captionless media with overlayMeta: the box ends TERMINAL_META_GAP above the content bottom; when the content and the box together are wider than the row, the overlayMeta box is placed at the bottom end of the content instead, TERMINAL_META_GAP above its bottom. Either box is placed at the top of the content at most, and the row is at least as tall as the box. When the rule leaves room for the time beside it, the time stays on the baseline of the last text line above it (D24); otherwise it is placed under the rule. |
ChatItemSender |
Name, badge, role label, own, avatar |
chatItemSender(chatInfo, cItem, range, reversedChatItems, showMemberInfo, showChatInfo) |
Sender of a row (table below) |
SenderNameAndRole(sender, modifier) |
Private; name and badge (the body1 size, semibold; primary for own items, secondary otherwise; user) and role label (the same size, medium, secondary) |
terminalGutter(chatInfo) |
The start of the message column: in groups TERMINAL_MEMBER_IMAGE_SIZE (27dp, scaled by fontSizeSqrtMultiplier) plus TERMINAL_AVATAR_GAP less TERMINAL_AVATAR_OVERSHOOT, 35dp, so that the text starts at 47dp; 0 in other chats |
TerminalChatItemRow(sender, gutter, topGap, modifier, content) |
Row layout below; constants TERMINAL_MEMBER_IMAGE_SIZE, TERMINAL_AVATAR_OVERSHOOT and TERMINAL_AVATAR_GAP (L400-L402) |
In ChatView.kt, shared with the classic date separator:
| Function | Purpose |
|---|---|
terminalRowsSeparated(olderRow) |
A date separator or the chat banner between a row and the older row: the newest item of the older row is the banner, or the separation of the older row (rowItemSeparation(row, terminal)) has a date. False without an older row. The older row is the row of the nearest shown older item (MergedItems.olderShownRow(row)) |
rowItemSeparation(row, terminal) |
Private; the separation of a row, also used by ChatItemsList for the date separator it draws: getItemSeparation of the newest item of the row and the nearest shown newer item (the oldest item of the newer shown row) when the row is revealed (MergedItem.revealed: a single item or a revealed group row), without the newer item otherwise (user, D32). In bubbles ChatItemsList applies the event run gap to it (section 4, Bubbles) |
getItemSeparation(chatItem, prevItem, terminal) |
Private; the time, the large gap and the date between an item and the newer item prevItem. The time is hidden when the newer item has the same sender, is less than 60 seconds newer and shows the same minute; in terminal rows it stays shown when the newer item has deleted, moderated or blocked content (isDeletedContent) or is marked deleted (meta.itemDeleted), although its card shows its own time (user). Bubbles keep this grouping: a bubble before a deleted item in the same minute shows no time |
Row Layout
sender row the name line topGap (terminalRowGap) below the row top, as on master (user: "no changes in text layout");
the avatar centred on it, reaching into the gap above when it is taller than the name line; the row
is as tall as the lower of the item bottom and the avatar bottom
avatar TERMINAL_MEMBER_IMAGE_SIZE × fontSizeSqrtMultiplier, drawn to the edge of its box; sender rows of groups only;
at CHAT_ITEM_TEXT_PADDING − TERMINAL_AVATAR_OVERSHOOT (10dp), 2dp into the screen padding, as round
glyphs pass flat ones (user)
name name and badge (body1 size, semibold; primary for own messages, secondary otherwise), role label (the
same size); start padding CHAT_ITEM_TEXT_PADDING; text style chatTextStyle(body1 size); at the
message column, terminalGutter(chatInfo), so in groups it starts TERMINAL_AVATAR_GAP (10dp) after the
avatar, at 47dp; in the width less the column
one padding 12dp (user, I26): screen edge to the text in chats without avatars, time to the screen edge
item ChatItemView in the message column: at terminalGutter(chatInfo) in the width less it, so that its 12dp
text edge is at 47dp in groups and at 12dp in other chats, for every row, with or without a sender row;
at the bottom of the name line, TERMINAL_PARAGRAPH_GAP lower when the item reports a card at its top
(CardTop at 0); at topGap in a row without a sender row; media take the column's width (FlatMediaWidth)
row height the lower of the item's bottom and the avatar's bottom
ChatItemsList passes showAvatar = terminalItemShowsSender(item, merged.oldest().nextItem), the nearest shown older item, and the row gets chatItemSender(...) when it is true, null otherwise; the gap above the row, with terminalRowsSeparated of the row of that item (MergedItems.olderShownRow), is passed to ChatViewListItem as terminalGap.
Sender Rule
terminalItemShowsSender: a row shows the sender row when the item has a sender (hasTerminalSender) and one of these holds:
- it is the oldest loaded item, hidden items not counted;
- the older item has no sender (an event);
sameSenderis false;- the item is
TERMINAL_NAME_REPEAT_SECONDS(450, 7.5 minutes; user) or more after the older item, by the shown times (itemTs; the 60-second gap comparescreatedAt).
A date change does not repeat the sender row.
sameSender: when either item is posted as the channel (ChannelRcv, or GroupSnd with meta.showGroupAsSender), both must be; two GroupRcv items need the same memberId; other items need the same direction class.
Sender Resolution
| Direction | Name and badge | Role label | Avatar | Avatar click | Own colour |
|---|---|---|---|---|---|
ChannelRcv, GroupSnd with showGroupAsSender |
Channel name | "channel" (channel_role_label) |
ProfileImage of the group, toEdge |
showChatInfo |
For GroupSnd |
DirectRcv |
Contact display name and badge | None | None | None | No |
GroupRcv |
memberNames of the merged members; badge for one member |
Member role when above Member, for one member |
MemberImage, toEdge |
showMemberInfo |
No |
GroupSnd |
groupInfo.membership display name and badge |
Membership role when above Member |
MemberImage(membership), toEdge |
None | Yes |
| Other, incognito chat | "Incognito" | None | None | None | Yes |
Other (DirectSnd, LocalSnd, LocalRcv) |
Current user display name and badge | None | None | None | Yes |
The sender row has no time; the time of every item is placed by ItemWithMeta.
Row Background
| State | Background |
|---|---|
| Selected (selection mode) | primary at 10% |
Highlighted (highlightedItems contains the item, e.g. after jumping to a quoted message) |
primary at 14% |
| Otherwise | Transparent |
Hover and press are drawn by terminalRowIndication over the whole row.
Go-to Button
GoToItemButton is activated by the row hover (parentActivated; the row interaction source is passed as bubbleInteractionSource).
- Search results: the search icon is drawn by
ChatItemViewafter the item, as for classic received items: at the end of the row, centred on the item; every row of the results is narrowed by the button and its 13dp start padding, so their times stay aligned. - Forwarded items drawn by
FramedItemView: the arrow is passed asendButtonand placed byItemWithMetaat the end of the row, centred on the item above the line with the time (the forwarded header line for a one-line message); the text is narrowed by the arrow, and the time keeps its place. - Forwarded items shown as marked deleted (
markedDeleted, no header line): the arrow after the item, as in search results.
Selection and Swipe
The selection checkbox (8dp start padding) and the full-row selection click overlay are shared with the classic layout. The row is moved by Modifier.terminalStartOffset for sent and received items alike. Swipe to reply uses the swipeableModifier of the classic layout on the whole row (Android; off in selection mode).
Theme Screens
LocalTerminalLayout is provided to the theme screens of a terminal chat or profile:
| Screen | Value |
|---|---|
Chat theme (ChatWallpaperEditorModal) |
activeChatLayout of the chat |
Appearance › Themes, preset selector (ThemesSection) |
profileChatLayout of the current user, or of none for the app theme destination |
| Customize theme, profile theme, colour editors | the same, through profileLayoutIsTerminal and the terminal parameter of editColor |
With the value true:
- the preview draws two terminal rows ("alice", then "bob" in the own colour) without gutter, the gap between them by
terminalRowGap, as in the chat;PreviewInEitherLayoutmeasures both layouts and shows the active one centred in the larger height, so a layout switch keeps the preview height; - the preview and the preset tiles show the wallpaper colour without the image;
- the custom image tile, the image scale, the scale slider and the wallpaper accent row are hidden.
Layout controls:
| Control | Values | Stored in |
|---|---|---|
Chat theme screen, first section (ChatLayoutSection) |
the chat default, "(chat)" when the chat layout is the default, otherwise "(default)"; the other layout | chat theme record, by setChatLayout and apiSetChatUIThemes |
Appearance › Themes, app theme destination (ChatLayoutRow) |
Classic, Terminal; the selection is profileChatLayout(null) |
appPrefs.chatLayout |
| Appearance › Themes, profile destination | profileChatLayout(null) "(default)"; the other layout |
profile theme record, by saveThemeToDatabase and apiSetUserUIThemes |