Understanding Windows Console Host Settings
Welcome to the first of several posts that describe some of the inner workings of the Windows Console.
Settings in the Windows Console Host can be a bit tricky to understand. This is mostly because the settings system evolved over the course of decades. Settings are persisted to/from a variety of locations depending on how the Windows Console Host was invoked.
The hierarchy of loaded settings
Where a Console’s settings are loaded-from and/or persisted-to is decided upon based upon the following hierarchy:
- Hardcoded settings in conhostv2.dll
- User’s configured Console defaults, stored as values in ‘HKCU\Console’
- Per-Console-application registry settings, stored as sub-keys of ‘HKCU\Console\
‘ using one of two sub-key names:
- Console application path (replacing ‘\’ with ‘_’)
- Console title
- Windows shortcut (.lnk) files
When Console applications are launched, the Windows Console Host determines which settings to use by loading the Console details, and overlaying settings from the hierarchy in order. Each setting will take on the value of whatever is loaded last, and so values in a Windows shortcut (#4) will override values set in the user’s configured defaults (#2).
This hierarchy explains why each Console window has a ‘Defaults’ option and a ‘Properties’ option inside of its title bar menu:
When modifying ‘Defaults’, changes are written to the User’s configured defaults, stored as values in ‘HKCU\Console’, (#2 in the hierarchy above).
When modifying ‘Properties’, changes will be persisted to either the per-Console-application settings in the registry, or to the Windows shortcut file:
- If the application was launched directly (e.g. via the Windows run dialog), changes will be persisted in the per-application storage location mentioned above (#3 in the hierarchy).
- If the application was launched via a Windows shortcut file, changes will be persisted directly into the .lnk file (the fourth item in the hierarchy). For Console applications with a shortcut, you can also right-click on the shortcut file itself and choose ‘Properties’ to access the settings dialog.
When Console applications are launched, the Windows Console Host determines which settings to use by overlaying settings from the hierarchy in order, starting with the hardcoded defaults. This means that a Windows Console shortcut with settings information inside of it will override the application storage and default settings.
Note that the registry settings are “sparse”, meaning that if a setting isn’t present, then whatever value that is already in use remains unchanged. This allows users to have some settings shared amongst all Console applications and other settings be specific.
Shortcut files, however, store each setting regardless of whether it was a default setting or not. Settings are stored in shortcuts as opaque blobs of data.
Here’s a full list of every setting for the Windows Console, including a quick description on what it does.
|FontSize||Coordinate (REG_DWORD)||Size of font in pixels|
|FontFamily||REG_DWORD||GDI Font family|
|ScreenBufferSize||Coordinate (REG_DWORD)||Size of the screen buffer in WxH characters|
|CursorSize||REG_DWORD||Cursor height as percentage of a single character|
|WindowSize||Coordinate (REG_DWORD)||Initial size of the window in WxH characters|
|WindowPosition||Coordinate (REG_DWORD)||Initial position of the window in WxH pixels (if not set, use auto-positioning)|
|WindowAlpha||REG_DWORD||Opacity of the window (valid range: 0x4D-0xFF)|
|ScreenColors||REG_DWORD||Default foreground and background colors|
|PopupColors||REG_DWORD||FG and BG colors used when displaying a popup window (e.g. when F2 is pressed in CMD.exe)|
|QuickEdit||REG_DWORD||Whether QuickEdit is on by default or not|
|FaceName||REG_SZ||Name of font to use (or “__DefaultTTFont__”, which defaults to whichever font is deemed most appropriate for your codepage)|
|FontWeight||REG_DWORD||GDI font weight|
|InsertMode||REG_DWORD||Whether Insert mode is on by default or not|
|HistoryBufferSize||REG_DWORD||Number of history entries to retain|
|NumberOfHistoryBuffers||REG_DWORD||Number of history buffers to retain|
|HistoryNoDup||REG_DWORD||Whether to retain duplicate history entries or not|
|ColorTable%%||REG_DWORD||For each of the 16 colors in the palette, the RGB value of the color to use|
|ExtendedEditKey||REG_DWORD||Whether to allow the use of extended edit keys or not|
|WordDelimiters||REG_SZ|| A list of characters that are considered as delimiting words (e.g. |
|TrimLeadingZeros||REG_DWORD|| Whether to remove zeroes from the beginning of a selected string on copy (e.g. |
|EnableColorSelection||REG_DWORD||Whether to allow selection colorization or not|
|ScrollScale||REG_DWORD|| How many lines to scroll when using |
|CodePage||REG_DWORD||The default codepage to use|
|ForceV2||REG_DWORD||Whether to use the improved version of the Windows Console Host|
|LineSelection*||REG_DWORD||Whether to use wrapped text selection|
|FilterOnPaste*||REG_DWORD||Whether to replace characters on paste (e.g. Word “smart quotes” are replaced with regular quotes)|
|LineWrap||REG_DWORD||Whether to have the Windows Console Host break long lines into multiple rows|
|CtrlKeyShortcutsDisabled||REG_DWORD||Disables new control key shortcuts|
|AllowAltF4Close||REG_DWORD||Allows the user to disable the Alt-F4 hotkey|
|VirtualTerminalLevel||REG_DWORD||The level of VT support provided by the Windows Console Host|
*Only applies to the improved version of the Windows Console Host
As with most complex things, there are a few gotcha’s to be aware of:
Settings get reset on OS upgrade
Whenever you upgrade to a new version of Windows, system-owned shortcuts and/or Start Menu items’ settings are reset to defaults. This means that if you customize default fonts, colors, etc., when you upgrade to a new OS build, your settings will be reset to Windows defaults.
While there are several ways in which you can set things back to your own defaults after each upgrade, most of them involve updating the registry (which should always be done with care), and most don’t handle updating shortcuts/links at all.
We’re working on a tool to make handling Console settings easier and more manageable. We’ll announce this tool here, so be sure to visit this blog regularly to be among the first to use this tool when it is released.