The Terminal Page is the primary UI container component in Windows Terminal that manages tabs, panes, and the overall terminal interface. It serves as the central coordinator for user interaction, command execution, and window management, enabling users to interact with multiple terminal instances within a single window.
For information about the tab and pane management systems specifically, see Tab and Pane Management.
TerminalPage is the main UI orchestrator in Windows Terminal, implemented in src/cascadia/TerminalApp/TerminalPage.h and src/cascadia/TerminalApp/TerminalPage.cpp It coordinates between the settings system, action dispatch mechanism, tab management, and UI components. The class is responsible for:
The page maintains two critical dispatch objects:
_actionDispatch: A ShortcutActionDispatch instance that handles action execution_bindings: An AppKeyBindings instance that maps key chords to actionsTerminalPage Component Structure
Sources:
Two objects above TerminalPage form the XAML application foundation for each terminal process.
App (src/cascadia/TerminalApp/App.h src/cascadia/TerminalApp/App.cpp) is the Windows::UI::Xaml::Application subclass that bootstraps the XAML environment. Its IDL surface (src/cascadia/TerminalApp/App.idl) exposes two members: Logic (the singleton AppLogic instance) and IsDisposed.
App::Initialize() registers XAML metadata providers for the terminal control library (Microsoft::Terminal::Control) and the WinUI library (Microsoft::UI::Xaml). It also calls WindowsXamlManager::InitializeForCurrentThread() to set up XAML Islands for the process thread. High-contrast automatic adjustment is disabled globally so the terminal takes full control of its color rendering.
App::PrepareForSettingsUI() is a deferred step called on demand before showing the settings editor. It registers the settings editor's XAML metadata provider lazily, avoiding loading that assembly when the settings UI is never opened.
App::Logic() returns a static singleton AppLogic instance — the same object on every call. AppLogic acts as the business logic layer between the XAML application and per-window TerminalPage instances. It owns settings management (CascadiaSettings loading and reloading), window creation and tracking, elevation status (IsRunningElevated()), and drag-and-drop policy (CanDragDrop()).
TerminalPage accesses AppLogic at runtime through Application::Current().as<TerminalApp::App>().Logic(). This pattern appears in TerminalPage::IsRunningElevated() and TerminalPage::CanDragDrop() src/cascadia/TerminalApp/TerminalPage.cpp296-316
Application Object Hierarchy
Sources:
The Terminal Page is responsible for:
Sources:
The Terminal Page is built using XAML and contains several key UI components:
| Component | Description |
|---|---|
TabRow | Container for the tab strip and tab-related controls |
TabView | UI component that displays and manages tabs |
TabContent | Container for the active tab's content |
NewTabButton | Button for creating new tabs |
CommandPalette | UI for executing commands via text input |
Dialogs | Various dialog boxes for user interactions |
The TerminalPage class also contains a number of important internal member variables:
| Member | Type | Purpose |
|---|---|---|
_tabs | Observable vector | Stores all open tabs |
_mruTabs | Observable vector | Most recently used tabs |
_tabView | TabView | UI control for tab management |
_settings | CascadiaSettings | Application settings |
_actionDispatch | ShortcutActionDispatch | Handles dispatching actions |
_bindings | AppKeyBindings | Manages keyboard shortcuts |
Sources:
The Terminal Page initialization process follows these key steps:
Create() initializes UI components and bindings_OnFirstLayout() is called once the UI is rendered to process startup actionsProcessStartupActions() handles any commands passed via commandlineDuring initialization, the Terminal Page:
Sources:
While detailed tab and pane management is covered in Tab and Pane Management, TerminalPage provides the high-level orchestration for tab operations.
Tab Creation Flow
The _OpenNewTab() method src/cascadia/TerminalApp/TabManagement.cpp64-93 is the primary entry point, called by action handlers like _HandleNewTab and _HandleSplitPane.
TerminalPage maintains several collections for tab tracking:
| Collection | Type | Purpose |
|---|---|---|
_tabs | IObservableVector<Tab> | All tabs in display order |
_mruTabs | IObservableVector<Tab> | Most-recently-used order for tab switching |
_tabView.TabItems() | XAML collection | Actual UI tab strip items |
Tab indices are synchronized across these collections through _UpdateTabIndices() src/cascadia/TerminalApp/TabManagement.cpp794-804
In _RegisterTabEvents() src/cascadia/TerminalApp/TerminalPage.cpp2450-2589 the page subscribes to tab events:
CloseRequested: Forwarded to _HandleCloseTabRequested()ColorSelected, ColorCleared: Update tab visual appearanceTabRaiseVisualBell: Propagated to app host for window flashingDuplicateRequested: Triggers _DuplicateTab()SplitTabRequested: Initiates pane splittingThis event-driven model decouples tabs from TerminalPage, allowing tabs to request operations that the page orchestrates.
Sources:
The action dispatch system is the core mechanism by which TerminalPage responds to user commands. It bridges user input (keyboard shortcuts, command palette commands) to concrete action handlers.
Action Dispatch Flow
ShortcutActionDispatch (src/cascadia/TerminalApp/ShortcutActionDispatch.h) is a WinRT event-based dispatcher. For each action listed in src/cascadia/TerminalSettingsModel/AllShortcutActions.h it exposes a corresponding WinRT event (e.g., NewTab, SplitPane, CloseTab, and so on).
Behavioral properties:
ShortcutAction enum valuesDoAction(ActionAndArgs) fires the event matching the action enum value, delivering an ActionEventArgs to all registered handlersDoAction(sender, ActionAndArgs) passes an originating sender object (e.g., a specific TermControl or Tab) so handlers can operate on that control rather than defaulting to the currently focused one — used when an action is triggered contextually from a tab's context menu or a control eventTerminalPage is the primary subscriber for all action events. The HOOKUP_ACTION macro at src/cascadia/TerminalApp/TerminalPage.cpp52 expands for each action into a subscription that wires _actionDispatch's event for that action to the corresponding TerminalPage::_Handle<ActionName> method. _RegisterActionCallbacks() src/cascadia/TerminalApp/TerminalPage.cpp1820-1960 calls this macro for all ~80 registered actions.
TerminalPage uses the HOOKUP_ACTION macro to register its handlers during initialization:
In _RegisterActionCallbacks() src/cascadia/TerminalApp/TerminalPage.cpp1820-1960 the page registers approximately 80 action handlers:
This macro expands to register a member function as the handler. For example, HOOKUP_ACTION(NewTab) connects _HandleNewTab to the NewTab action in _actionDispatch.
Actions can carry arguments defined in src/cascadia/TerminalSettingsModel/ActionArgs.h These are strongly-typed argument objects that specify parameters for actions:
| Argument Type | Used By Actions | Key Properties |
|---|---|---|
NewTerminalArgs | NewTab, SplitPane | Profile, Commandline, StartingDirectory, TabTitle |
SplitPaneArgs | SplitPane | SplitDirection, SplitSize, ContentArgs |
ResizePaneArgs | ResizePane | ResizeDirection |
MoveFocusArgs | MoveFocus | FocusDirection |
SwitchToTabArgs | SwitchToTab | TabIndex |
CopyTextArgs | CopyText | SingleLine, CopyFormatting, DismissSelection |
Arguments are deserialized from JSON in settings, passed through keybindings, and validated before handlers execute.
Action handlers in TerminalPage follow a consistent pattern:
ActionEventArgs.ActionArgs() to the expected typeargs.Handled(true) if successful, false otherwiseExample from src/cascadia/TerminalApp/AppActionHandlers.cpp459-478:
The _HookupKeyBindings() method src/cascadia/TerminalApp/TerminalPage.cpp1912-1924 connects the settings' ActionMap to _bindings:
AppKeyBindings (src/cascadia/TerminalApp/AppKeyBindings.h) implements the IKeyBindings interface from the terminal control library. It is the bridge between raw keyboard input captured by XAML and the action dispatch system.
The key chord resolution path in TryKeyChord() src/cascadia/TerminalApp/AppKeyBindings.cpp15-22:
KeyChord (modifier flags + virtual key) arrives at AppKeyBindings::TryKeyChord()_actionMap.GetActionByKeyChord(kc) queries the current IActionMapView for a matching CommandCommand is found, _dispatch.DoAction(cmd.ActionAndArgs()) fires the action on the ShortcutActionDispatchTryKeyChord() returns false, allowing the key event to propagate normally to the terminal controlAppKeyBindings holds two dependency references:
_actionMap (IActionMapView) — provides the chord → ActionAndArgs lookup table derived from CascadiaSettings_dispatch (ShortcutActionDispatch) — executes the resolved actionBoth references are injected via SetActionMap() and SetDispatch() during _HookupKeyBindings().
AppKeyBindings Key Chord Resolution Flow
Sources:
The complete list of actions is defined in src/cascadia/TerminalSettingsModel/AllShortcutActions.h26-93 Key action categories include:
| Category | Actions |
|---|---|
| Tab Operations | NewTab, DuplicateTab, CloseTab, SwitchToTab, NextTab, PrevTab, RenameTab, MoveTab |
| Pane Operations | SplitPane, ClosePane, ResizePane, MoveFocus, SwapPane, TogglePaneZoom, MovePane |
| Content Operations | CopyText, PasteText, SendInput, SelectAll, Find, ClearBuffer |
| Scrolling | ScrollUp, ScrollDown, ScrollUpPage, ScrollDownPage, ScrollToTop, ScrollToBottom, ScrollToMark |
| Window State | ToggleFullscreen, SetFullScreen, ToggleFocusMode, SetFocusMode, ToggleAlwaysOnTop |
| UI Controls | ToggleCommandPalette, OpenNewTabDropdown, OpenTabColorPicker, OpenSettings |
Sources:
The Terminal Page consumes settings from the CascadiaSettings object to configure the terminal UI and behavior:
Settings Application Pipeline
The SetSettings() method src/cascadia/TerminalApp/TerminalPage.cpp268-294 is called when:
Key operations performed:
TerminalSettingsCache for efficient settings lookup_RefreshUIForSettingsReload() to update visible UI elementsThe settings object is stored in _settings and queried throughout the page's lifetime for:
_OpenNewTab() via GetProfileForArgs()_UpdateTabView()_actionDispatchSources:
The Terminal Page hosts several UI components:
The command palette provides a keyboard-driven interface for executing commands. It is shown/hidden by the TerminalPage based on user actions.
The new tab dropdown is populated from profile data in settings, allowing users to create new tabs with specific profiles.
The Terminal Page manages various dialogs:
| Dialog | Purpose |
|---|---|
AboutDialog | Displays application information |
QuitDialog | Confirms application exit |
CloseAllDialog | Confirms closing multiple tabs |
MultiLinePasteDialog | Confirms multi-line paste operations |
LargePasteDialog | Confirms large paste operations |
ControlNoticeDialog | Displays terminal control notices |
Sources:
The Terminal Page manages several window states:
| State | Property | Methods |
|---|---|---|
| Focus Mode | _isInFocusMode | ToggleFocusMode(), SetFocusMode() |
| Fullscreen | _isFullscreen | ToggleFullscreen(), SetFullscreen() |
| Always on Top | _isAlwaysOnTop | ToggleAlwaysOnTop() |
| Maximized | _isMaximized | Maximized(), RequestSetMaximized() |
The page raises events for window state changes, which are handled by the application host:
Sources:
The Terminal Page raises and handles numerous events to coordinate with the application and UI:
| Event | Purpose |
|---|---|
Initialized | Signals page initialization is complete |
CloseWindowRequested | Requests window closure |
SetTitleBarContent | Updates titlebar content |
FocusModeChanged | Signals focus mode state changes |
FullscreenChanged | Signals fullscreen state changes |
AlwaysOnTopChanged | Signals always on top state changes |
RaiseVisualBell | Signals terminal bell activation |
SetTaskbarProgress | Updates taskbar progress |
Sources:
The Terminal Page is the central UI component of Windows Terminal that manages tabs, panes, and user interactions. It coordinates the display of terminal content, processes user commands, and manages window state. The page connects the user interface to the underlying terminal engine and provides features like tab management, pane splitting, and command execution through keyboard shortcuts or the command palette.
Refresh this wiki
This wiki was recently refreshed. Please wait 4 days to refresh again.