UI navigation, theme shell, and component foundation
Overview
This doc covers the Java UI shell rooted in TMessagesProj/src/main/java/org/telegram/ui/ActionBar/**, Components/**, Cells/**, Adapters/**, Delegates/**, Storage/**, LNavigation/**, the top-level Theme*.java screens, and the primary screen entry points DialogsActivity.java, ProfileActivity.java, ContactsActivity.java, LanguageSelectActivity.java, WallpapersListActivity.java, ArticleViewer.java, PhotoViewer.java, and BasePermissionsActivity.java.
The navigation model is not AndroidX Fragment-based. Screens extend org.telegram.ui.ActionBar.BaseFragment, which owns a fragmentView, an ActionBar, a currentAccount, a generated classGuid, an optional Theme.ResourcesProvider, and lifecycle hooks such as onFragmentCreate, createView, onResume, onPause, onFragmentDestroy, onTransitionAnimationStart/End, and getThemeDescriptions. BaseFragment also exposes account-scoped controllers (MessagesController, MessagesStorage, ContactsController, MediaDataController, ConnectionsManager, etc.) so UI code can reach chat, storage, contacts, notification, and network state without passing those controllers through each screen.
Navigation containers implement org.telegram.ui.ActionBar.INavigationLayout. INavigationLayout.newLayout selects between the classic ActionBarLayout and the alternate LNavigation implementation using ExteraConfig.useLNavigation; call sites should target the interface, not a concrete layout. INavigationLayout.NavigationParams carries the common routing flags: target BaseFragment, removeLast, noAnimation, delegate checking, preview mode, preview menu, and delayed-open behavior. BaseFragment.presentFragment, presentFragmentAsPreview, finishFragment, and removeSelfFromStack are thin wrappers around the parent INavigationLayout.
ActionBarLayout is the classic stack container. It keeps two LayoutContainer instances (containerView and containerViewBack) and swaps them when presenting a fragment. presentFragment checks transition state and delegate vetoes, calls fragment.onFragmentCreate, sets preview/menu flags, hides the keyboard when appropriate, attaches or creates the fragment view, attaches the fragment's ActionBar, pushes the fragment into fragmentsStack, and runs either custom fragment animation (BaseFragment.onCustomTransitionAnimation) or its built-in open/close animations. It also handles preview cards with rounded outlines and optional ActionBarPopupWindow menus, calls onBecomeFullyVisible/Hidden, and removes or pauses the previous fragment depending on removeLast and animation state. closeLastFragment, removeFragmentFromStack, showLastFragment, and rebuildAllFragmentViews are the corresponding stack maintenance paths.
LNavigation is the alternate stack container behind the same INavigationLayout API. It wraps fragment views in internal holder views, exposes an unmodifiable getFragmentStack, drives open/close/swipe progress with SpringAnimation, integrates preview blur snapshots, and can crossfade action bars while swiping. It keeps at most foreground/background holder views live and rebuilds holders through rebuildFragments. NavigationExt.backToFragment is a small helper that walks the parent layout stack, removes fragments above a matching fragment, then finishes the current top fragment.
org.telegram.ui.ActionBar.ActionBar is the per-fragment top bar. BaseFragment.createActionBar constructs it with the fragment's Theme.ResourcesProvider, sets default action bar colors from Theme.key_actionBarDefault*, and suppresses status bar occupancy in preview or bubble mode. ActionBar owns the back/menu image, title/subtitle, overlay title, search field state, normal/action-mode menus (ActionBarMenu, ActionBarMenuItem, ActionBarMenuSubItem), action-mode color sets, and drawing hooks used by LNavigation for action-bar crossfade. DrawerLayoutContainer wraps the root content and side drawer, manages status bar/window inset propagation, drawer gestures, scrim drawing, and preview drawing over the drawer. BottomSheet is the shared modal sheet base; it is a Dialog with its own container, swipe/nested-scroll dismissal, insets/navigation-bar coloring, item cells, and Theme.ResourcesProvider support.
The theme model is centralized in org.telegram.ui.ActionBar.Theme. It defines integer theme keys (Theme.key_*), global paints/drawables, chat bubble Theme.MessageDrawable, theme metadata (Theme.ThemeInfo and accents), wallpaper/background settings, selector/drawable factories, fallback keys, and theme apply/save logic. Theme.ResourcesProvider allows a fragment, preview, dialog, or sheet to override key lookup; code that creates views should pass the provider through constructors when available. ThemeDescription maps views, paints, drawables, reflection-discovered fields, and delegates to theme keys and update flags. Both ActionBarLayout.animateThemedValues and LNavigation.animateThemedValues collect each visible fragment's getThemeDescriptions, visible BottomSheet/AlertDialog theme descriptions, optionally save start colors for chat outgoing bubbles, apply the new theme, and interpolate colors into the descriptions. ThemeActivity, ThemePreviewActivity, ThemeSetUrlActivity, and WallpapersListActivity are the main user-facing theme/background routes: settings rows are built from cells, previews render chat/message samples with Theme.MessageDrawable, and wallpaper/theme changes flow back through Theme and MessagesController/MediaDataController state.
Reusable UI foundation lives in Components/** and Cells/**. Components/LayoutHelper.java is the standard factory for density-converted FrameLayout, LinearLayout, RelativeLayout, and ScrollView params with RTL-aware helpers. Components/RecyclerListView.java extends RecyclerView with Telegram-specific item click/long-click callbacks, enabled-selection adapters, empty-view handling, pinned headers/sections, fast scroll, selector drawing, multi-selection gestures, and theme-aware selector resources. Components/BackupImageView.java wraps ImageReceiver, ensures image loading only while attached, supports avatars through setForUserOrChat, and optionally manages blurred copies. Larger components include media/video controls, alerts/bulletins, emoji/sticker widgets, forum/profile/shared-media widgets, VoIP widgets, and text span helpers used by the primary screens.
Cells are custom View or FrameLayout rows that own their measurement, drawing, theme colors, and public setters. Simple settings rows such as Cells/TextCell.java compose SimpleTextView, animated value text, an icon, optional value icon, and Switch, with theme keys selected from dialog or window palettes. Heavy rows such as Cells/DialogCell.java draw chat list content directly from MessagesController, MessagesStorage, MessageObject, TLRPC users/chats, forum topics, reactions, counters, message status, avatar/image receivers, and swipe affordances. Because cells are reused across screens and adapters, they usually expose setters for semantic state instead of relying on Android XML resources.
Adapters under Adapters/** bridge controller state into cells. DialogsAdapter is representative: it extends RecyclerListView.SelectionAdapter, owns view-type constants for dialog, hint, archive, empty, header, user, shadow, and requirements rows, computes stable internal items from MessagesController dialog data and hints, and binds DialogCell, TextCell, UserCell, HeaderCell, and loading/empty cells. Other adapters (ContactsAdapter, SearchAdapter, DialogsSearchAdapter, MessagesSearchAdapter, MentionsAdapter, sticker/location adapters) follow the same pattern: they are UI-facing projections of messenger/controller state into RecyclerListView cells.
The primary screens organize the app around this shell. DialogsActivity is the chat-list hub; it extends BaseFragment, observes NotificationCenter, owns paged dialog lists, search adapters, folders/tabs, drawer cells, and routes selections into chat/profile/theme flows through presentFragment. ProfileActivity is the user/chat/channel profile surface; it imports chat, contact, media, notification, shared media, and premium components, and routes actions to contacts, dialogs, profile settings, and shared-media views. ContactsActivity loads and observes contacts, supports selection/delegate modes, secret chat creation, permission prompts, and contact search using ContactsAdapter/SearchAdapter. LanguageSelectActivity is a compact example of the common fragment pattern: configure action bar/search item, build a FrameLayout, attach RecyclerListView with normal/search adapters, and react to global language notifications. ArticleViewer and PhotoViewer are large viewer surfaces that are owned by this doc because they build their own action bars, overlays, selection/action modes, recycler/view-pager surfaces, media players, and theme-aware controls rather than living under a narrower screen module. BasePermissionsActivity is the non-fragment permission result shell; it translates request codes into themed AlertDialog permission explanations and controller side effects such as ImageLoader.checkMediaPaths, contact import, camera init, and location permission notifications.
Delegates/** contains UI delegates that are not full fragments but attach to fragments or chat screens. MemberRequestsDelegate builds the member request list UI inside a provided fragment/container, uses MemberRequestsController, RecyclerListView, MemberRequestCell, and ProfileActivity/MemberRequestsActivity routing. ChatActivityMemberRequestsDelegate builds the chat top-panel entry point for pending join requests, themes it from the owning fragment, and opens MemberRequestsBottomSheet. Storage/CacheModel.java is a UI model for cache-control selection state: it groups file entities by media type/dialog, tracks selected file/dialog IDs and selected sizes, and depends on CacheControlActivity entity/type classes.
Coupling
- If navigation behavior changes, update both ActionBarLayout.java and LNavigation.java through the INavigationLayout.java contract. Screens call
BaseFragment.presentFragmentand may run under either implementation becauseINavigationLayout.newLayoutswitches onExteraConfig.useLNavigation. - If a new
BaseFragmentneeds animated theme changes, implementgetThemeDescriptionsin that fragment and any visibleBottomSheet/AlertDialogit owns.ActionBarLayout.animateThemedValuesandLNavigation.animateThemedValuesonly interpolate views returned by those descriptions; directTheme.getColorusage in unlisted child views will not update until a rebuild. - If a view or cell accepts a
Theme.ResourcesProvider, pass the owning fragment's provider through all nested components.BaseFragment.createActionBar,TextCell,RecyclerListView,BottomSheet, member-request delegates, and theme preview screens all rely on provider-aware color lookup for previews and per-chat/theme overrides. - If stack manipulation removes or reorders fragments manually, preserve lifecycle symmetry:
onFragmentCreatemust be paired withonFragmentDestroy, visible fragments must be resumed/unpaused, and detached views must go throughclearViews/setParentLayout. BothActionBarLayoutandLNavigationalso notifyImageLoaderor their stack listeners when the stack changes. - If a screen uses
BaseFragment.currentAccountor controller getters, set the account beforecreateView;BaseFragment.setCurrentAccountthrows oncefragmentViewexists, and controller getters bind toAccountInstance.getInstance(currentAccount). - If row or adapter view types change in Adapters/DialogsAdapter.java, verify every
DialogCell/UserCell/empty/header binding and selection offset helper such asfixPosition;DialogsActivityrelies on adapter positions for opening chats, folder/archive behavior, and search/list transitions. - If drawer, preview, or action-bar status-bar handling changes, verify DrawerLayoutContainer.java,
ActionBarLayout.LayoutContainer,LNavigationholder drawing, andBaseFragment.createActionBar. These classes share assumptions aboutAndroidUtilities.statusBarHeight,ActionBar.shouldAddToContainer, preview mode, bubble mode, and insets. - If permission request codes are added in UI screens, update
BasePermissionsActivity.checkPermissionsResultso denied permissions show the correct themed explanation and granted permissions trigger the necessary controller side effects.
Risks
INavigationLayout.newLayoutcan swap ActionBarLayout.java for LNavigation.java at runtime viaExteraConfig.useLNavigation. A fix tested against only one implementation can leave the other with different stack mutability, preview behavior, or lifecycle ordering.ActionBarLayout.animateThemedValuesandLNavigation.animateThemedValuestemporarily clear/recreate fragment views and disable delegates while interpolatingThemeDescriptioncolors. If a fragment keeps external references to old child views, theme switching can leave stale references or missed updates.- ThemeDescription.java can update class fields by reflected field names and caches missing fields. Renaming a paint/drawable field inside a cell or component without updating the corresponding theme description silently stops recoloring that element.
- DialogCell.java draws much of the chat list manually from controller/message state instead of using child views. Changes to
MessagesControllerdialog data,MessageObjectflags, forum topic fields, or theme keys can break chat list rendering without adapter compile errors. - BackupImageView.java requires
setBlurAllowed(true)before attachment and beforesetHasBlur(true). Enabling blur after attach throws, so cells that add blurred avatars/previews must configure blur before the view enters the hierarchy.