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 / window-shell-navigation-notifications

Window shell, navigation, tray, and notifications

Overview

The window area owns the desktop shell around authenticated sessions: the top-level Qt window, the per-window controller, per-session navigation state, adaptive columns, lock overlays, menus, tray integration, notifications, and theme/background application.

Telegram/…/main_window.h and Telegram/…/main_window.cpp define Window::MainWindow, the Ui::RpWindow subclass that owns the actual widget frame. It initializes native/custom title handling, the window icon/title, palette, minimum sizes, saved geometry, right-column widgets, outdated/screen-reader bars, and tray activation. Closing/minimizing is policy-driven: MainWindow::hideNoQuit() checks Core::Settings::WorkMode and close behavior, may minimize to tray, and clears the session section stack before hiding. MainWindow::showFromTray() activates the window, refreshes the global menu, and updates tray counters through Core::App().tray().updateIconCounters().

Telegram/…/window_controller.h and Telegram/…/window_controller.cpp are the per-window orchestrator. Window::Controller owns a MainWindow, an Adaptive instance, and at most one SessionController. Controller::showAccount() is the main account/session switch path: it replaces _sessionController when Main::Account::sessionValue() changes, updates the window icon/title, installs the main or intro UI, wires terms/setup-email locks, updates online state, and closes non-primary windows if their account session changes. It also exposes shell services used by the rest of the UI: showing boxes/layers/toasts, right-column widgets, passcode/setup-email locks, logout confirmation, active/blur timers, and cross-window dispatch through invokeForSessionController().

Telegram/…/window_session_controller.h and Telegram/…/window_session_controller.cpp are the session-scoped navigation hub. SessionNavigation provides link/peer/message resolution helpers over Main::Session; SessionController implements the actual UI navigation by delegating to MainWidget (content()), tracking the active chat entry, filters/folders/forums/communities, layer sections, chat themes, media openings, and separate-window requests. SessionController::showPeerHistory(), showSection(), showTopic(), showSublist(), and showMessage() route navigation into the active content widget or an existing layer. SessionController::showInNewWindow() turns a SeparateId into a separate window via Core::App().ensureSeparateWindowFor(), but falls back to in-window navigation if CanShowSeparateWindow() rejects the id.

Window identity for multi-window behavior lives in Telegram/…/window_separate_id.h and Telegram/…/window_separate_id.cpp. SeparateId encodes primary, archive, chat, forum, community, saved-sublist, and shared-media windows, including the owning account/thread. CanShowSeparateWindow() blocks windows for unavailable threads or while passcode/terms locks are active. Saved/restored window state is handled by Telegram/…/window_saved_windows.h and Telegram/…/window_saved_windows.cpp: it serializes up to bounded lists of SavedWindow/SavedChat records under local settings keys, restores shell placeholders, resolves peers/threads, recreates windows, and replays chat stacks for replayable window types.

Adaptive layout is intentionally centralized. Telegram/…/window_adaptive.h and Telegram/…/window_adaptive.cpp expose reactive WindowLayout and ChatLayout state plus the global adaptiveForWide setting. SessionController::computeColumnLayout() in window_session_controller.cpp computes one-column, normal two-column, or three-column widths from body width, filters width, style minima, stored dialogs/third-column ratios, and third-section settings. resizeForThirdSection() and closeThirdSection() temporarily adjust settings/window width so the third column can be shown or removed without silently losing ratios. Telegram/…/window_top_bar_wrap.h wraps top bars in a slide wrapper whose shadow geometry changes when the adaptive layout enters/leaves one-column mode.

Lock and setup gates are shell-level overlays. Telegram/…/window_lock_widgets.h and Telegram/…/window_lock_widgets.cpp define TryPasscode(), LockWidget, PasscodeLockWidget, and TermsBox. PasscodeLockWidget checks storage/domain passcodes, updates bad-try counters, supports platform system unlock, and calls Core::App().unlockPasscode() only after a correct passcode. LockWidget::showFinished() clears the section stack after showing the lock over prior content. Telegram/…/window_unlock_passcode_box.cpp provides a modal unlock box for actions that need passcode unlock without replacing the whole window. Telegram/…/window_setup_email.cpp provides the setup-email lock widget, using session promo-suggestion state to either show email setup controls, a busy state in secondary windows, or account/logout navigation.

Menus and account switching are part of the shell. Telegram/…/window_main_menu.cpp builds the in-app main menu layer around SessionController, account userpics, unread state from other accounts, settings/actions, scale reset, and theme/status controls. Telegram/…/tray.cpp owns the platform tray menu: it creates/destroys the tray icon based on Core::Settings::WorkMode, rebuilds menu entries when passcode/account sessions change, exposes show/hide requests, toggles desktop notifications while remembering sound/flash settings, and updates icon counters. Telegram/…/tray_accounts_menu.cpp adds per-account tray actions when multiple sessions exist; Ctrl-click opens a separate account window, while normal click activates the account in the domain. Telegram/…/tray_accounts_menu_dummy.cpp is the no-op implementation for builds without the real account tray menu.

Chat switching is handled by Telegram/…/window_chat_switch_process.h and Telegram/…/window_chat_switch_process.cpp. ChatSwitchProcess renders a transient overlay from Main::Session::recentPeers().collectChatOpenHistory(), handles keyboard requests from Shortcuts::ChatSwitchRequest, emits chosen thread/close events, and supports removing a recent entry with Q; removal closes separate windows showing that thread or clears active stacks in windows where that thread is selected.

