Introducing a new way to review your PRs.

Read the announcement

ayugram / ayugramdesktop

Desktop Telegram client with good customization and Ghost mode.

View on GitHub

13 documents · Updated Nov 16, 2026

docs / history-message-view

Chat History Message View

Overview

This area turns chat data into visible message rows and the interactions on those rows. The persistent model starts at Telegram/…/history.h: History owns a peer/thread, message blocks, unread/read state, drafts, translation state, chat-list projection, and scroll anchors. Incoming MTProto messages and locally-created outgoing messages are inserted through History::addNewMessage, History::addNewLocalMessage, and History::createItem; each produces a HistoryItem (Telegram/…/history_item.h) that stores the message id, flags, author, date, Data::Media, rich page, reply/forward/markup/reaction components, TTL state, translation component, and a back-pointer to its main visible HistoryView::Element.

HistoryItem::createView in Telegram/…/history_item.h is the model-to-view bridge. Normal messages become HistoryView::Message (Telegram/…/history_view_message.h), service messages become HistoryView::Service (Telegram/…/history_view_service_message.h), and both inherit from HistoryView::Element (Telegram/…/history_view_element.h). Element is the shared row contract: it tracks y-position, attachment to previous/next rows, date and unread bars, forum thread bars, selection conversion, text hit-testing, media ownership, reactions/reply-button parameters, deleted opacity, and repaint/resize invalidation. Message adds the bubble layout: from-name, forwarded/reply/summary blocks, media placement, rich-page text, inline keyboards, bottom info, right-side fast actions, edit badges, comments buttons, and link/ripple state. Media-specific row content is delegated to subclasses of HistoryView::Media in Telegram/…/history_view_media.h, such as the location renderer in Telegram/…/history_view_location.h, which owns map thumbnails/live-location state and uses LocationClickHandler from Telegram/…/history_location_manager.h for URL/copy/drag behavior.

There are two chat-list/viewer stacks in this tree. The newer detailed chat section is HistoryView::ChatWidget in Telegram/…/history_view_chat_section.h; it owns a HistoryView::ListWidget (Telegram/…/history_view_list_widget.h) plus top/bottom/compose controls, and implements ListDelegate so the list can ask for message slices, mark reads, open media, build context menus, provide theme/paint context, and report selection changes. ListWidget is the reusable detailed history view: it requests Data::MessagesSlice from ListDelegate::listSource, owns a map from HistoryItem* to Element, maintains scroll mementos, runs painting/visible-area updates, creates translation/read-metric trackers, handles mouse/touch/key events, selection, copy restrictions, reactions, reply buttons, and exposes edit/reply/read/show requests back to ChatWidget. The older HistoryWidget / HistoryInner path in Telegram/…/history_widget.h and Telegram/…/history_inner_widget.h still performs the same row painting and interaction work directly over History::blocks; its HistoryMainElementDelegateMixin connects HistoryItem views back to the active HistoryInner so row hit-testing, media opening, reply, selection, and context-menu actions have a live widget delegate.

Row rendering flows through the delegate interfaces rather than direct widget calls. HistoryView::ElementDelegate in Telegram/…/history_view_element.h defines everything a row can ask of its host: selection mode, whether a reply should be hidden, unread visibility, media opening, poll results, bot commands, search, author rank, topic buttons, animations, and path gradients. ListWidget, HistoryInner, and AdminLog::InnerWidget each implement this contract for their context. HistoryView::Context distinguishes main history, replies, pinned, admin log, TTL viewer, chat preview, welcome messages, and other presentations, so Message can draw/hit-test differently without owning navigation state.

Selection has both row-level and text-level layers. Full message selection is stored by the host widgets (HistoryInner keeps SelectedItems; ListWidget exposes SelectedItems and MessageIdsList), while per-message text selection uses HistoryView::MessageSelection from Telegram/…/history_message_selection.h. That type can represent flat message text or rich-page article selections, preserving anchor/focus endpoints for keyboard and drag expansion. Element and Message convert point states into MessageSelection, selected text, rich-page blocks, selected quotes, and edit ranges; the host widgets combine those results for copy, forward, delete, report, drag, and context-menu operations.

Unread and read behavior is split between history state and visible bars. History in Telegram/…/history.h tracks inbox/outbox read ids, unread counts, unread mark, first unread message, and the unread bar element. Mention/reaction/poll-vote unread lists are stored in HistoryUnreadThings::Proxy / List (Telegram/…/history_unread_things.h) and notify the owning Data::Thread. ListWidget and HistoryInner mark visible messages and contents read via their delegates; the newer stack uses ListDelegate::listMarkReadTill, listMarkContentsRead, listMessagesBar, and ReadMetricsTracker creation in Telegram/…/history_view_list_widget.cpp. The visual unread separator is an UnreadBar runtime component on any Element (Telegram/…/history_view_element.h).