Notifications are split into scheduling/filtering and platform/custom rendering. Telegram/…/notifications_manager.h and Telegram/…/notifications_manager.cpp define Window::Notifications::System, the global notification pipeline. System::schedule() receives Data::ItemNotification, skips hidden/duplicate/unready notifications, computes delay from online/cloud timing and notification settings, registers topic/sublist destruction watchers, schedules alert sound/bounce events, and queues desktop toasts through the active Manager. System::showNext() processes ready waiters, groups forwarded messages/albums, chooses sound IDs, calls Manager::showNotification(), and plays sound/flash-bounce through manager hooks. System::setManager() selects native, default custom, or dummy managers based on platform support, settings, and feature options.

Notifications::Manager in notifications_manager.h/.cpp defines activation/reply/action semantics shared by native and custom toasts. notificationActivated() resolves the session/history/message, optionally stores a draft reply, opens the target chat/topic/sublist in the current or separate window, clears matching notifications, and respects passcode lock by only raising the resolved window and clearing notifications. notificationReplied() sends a message through the session API with topic/sublist reply context. NativeManager::doShowNotification() composes titles, subtitles, hidden-preview behavior, custom sound callbacks, and notification actions before delegating to the platform implementation.

Telegram/…/notifications_manager_default.h and Telegram/…/notifications_manager_default.cpp implement the non-native toast stack. Default::Manager queues visible notifications up to the configured count, positions them inside NotificationDisplayRect(), tracks a hide-all button, updates on palette/settings changes, and subscribes to session downloads to refresh userpics. Each internal::Notification is a frameless always-on-top widget that renders cached title/text/userpic content, pauses hiding on hover, exposes reply UI when previews and passcode state allow it, sends replies through Manager::notificationReplied(), opens messages on left-click, and dismisses on right-click/close. Telegram/…/notifications_utilities.h and .cpp provide userpic generation and temporary PNG caching for platform notification APIs.

Theme orchestration lives under Telegram/SourceFiles/window/themes/**. window_theme.h and window_theme.cpp define the global Theme::ChatBackground, theme file parsing, palette/background application, night-mode toggling, editing/reverting, and background update events. SessionController listens to Theme::Background()->updates() to refresh chat backgrounds and validate chat-theme wallpapers. window_themes_chat.cpp adapts cloud chat themes into Ui::ChatTheme palettes, outgoing bubble data, and wallpaper application; it asynchronously downloads wallpaper documents before calling Theme::Background()->set(). Embedded/default color schemes and accent colorization are in window_themes_embedded.cpp.

Coupling

  • If SeparateType or SeparateId changes in Telegram/…/window_separate_id.h, update all serialization/restore paths in Telegram/…/window_saved_windows.cpp. ValidType(), ReplayableType(), NeedsThread(), StepSeparateId(), and the serialized kVersion stream all assume the enum shape and determine whether restored windows can be recreated or skipped.
  • If notification identity fields change, update both native activation and custom widgets: Notifications::Manager::NotificationId in Telegram/…/notifications_manager.h, Manager::openNotificationMessage() / notificationReplied() in notifications_manager.cpp, and Default::internal::Notification::myId() in notifications_manager_default.cpp must agree on sessionId, peerId, topicRootId, monoforumPeerId, and msgId or clicks/replies will open or reply to the wrong thread.
  • If tray notification toggles are changed in Telegram/…/tray.cpp, also verify Window::Notifications::System settings reactions in Telegram/…/notifications_manager.cpp. The tray toggler updates desktopNotify, remembered sound/flash settings, saves settings, and emits ChangeType::DesktopEnabled, SoundEnabled, and FlashBounceEnabled; missing an event leaves visible notifications, sounds, or unread badges stale.
  • If adaptive width settings or style minima change, check SessionController::computeColumnLayout(), resizeForThirdSection(), and closeThirdSection() in Telegram/…/window_session_controller.cpp together with MainWindow::computeMinWidth() / updateControlsGeometry() in Telegram/…/main_window.cpp. Filters and right-column widgets both subtract from available shell width and can silently make one/three-column transitions wrong.
  • If passcode or terms-lock behavior changes, verify separate-window creation and notification activation. CanShowSeparateWindow() in Telegram/…/window_separate_id.cpp blocks locked thread windows, while Manager::openNotificationMessage() in Telegram/…/notifications_manager.cpp has a separate passcode-locked path that raises an existing window and clears notifications instead of navigating.
  • If theme/background update event types change in Telegram/…/window_theme.h, update SessionController subscriptions in Telegram/…/window_session_controller.cpp. It reacts differently to New/Changed versus ApplyingTheme and primary-window-only chat wallpaper checks.

Risks

  • Telegram/…/window_saved_windows.cpp uses a compact QDataStream format with a bounded kVersion; adding fields without bumping/deserializing carefully can make saved sessions fail restore or restore to the wrong chat/window type.
  • Telegram/…/notifications_manager.cpp and Telegram/…/notifications_manager_default.cpp keep notification lifetime state in several maps/queues plus widgets that can outlive sessions during hide animations. If clear/unlink paths miss topics, sublists, or sessions, stale notifications can open deleted contexts or retain session-owned text/custom-emoji caches.
  • Telegram/…/window_session_controller.cpp stores active-chat fake unread state and cloud drafts in setActiveChatEntry(). If new navigation paths bypass this setter, the previous history can keep fake unread state or drafts may not be saved before switching chats.