Translation state also spans model and view. HistoryTranslation (Telegram/…/history_translation.h) records the language offered and the target language for a History. Individual HistoryItems can carry HistoryMessageTranslation (Telegram/…/history_item_components.h) with translated text/rich page, request status, failure status, and whether it is currently used. HistoryView::TranslateTracker (Telegram/…/history_view_translate_tracker.h) collects visible elements/items, recognizes languages, applies limits, sends MTProto translation requests, and switches item translations; HistoryView::TranslateBar (Telegram/…/history_view_translate_bar.h) is the chat-level control for target selection, hiding, settings toasts, and override state.

Admin log reuses the message view layer but swaps in a channel-event data source. AdminLog::Widget (Telegram/…/history_admin_log_section.h) owns the scroll area, fixed bar/filter controls, scroll-down button, and AdminLog::InnerWidget. AdminLog::InnerWidget (Telegram/…/history_admin_log_inner.h) implements HistoryView::ElementDelegate, loads/paginates filtered events, restores state via SectionMemento, paints HistoryView::Elements, and handles selection, context menus, and event deletion metadata. Admin-log-specific HistoryItems are created via the channel admin log path mentioned in History::createItem (Telegram/…/history.h) and can carry HistoryView::LogEntryOriginal on Message (Telegram/…/history_view_message.h) to render original content for edited/deleted event entries.

The chat list and media overview are secondary projections of the same HistoryItem model. Dialog rows use Dialogs::Row (Telegram/…/dialogs_row.h) for userpic/unread/ripple layout, while Dialogs::Ui::MessageView (Telegram/…/dialogs_message_view.h) prepares and caches sender text, preview text, preview images, mini-icons, spoiler animation, and topic jump UI from a HistoryItem. History implements the dialog entry contract in Telegram/…/history.h, exposing chat-list name, unread state, badges, top message, and userpic painting. Shared-media/detail overviews use Overview::Layout::ItemBase and subclasses in Telegram/…/overview_layout.h; they point back to a HistoryItem, paint selectable media/document tiles, register heavy items through Overview::Layout::Delegate (Telegram/…/overview_layout_delegate.h), and open photos/documents using the same FullMsgId context.

chat_helpers participates mainly at the interaction edges. The compose field and autocomplete/emoji/sticker/bot-keyboard helpers used by HistoryWidget and ChatWidget live under Telegram/SourceFiles/chat_helpers/; row inline keyboards are represented by HistoryMessageReplyMarkup and ReplyKeyboard in Telegram/…/history_item_components.h, while bot keyboard visibility, replies, edit drafts, and send/edit operations are coordinated by HistoryWidget (Telegram/…/history_widget.h) and ChatWidget (Telegram/…/history_view_chat_section.h).

Coupling

Risks

  • Telegram/…/history_view_list_widget.cpp is fragile around destruction, scrolling, and collapse animations. Recent history includes fixes for repaint requests during list destruction (53cd9c0e5), slice reload flipping jump animation (0cd09904c), out-of-bounds pinned bar tracking (1f1ad7bc6), and several collapse/scroll pin fixes (8c53eeffd, 36f4391a1, 3f6639cd1, 0ea3ac964). If row lifetime, scroll anchoring, or resize behavior changes here, test message deletion animations, jump-to-message, pinned tracking, and teardown while translations/repaints are in flight.
  • Telegram/…/history_item.cpp, Telegram/…/history.cpp, and Telegram/…/history_view_chat_section.cpp have repeated fixes for stale top/last message and topic/sublist switches (aba8ea0f4, fa863635b, 4f3da4db8, 8bcbab7f1, c6491dad0). If message movement, service editions, forum topics, replies, or saved sublists change, stale dialog previews or wrong visible roots can result.
  • Telegram/…/history_admin_log_section.h and Telegram/…/history_admin_log_inner.h are teardown-sensitive. Recent fixes mention admin-log teardown crashes (c91afffd6), resize re-entry on teardown (52f19c640), reassigned OwnedItem destruction (3a93e18ac), and a kick handler lifetime leak (d54eac4c6). If admin log pagination, filtering, or item replacement changes, verify scroll/resize during close and event deletion context actions.
  • Notification scheduling and item destruction depend on CanHoldItemNotification in Telegram/…/history_item_helpers.h. Its comment states History::destroyMessage relies on it being a superset of scheduler guards, because notification queues hold raw HistoryItem* pointers. If unread poll/reaction/mention scheduling rules change without updating this helper, destroyed items can remain queued and later crash notification delivery.