config package

Manages NVDA configuration. The heart of NVDA’s configuration is Configuration Manager, which records current options, profile information and functions to load, save, and switch amongst configuration profiles. In addition, this module provides three actions: profile switch notifier, an action to be performed when NVDA saves settings, and action to be performed when NVDA is asked to reload configuration from disk or reset settings to factory defaults. For the latter two actions, one can perform actions prior to and/or after they take place.

config.isAppX = False

True if NVDA is running as a Windows Store Desktop Bridge application

config.conf

The active configuration, C{None} if it has not yet been loaded. @type: ConfigManager

config.post_configProfileSwitch = <extensionPoints.Action object>

Notifies after the configuration profile has been switched. This allows components and add-ons to apply changes required by the new configuration. For example, braille switches braille displays if necessary. Handlers are called with no arguments.

config.pre_configSave = <extensionPoints.Action object>

Notifies when NVDA is saving current configuration. Handlers can listen to “pre” and/or “post” action to perform tasks prior to and/or after NVDA’s own configuration is saved. Handlers are called with no arguments.

config.pre_configReset = <extensionPoints.Action object>

Notifies when configuration is reloaded from disk or factory defaults are applied. Handlers can listen to “pre” and/or “post” action to perform tasks prior to and/or after NVDA’s own configuration is reloaded. Handlers are called with a boolean argument indicating whether this is a factory reset (True) or just reloading from disk (False).

config.initialize()
config.saveOnExit()

Save the configuration if configured to save on exit. This should only be called if NVDA is about to exit. Errors are ignored.

class config.RegistryKey(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: str, Enum

INSTALLED_COPY = 'SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Uninstall\\NVDA'
RUN = 'SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Run'
NVDA = 'SOFTWARE\\NVDA'

The name of the registry key stored under HKEY_LOCAL_MACHINE where system wide NVDA settings are stored. Note that NVDA is a 32-bit application, so on X64 systems, this will evaluate to r"SOFTWAREWOW6432Nodenvda"

CONFIG_IN_LOCAL_APPDATA_SUBKEY = 'configInLocalAppData'

#6864: The name of the subkey stored under RegistryKey.NVDA where the value is stored which will make an installed NVDA load the user configuration either from the local or from the roaming application data profile. The registry value is unset by default. When setting it manually, a DWORD value is preferred. A value of 0 will evaluate to loading the configuration from the roaming application data (default). A value of 1 means loading the configuration from the local application data folder.

FORCE_SECURE_MODE_SUBKEY = 'forceSecureMode'
SERVICE_DEBUG_SUBKEY = 'serviceDebug'
_generate_next_value_(start, count, last_values)

Generate the next value when not given.

name: the name of the member start: the initial start value or None count: the number of existing members last_values: the list of values assigned

_new_member_(**kwargs)

Create and return a new object. See help(type) for accurate signature.

_use_args_ = True
_member_names_ = ['INSTALLED_COPY', 'RUN', 'NVDA', 'CONFIG_IN_LOCAL_APPDATA_SUBKEY', 'FORCE_SECURE_MODE_SUBKEY', 'SERVICE_DEBUG_SUBKEY']
_member_map_ = {'CONFIG_IN_LOCAL_APPDATA_SUBKEY': RegistryKey.CONFIG_IN_LOCAL_APPDATA_SUBKEY, 'FORCE_SECURE_MODE_SUBKEY': RegistryKey.FORCE_SECURE_MODE_SUBKEY, 'INSTALLED_COPY': RegistryKey.INSTALLED_COPY, 'NVDA': RegistryKey.NVDA, 'RUN': RegistryKey.RUN, 'SERVICE_DEBUG_SUBKEY': RegistryKey.SERVICE_DEBUG_SUBKEY}
_value2member_map_ = {'SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Run': RegistryKey.RUN, 'SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Uninstall\\NVDA': RegistryKey.INSTALLED_COPY, 'SOFTWARE\\NVDA': RegistryKey.NVDA, 'configInLocalAppData': RegistryKey.CONFIG_IN_LOCAL_APPDATA_SUBKEY, 'forceSecureMode': RegistryKey.FORCE_SECURE_MODE_SUBKEY, 'serviceDebug': RegistryKey.SERVICE_DEBUG_SUBKEY}
_unhashable_values_ = []
_member_type_

alias of str

_value_repr_()

Return repr(self).

config.isInstalledCopy() bool

Checks to see if this running copy of NVDA is installed on the system

config.getInstalledUserConfigPath() str | None
config.getUserDefaultConfigPath(useInstalledPathIfExists=False)

Get the default path for the user configuration directory. This is the default path and doesn’t reflect overriding from the command line, which includes temporary copies. Most callers will want the C{NVDAState.WritePaths.configDir variable} instead.

config.getScratchpadDir(ensureExists: bool = False) str

Returns the path where custom appModules, globalPlugins and drivers can be placed while being developed.

config.initConfigPath(configPath: str | None = None) None

Creates the current configuration path if it doesn’t exist. Also makes sure that various sub directories also exist. @param configPath: an optional path which should be used instead (only useful when being called from outside of NVDA)

config.getStartAfterLogon() bool

Not to be confused with getStartOnLogonScreen.

Checks if NVDA is set to start after a logon. Checks related easeOfAccess current user registry keys on Windows 8 or newer. Then, checks the registry run key to see if NVDA has been registered to start after logon on Windows 7 or by earlier NVDA versions.

config.setStartAfterLogon(enable: bool) None

Not to be confused with setStartOnLogonScreen.

Toggle if NVDA automatically starts after a logon. Sets easeOfAccess related registry keys.

When toggling off, always delete the registry run key in case it was set by an earlier version of NVDA.

config.getStartOnLogonScreen() bool

Not to be confused with getStartAfterLogon.

Checks if NVDA is set to start on the logon screen.

Checks related easeOfAccess local machine registry keys. Then, checks a NVDA registry key to see if NVDA has been registered to start on logon by earlier NVDA versions.

config._setStartOnLogonScreen(enable: bool) None
config.setSystemConfigToCurrentConfig()
config._setSystemConfig(fromPath)
config.setStartOnLogonScreen(enable: bool) None

Not to be confused with setStartAfterLogon.

Toggle whether NVDA starts on the logon screen automatically. On failure to set, retries with escalated permissions.

Raises a RuntimeError on failure.

config._transformSpec(spec: ConfigObj)

To make the spec less verbose, transform the spec: - Add default=”default” to all featureFlag items. This is required so that the key can be read, even if it is missing from the config.

class config.ConfigManager

Bases: object

Manages and provides access to configuration. In addition to the base configuration, there can be multiple active configuration profiles. Settings in more recently activated profiles take precedence, with the base configuration being consulted last. This allows a profile to override settings in profiles activated earlier and the base configuration. A profile need only include a subset of the available settings. Changed settings are written to the most recently activated profile.

BASE_ONLY_SECTIONS = {'addonStore', 'development', 'general', 'update', 'upgrade'}

Sections that only apply to the base configuration; i.e. they cannot be overridden in profiles. Note this set may be extended by add-ons.

_profileCache: Dict[str | None, ConfigObj] | None

All loaded profiles by name.

profiles: List[ConfigObj]

The active profiles.

profileTriggersEnabled: bool

Whether profile triggers are enabled (read-only).

triggersToProfiles: Dict[ProfileTrigger, ConfigObj] | None

Maps triggers to profiles.

_dirtyProfiles: Set[str]

The names of all profiles that have been modified since they were last saved.

_handleProfileSwitch(shouldNotify=True)
_initBaseConf(factoryDefaults=False)
_loadConfig(fn, fileError=False)
get(key, default=None)
dict()
listProfiles()
_getProfileFn(name: str) str
_getProfile(name, load=True)
getProfile(name)

Get a profile given its name. This is useful for checking whether a profile has been manually activated or triggered. @param name: The name of the profile. @type name: str @return: The profile object. @raise KeyError: If the profile is not loaded.

manualActivateProfile(name)

Manually activate a profile. Only one profile can be manually active at a time. If another profile was manually activated, deactivate it first. If C{name} is C{None}, a profile will not be activated. @param name: The name of the profile or C{None} for no profile. @type name: str

_markWriteProfileDirty()
_writeProfileToFile(filename, profile)
save()

Save all modified profiles and the base configuration to disk.

reset(factoryDefaults=False)

Reset the configuration to saved settings or factory defaults. @param factoryDefaults: C{True} to reset to factory defaults, C{False} to reset to saved configuration. @type factoryDefaults: bool

createProfile(name)

Create a profile. @param name: The name of the profile to create. @type name: str @raise ValueError: If a profile with this name already exists.

deleteProfile(name)

Delete a profile. @param name: The name of the profile to delete. @type name: str @raise LookupError: If the profile doesn’t exist.

renameProfile(oldName, newName)

Rename a profile. @param oldName: The current name of the profile. @type oldName: str @param newName: The new name for the profile. @type newName: str @raise LookupError: If the profile doesn’t exist. @raise ValueError: If a profile with the new name already exists.

_triggerProfileEnter(trigger)

Called by L{ProfileTrigger.enter}}}.

_triggerProfileExit(trigger)

Called by L{ProfileTrigger.exit}}}.

atomicProfileSwitch()

Indicate that multiple profile switches should be treated as one. This is useful when multiple triggers may be exited/entered at once; e.g. when switching applications. While multiple switches aren’t harmful, they might take longer; e.g. unnecessarily switching speech synthesizers or braille displays. This is a context manager to be used with the C{with} statement.

suspendProfileTriggers()

Suspend handling of profile triggers. Any triggers that currently apply will continue to apply. Subsequent enters or exits will not apply until triggers are resumed. @see: L{resumeTriggers}

resumeProfileTriggers()

Resume handling of profile triggers after previous suspension. Any trigger enters or exits that occurred while triggers were suspended will be applied. Trigger handling will then return to normal. @see: L{suspendTriggers}

disableProfileTriggers()

Temporarily disable all profile triggers. Any triggered profiles will be deactivated and subsequent triggers will not apply. Call L{enableTriggers} to re-enable triggers.

enableProfileTriggers()

Re-enable profile triggers after they were previously disabled.

_loadProfileTriggers()
saveProfileTriggers()

Save profile trigger information to disk. This should be called whenever L{profilesToTriggers} is modified.

_getSpecFromKeyPath(keyPath)
_getConfigValidation(spec)

returns a tuple with the spec for the config spec: (“type”, [], {}, “default value”) EG: - (u’boolean’, [], {}, u’false’) - (u’integer’, [], {‘max’: u’255’, ‘min’: u’1’}, u’192’) - (u’option’, [u’changedContext’, u’fill’, u’scroll’], {}, u’changedContext’)

getConfigValidation(keyPath)

Get a config validation details This can be used to get a L{ConfigValidationData} containing the type, default, options list, or other validation parameters (min, max, etc) for a config key. @param keyPath: a sequence of the identifiers leading to the config key. EG (“braille”, “messageTimeout”) @return ConfigValidationData

class config.ConfigValidationData(validationFuncName)

Bases: object

validationFuncName: str = None
args: List[Any] = []
kwargs: Dict[str, Any] = {}
default = None
class config.AggregatedSection(manager: ConfigManager, path: Tuple[str], spec: ConfigObj, profiles: List[ConfigObj])

Bases: object

A view of a section of configuration which aggregates settings from all active profiles.

profiles

The relevant section in all of the profiles.

static _isSection(val: Any) bool

Checks if a given value or spec is a section of a config profile.

get(key, default=None)
isSet(key)

Check whether a given key has been explicitly set. This is sometimes useful because it can return C{False} even if there is a default for the key. @return: C{True} if the key has been explicitly set, C{False} if not. @rtype: bool

_cacheLeaf(key, spec, val)
items()
copy()
dict()

Return a deepcopy of self as a dictionary. Adapted from L{configobj.Section.dict}.

_linkDeprecatedValues(key: str, val: _cacheT | _SupportsStrT | KeyError)

Link deprecated config keys and values to their replacements.

Args:

key: The configuration key to link to its new or old counterpart. val: The value associated with the configuration key.

postconditions:
  • If self.path is “documentFormatting”:
    • If key is “reportFontAttributes”:
      • If val is True, “documentFormatting.fontAttributeReporting” is set to OutputMode.SPEECH_AND_BRAILLE, otherwise, it is set to OutputMode.OFF.

    • If key is “fontAttributeReporting”:
      • if val is OutputMode.OFF, “documentFormatting.reportFontAttributes” is set to False, otherwise, it is set to True.

_getUpdateSection()
property spec
class config.ProfileTrigger

Bases: object

A trigger for automatic activation/deactivation of a configuration profile. The user can associate a profile with a trigger. When the trigger applies, the associated profile is activated. When the trigger no longer applies, the profile is deactivated. L{spec} is a string used to search for this trigger and must be implemented. To signal that this trigger applies, call L{enter}. To signal that it no longer applies, call L{exit}. Alternatively, you can use this object as a context manager via the with statement; i.e. this trigger will apply only inside the with block.

_shouldNotifyProfileSwitch = True

Whether to notify handlers when activating a triggered profile. This should usually be C{True}, but might be set to C{False} when only specific settings should be applied. For example, when switching profiles during a speech sequence, we only want to apply speech settings, not switch braille displays.

spec
property hasProfile

Whether this trigger has an associated profile. @rtype: bool

enter()

Signal that this trigger applies. The associated profile (if any) will be activated.

exit()

Signal that this trigger no longer applies. The associated profile (if any) will be deactivated.

class config.AllowUiaInChromium(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

_DEFAULT = 0
WHEN_NECESSARY = 1
YES = 2
NO = 3
static getConfig() AllowUiaInChromium
class config.AllowUiaInMSWord(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

_DEFAULT = 0
WHEN_NECESSARY = 1
WHERE_SUITABLE = 2
ALWAYS = 3
static getConfig() AllowUiaInMSWord

Submodules

config.aggregatedSection module

class config.aggregatedSection._SupportsStrT(*args, **kwargs)

Bases: Protocol

Valid config values must support str(), as this is how they are written to disk

_abc_impl = <_abc._abc_data object>
_is_protocol = True

config.configDefaults module

config.configFlags module

Flags used to define the possible values for an option in the configuration. Use Flag.MEMBER.value to set a new value or compare with an option in the config; use Flag.MEMBER.displayString in the UI for a translatable description of this member.

When creating new parameter options, consider using F{FeatureFlag} which explicitely defines the default value.

class config.configFlags.NVDAKey(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: DisplayStringIntFlag

IntFlag enumeration containing the possible config values for “Select NVDA Modifier Keys” option in keyboard settings.

Use NVDAKey.MEMBER.value to compare with the config; the config stores a bitwise combination of one or more of these values. use NVDAKey.MEMBER.displayString in the UI for a translatable description of this member.

CAPS_LOCK = 1
NUMPAD_INSERT = 2
EXTENDED_INSERT = 4
property _displayStringLabels

Specify a dictionary which takes members of the Enum and returns the translated display string.

class config.configFlags.ShowMessages(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: DisplayStringIntEnum

Enumeration containing the possible config values for “Show messages” option in braille settings.

Use ShowMessages.MEMBER.value to compare with the config; use ShowMessages.MEMBER.displayString in the UI for a translatable description of this member.

DISABLED = 0
USE_TIMEOUT = 1
SHOW_INDEFINITELY = 2
property _displayStringLabels

Specify a dictionary which takes members of the Enum and returns the translated display string.

class config.configFlags.TetherTo(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: DisplayStringStrEnum

Enumeration containing the possible config values for “Tether to” option in braille settings.

Use TetherTo.MEMBER.value to compare with the config; use TetherTo.MEMBER.displayString in the UI for a translatable description of this member.

AUTO = 'auto'
FOCUS = 'focus'
REVIEW = 'review'
property _displayStringLabels

Specify a dictionary which takes members of the Enum and returns the translated display string.

class config.configFlags.BrailleMode(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: DisplayStringStrEnum

Enumeration containing the possible config values for “Braille mode” option in braille settings. Use BrailleMode.MEMBER.value to compare with the config; use BrailleMode.MEMBER.displayString in the UI for a translatable description of this member.

FOLLOW_CURSORS = 'followCursors'
SPEECH_OUTPUT = 'speechOutput'
property _displayStringLabels: dict[BrailleMode, str]

Specify a dictionary which takes members of the Enum and returns the translated display string.

class config.configFlags.ReportLineIndentation(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: DisplayStringIntEnum

Enumeration containing the possible config values to report line indent.

Use ReportLineIndentation.MEMBER.value to compare with the config; use ReportLineIndentation.MEMBER.displayString in the UI for a translatable description of this member.

OFF = 0
SPEECH = 1
TONES = 2
SPEECH_AND_TONES = 3
property _displayStringLabels

Specify a dictionary which takes members of the Enum and returns the translated display string.

class config.configFlags.ReportTableHeaders(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: DisplayStringIntEnum

Enumeration containing the possible config values to report table headers.

Use ReportTableHeaders.MEMBER.value to compare with the config; use ReportTableHeaders.MEMBER.displayString in the UI for a translatable description of this member.

OFF = 0
ROWS_AND_COLUMNS = 1
ROWS = 2
COLUMNS = 3
property _displayStringLabels

Specify a dictionary which takes members of the Enum and returns the translated display string.

class config.configFlags.ReportCellBorders(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: DisplayStringIntEnum

Enumeration containing the possible config values to report cell borders.

Use ReportCellBorders.MEMBER.value to compare with the config; use ReportCellBorders.MEMBER.displayString in the UI for a translatable description of this member.

OFF = 0
STYLE = 1
COLOR_AND_STYLE = 2
property _displayStringLabels

Specify a dictionary which takes members of the Enum and returns the translated display string.

class config.configFlags.AddonsAutomaticUpdate(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: DisplayStringStrEnum

NOTIFY = 'notify'
DISABLED = 'disabled'
property _displayStringLabels

Specify a dictionary which takes members of the Enum and returns the translated display string.

class config.configFlags.OutputMode(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: DisplayStringIntFlag

Enumeration for ways to output information, such as formatting. Use OutputMode.MEMBER.value to compare with the config; use OutputMode.MEMBER.displayString in the UI for a translatable description of this member.

OFF = 0
SPEECH = 1
BRAILLE = 2
SPEECH_AND_BRAILLE = 3
property _displayStringLabels

Specify a dictionary which takes members of the Enum and returns the translated display string.

class config.configFlags.ParagraphStartMarker(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: DisplayStringStrEnum

NONE = ''
SPACE = ' '
PILCROW = '¶'
property _displayStringLabels

Specify a dictionary which takes members of the Enum and returns the translated display string.

config.configSpec module

config.configSpec.latestSchemaVersion = 13

The version of the schema outlined in this file. Increment this when modifying the schema and provide an upgrade step (@see profileUpgradeSteps.py). An upgrade step does not need to be added when just adding a new element to (or removing from) the schema, only when old versions of the config (conforming to old schema versions) will not work correctly with the new schema.

config.configSpec.configSpecString = '# NVDA Configuration File\nschemaVersion = integer(min=0, default=13)\n[general]\n\tlanguage = string(default="Windows")\n\tsaveConfigurationOnExit = boolean(default=True)\n\taskToExit = boolean(default=true)\n\tplayStartAndExitSounds = boolean(default=true)\n\t#possible log levels are DEBUG, IO, DEBUGWARNING, INFO\n\tloggingLevel = string(default="INFO")\n\tshowWelcomeDialogAtStartup = boolean(default=true)\n\n# Speech settings\n[speech]\n\t# The synthesizer to use\n\tsynth = string(default=auto)\n\t# symbolLevel: One of the characterProcessing.SymbolLevel values.\n\tsymbolLevel = integer(default=100)\n\ttrustVoiceLanguage = boolean(default=true)\n\tunicodeNormalization = featureFlag(optionsEnum="BoolFlag", behaviorOfDefault="disabled")\n\treportNormalizedForCharacterNavigation = boolean(default=true)\n\t# Deprecated in 2025.1\n\tincludeCLDR = boolean(default=True)\n\tsymbolDictionaries = string_list(default=list("cldr"))\n\tbeepSpeechModePitch = integer(default=10000,min=50,max=11025)\n\toutputDevice = string(default=default)\n\tautoLanguageSwitching = boolean(default=true)\n\tautoDialectSwitching = boolean(default=false)\n\tdelayedCharacterDescriptions = boolean(default=false)\n\texcludedSpeechModes = int_list(default=list())\n\n\t[[__many__]]\n\t\tcapPitchChange = integer(default=30,min=-100,max=100)\n\t\tsayCapForCapitals = boolean(default=false)\n\t\tbeepForCapitals = boolean(default=false)\n\t\tuseSpellingFunctionality = boolean(default=true)\n\n# Audio settings\n[audio]\n\taudioDuckingMode = integer(default=0)\n\tWASAPI = featureFlag(optionsEnum="BoolFlag", behaviorOfDefault="enabled")\n\tsoundVolumeFollowsVoice = boolean(default=false)\n\tsoundVolume = integer(default=100, min=0, max=100)\n\taudioAwakeTime = integer(default=30, min=0, max=3600)\n\twhiteNoiseVolume = integer(default=0, min=0, max=100)\n\tsoundSplitState = integer(default=0)\n\tincludedSoundSplitModes = int_list(default=list(0, 2, 3))\n\n# Braille settings\n[braille]\n\tdisplay = string(default=auto)\n\tmode = option("followCursors", "speechOutput", default="followCursors")\n\ttranslationTable = string(default=en-ueb-g1.ctb)\n\tinputTable = string(default=en-ueb-g1.ctb)\n\texpandAtCursor = boolean(default=true)\n\tshowCursor = boolean(default=true)\n\tcursorBlink = boolean(default=true)\n\tcursorBlinkRate = integer(default=500,min=200,max=2000)\n\tcursorShapeFocus = integer(default=192,min=1,max=255)\n\tcursorShapeReview = integer(default=128,min=1,max=255)\n\t# How braille display will show messages\n\t# 0: Disabled, 1: Use timeout, 2: Show indefinitely\n\tshowMessages = integer(0, 2, default=1)\n\t# Timeout after the message will disappear from braille display\n\tmessageTimeout = integer(default=4, min=1, max=20)\n\ttetherTo = option("auto", "focus", "review", default="auto")\n\treviewRoutingMovesSystemCaret = featureFlag(\t\toptionsEnum="ReviewRoutingMovesSystemCaretFlag", behaviorOfDefault="NEVER")\n\treadByParagraph = boolean(default=false)\n\tparagraphStartMarker = option("", " ", "¶", default="")\n\twordWrap = boolean(default=true)\n\tunicodeNormalization = featureFlag(optionsEnum="BoolFlag", behaviorOfDefault="disabled")\n\tfocusContextPresentation = option("changedContext", "fill", "scroll", default="changedContext")\n\tinterruptSpeechWhileScrolling = featureFlag(optionsEnum="BoolFlag", behaviorOfDefault="enabled")\n\tspeakOnRouting = boolean(default=false)\n\tshowSelection = featureFlag(optionsEnum="BoolFlag", behaviorOfDefault="enabled")\n\treportLiveRegions = featureFlag(optionsEnum="BoolFlag", behaviorOfDefault="enabled")\n\tfontFormattingDisplay = featureFlag(optionsEnum="FontFormattingBrailleModeFlag", behaviorOfDefault="LIBLOUIS")\n\t[[auto]]\n    \texcludedDisplays = string_list(default=list())\n\n\t# Braille display driver settings\n\t[[__many__]]\n\t\tport = string(default="")\n\n# Vision enhancement provider settings\n[vision]\n\n\t# Vision enhancement provider settings\n\t[[__many__]]\n\t\tenabled = boolean(default=false)\n\n# Presentation settings\n[presentation]\n\t\treportKeyboardShortcuts = boolean(default=true)\n\t\treportObjectPositionInformation = boolean(default=true)\n\t\tguessObjectPositionInformationWhenUnavailable = boolean(default=false)\n\t\treportTooltips = boolean(default=false)\n\t\treportHelpBalloons = boolean(default=true)\n\t\treportObjectDescriptions = boolean(default=True)\n\t\treportDynamicContentChanges = boolean(default=True)\n\t\treportAutoSuggestionsWithSound = boolean(default=True)\n\t[[progressBarUpdates]]\n\t\treportBackgroundProgressBars = boolean(default=false)\n\t\t#output modes are beep, speak, both, or off\n\t\tprogressBarOutputMode = string(default="beep")\n\t\tspeechPercentageInterval = integer(default=10)\n\t\tbeepPercentageInterval = integer(default=1)\n\t\tbeepMinHZ = integer(default=110)\n\n[mouse]\n\tenableMouseTracking = boolean(default=True) #must be true for any of the other settings to work\n\tmouseTextUnit = string(default="paragraph")\n\treportObjectRoleOnMouseEnter = boolean(default=False)\n\taudioCoordinatesOnMouseMove = boolean(default=False)\n\taudioCoordinates_detectBrightness = boolean(default=False)\n\taudioCoordinates_blurFactor = integer(default=3)\n\taudioCoordinates_minVolume = float(default=0.1)\n\taudioCoordinates_maxVolume = float(default=1.0)\n\taudioCoordinates_minPitch = integer(default=220)\n\taudioCoordinates_maxPitch = integer(default=880)\n\treportMouseShapeChanges = boolean(default=false)\n\tignoreInjectedMouseInput = boolean(default=false)\n\n[speechViewer]\n\tshowSpeechViewerAtStartup = boolean(default=false)\n\tautoPositionWindow = boolean(default=True)\n\t# Values for positioning the window.\n\t# Defaults are not used.\n\t# They should not be read if autoPositionWindow is True\n\tx = integer()\n\ty = integer()\n\twidth = integer()\n\theight = integer()\n\tdisplays = string_list()\n\n[brailleViewer]\n\tshowBrailleViewerAtStartup = boolean(default=false)\n\tshouldHoverRouteToCell = boolean(default=false)\n\tsecondsOfHoverToActivate = float(min=0.0, default=1.0)\n\t# Devices with 40 cells are quite common.\n\tdefaultCellCount = integer(min=20, max=160, default=40)\n\tautoPositionWindow = boolean(default=True)\n\t# Values for positioning the window.\n\t# Defaults are not used.\n\t# They should not be read if autoPositionWindow is True\n\tx = integer()\n\ty = integer()\n\tdisplays = string_list()\n\n#Keyboard settings\n[keyboard]\n\t# NVDAModifierKeys: Integer value combining single-bit value:\n\t# 1: CapsLock\n\t# 2: NumpadInsert\n\t# 4: ExtendedInsert\n\t# Default = 6: NumpadInsert + ExtendedInsert\n\tNVDAModifierKeys = integer(1, 7, default=6)\n\tkeyboardLayout = string(default="desktop")\n\tspeakTypedCharacters = boolean(default=true)\n\tspeakTypedWords = boolean(default=false)\n\tbeepForLowercaseWithCapslock = boolean(default=true)\n\tspeakCommandKeys = boolean(default=false)\n\tspeechInterruptForCharacters = boolean(default=true)\n\tspeechInterruptForEnter = boolean(default=true)\n\tallowSkimReadingInSayAll = boolean(default=False)\n\talertForSpellingErrors = boolean(default=True)\n\thandleInjectedKeys= boolean(default=true)\n\tmultiPressTimeout = integer(default=500, min=100, max=20000)\n\n[virtualBuffers]\n\tmaxLineLength = integer(default=100)\n\tlinesPerPage = integer(default=25)\n\tuseScreenLayout = boolean(default=True)\n\tautoPassThroughOnFocusChange = boolean(default=true)\n\tautoPassThroughOnCaretMove = boolean(default=false)\n\tpassThroughAudioIndication = boolean(default=true)\n\tautoSayAllOnPageLoad = boolean(default=true)\n\ttrapNonCommandGestures = boolean(default=true)\n\tenableOnPageLoad = boolean(default=true)\n\tautoFocusFocusableElements = boolean(default=False)\n\tloadChromiumVBufOnBusyState = featureFlag(optionsEnum="BoolFlag", behaviorOfDefault="enabled")\n\ttextParagraphRegex = string(default="((?<=\\w)(?<!\\d)["”»)]?[.…]{1,3}["”»)]?(\\[\\d+\\])*(?=[\\r\\n \xa0]|$)|[?!]|[.!?:;])")\n\n[touch]\n\tenabled = boolean(default=true)\n\ttouchTyping = boolean(default=False)\n\n#Settings for document reading (such as MS Word and wordpad)\n[documentFormatting]\n\t# These settings affect what information is reported when you navigate\n\t# to text where the formatting  or placement has changed\n\tdetectFormatAfterCursor = boolean(default=false)\n\treportFontName = boolean(default=false)\n\treportFontSize = boolean(default=false)\n\t# Deprecated in 2025.1\n\treportFontAttributes = boolean(default=false)\n\t# 0: Off, 1: Speech, 2: Braille, 3: Speech and Braille\n\tfontAttributeReporting = integer(0, 3, default=0)\n\treportRevisions = boolean(default=true)\n\treportEmphasis = boolean(default=false)\n\treportHighlight = boolean(default=true)\n\treportSuperscriptsAndSubscripts = boolean(default=false)\n\treportColor = boolean(default=False)\n\treportTransparentColor = boolean(default=False)\n\treportAlignment = boolean(default=false)\n\treportLineSpacing = boolean(default=false)\n\treportStyle = boolean(default=false)\n\treportSpellingErrors = boolean(default=true)\n\treportPage = boolean(default=true)\n\treportLineNumber = boolean(default=False)\n\t# 0: Off, 1: Speech, 2: Tones, 3: Both Speech and Tones\n\treportLineIndentation = integer(0, 3, default=0)\n\tignoreBlankLinesForRLI = boolean(default=False)\n\treportParagraphIndentation = boolean(default=False)\n\treportTables = boolean(default=true)\n\tincludeLayoutTables = boolean(default=False)\n\t# 0: Off, 1: Rows and columns, 2: Rows, 3: Columns\n\treportTableHeaders = integer(0, 3, default=1)\n\treportTableCellCoords = boolean(default=True)\n\t# 0: Off, 1: style, 2: color and style\n\treportCellBorders = integer(0, 2, default=0)\n\treportLinks = boolean(default=true)\n\treportGraphics = boolean(default=True)\n\treportComments = boolean(default=true)\n\treportBookmarks = boolean(default=true)\n\treportLists = boolean(default=true)\n\treportHeadings = boolean(default=true)\n\treportBlockQuotes = boolean(default=true)\n\treportGroupings = boolean(default=true)\n\treportLandmarks = boolean(default=true)\n\treportArticles = boolean(default=false)\n\treportFrames = boolean(default=true)\n\treportFigures = boolean(default=true)\n\treportClickable = boolean(default=true)\n\n[documentNavigation]\n\tparagraphStyle = featureFlag(optionsEnum="ParagraphNavigationFlag", behaviorOfDefault="application")\n\n[reviewCursor]\n\tsimpleReviewMode = boolean(default=True)\n\tfollowFocus = boolean(default=True)\n\tfollowCaret = boolean(default=True)\n\tfollowMouse = boolean(default=False)\n\n[UIA]\n\tenabled = boolean(default=true)\n\tuseInMSExcelWhenAvailable = boolean(default=false)\n\twinConsoleImplementation= option("auto", "legacy", "UIA", default="auto")\n\teventRegistration = option("auto", "selective", "global", default="auto")\n\t# 0:default, 1:Only when necessary, 2:yes, 3:no\n\tallowInChromium = integer(0, 3, default=0)\n\t# 0:default (where suitable), 1:Only when necessary, 2: where suitable, 3: always\n\tallowInMSWord = integer(0, 3, default=0)\n\tenhancedEventProcessing = featureFlag(optionsEnum="BoolFlag", behaviorOfDefault="enabled")\n\n[annotations]\n\treportDetails = boolean(default=true)\n\treportAriaDescription = boolean(default=true)\n\n[terminals]\n\tspeakPasswords = boolean(default=false)\n\tkeyboardSupportInLegacy = boolean(default=True)\n\tdiffAlgo = option("auto", "dmp", "difflib", default="auto")\n\twtStrategy = featureFlag(optionsEnum="WindowsTerminalStrategyFlag", behaviorOfDefault="diffing")\n\n[update]\n\tautoCheck = boolean(default=true)\n\tstartupNotification = boolean(default=true)\n\tallowUsageStats = boolean(default=false)\n\taskedAllowUsageStats = boolean(default=false)\n\n[inputComposition]\n\tautoReportAllCandidates = boolean(default=True)\n\tannounceSelectedCandidate = boolean(default=True)\n\talwaysIncludeShortCharacterDescriptionInCandidateName = boolean(default=True)\n\treportReadingStringChanges = boolean(default=True)\n\treportCompositionStringChanges = boolean(default=True)\n\n[debugLog]\n\thwIo = boolean(default=false)\n\tMSAA = boolean(default=false)\n\tUIA = boolean(default=false)\n\taudioDucking = boolean(default=false)\n\tgui = boolean(default=false)\n\tlouis = boolean(default=false)\n\ttimeSinceInput = boolean(default=false)\n\tvision = boolean(default=false)\n\tspeech = boolean(default=false)\n\tspeechManager = boolean(default=false)\n\tsynthDriver = boolean(default=false)\n\tnvwave = boolean(default=false)\n\tannotations = boolean(default=false)\n\tevents = boolean(default=false)\n\tgarbageHandler = boolean(default=false)\n\n[uwpOcr]\n\tlanguage = string(default="")\n\tautoRefresh = boolean(default=false)\n\tautoRefreshInterval = integer(default=1500, min=100)\n\n[upgrade]\n\tnewLaptopKeyboardLayout = boolean(default=false)\n\n[editableText]\n\tcaretMoveTimeoutMs = integer(min=0, max=2000, default=100)\n\n[development]\n\tenableScratchpadDir = boolean(default=false)\n\n[featureFlag]\n\t# 0:default, 1:yes, 2:no\n\tcancelExpiredFocusSpeech = integer(0, 2, default=0)\n\t# 0:Only in test versions, 1:yes\n\tplayErrorSound = integer(0, 1, default=0)\n\n[addonStore]\n\tshowWarning = boolean(default=true)\n\tautomaticUpdates = option("notify", "disabled", default="notify")\n'

The configuration specification string @type: String

config.configSpec.confspec = {'UIA': {'allowInChromium': 'integer(0, 3, default=0)', 'allowInMSWord': 'integer(0, 3, default=0)', 'enabled': 'boolean(default=true)', 'enhancedEventProcessing': 'featureFlag(optionsEnum="BoolFlag", behaviorOfDefault="enabled")', 'eventRegistration': 'option("auto", "selective", "global", default="auto")', 'useInMSExcelWhenAvailable': 'boolean(default=false)', 'winConsoleImplementation': 'option("auto", "legacy", "UIA", default="auto")'}, 'addonStore': {'automaticUpdates': 'option("notify", "disabled", default="notify")', 'showWarning': 'boolean(default=true)'}, 'annotations': {'reportAriaDescription': 'boolean(default=true)', 'reportDetails': 'boolean(default=true)'}, 'audio': {'WASAPI': 'featureFlag(optionsEnum="BoolFlag", behaviorOfDefault="enabled")', 'audioAwakeTime': 'integer(default=30, min=0, max=3600)', 'audioDuckingMode': 'integer(default=0)', 'includedSoundSplitModes': 'int_list(default=list(0, 2, 3))', 'soundSplitState': 'integer(default=0)', 'soundVolume': 'integer(default=100, min=0, max=100)', 'soundVolumeFollowsVoice': 'boolean(default=false)', 'whiteNoiseVolume': 'integer(default=0, min=0, max=100)'}, 'braille': {'__many__': {'port': 'string(default="")'}, 'auto': {'excludedDisplays': 'string_list(default=list())'}, 'cursorBlink': 'boolean(default=true)', 'cursorBlinkRate': 'integer(default=500,min=200,max=2000)', 'cursorShapeFocus': 'integer(default=192,min=1,max=255)', 'cursorShapeReview': 'integer(default=128,min=1,max=255)', 'display': 'string(default=auto)', 'expandAtCursor': 'boolean(default=true)', 'focusContextPresentation': 'option("changedContext", "fill", "scroll", default="changedContext")', 'fontFormattingDisplay': 'featureFlag(optionsEnum="FontFormattingBrailleModeFlag", behaviorOfDefault="LIBLOUIS")', 'inputTable': 'string(default=en-ueb-g1.ctb)', 'interruptSpeechWhileScrolling': 'featureFlag(optionsEnum="BoolFlag", behaviorOfDefault="enabled")', 'messageTimeout': 'integer(default=4, min=1, max=20)', 'mode': 'option("followCursors", "speechOutput", default="followCursors")', 'paragraphStartMarker': 'option("", " ", "¶", default="")', 'readByParagraph': 'boolean(default=false)', 'reportLiveRegions': 'featureFlag(optionsEnum="BoolFlag", behaviorOfDefault="enabled")', 'reviewRoutingMovesSystemCaret': 'featureFlag(\t\toptionsEnum="ReviewRoutingMovesSystemCaretFlag", behaviorOfDefault="NEVER")', 'showCursor': 'boolean(default=true)', 'showMessages': 'integer(0, 2, default=1)', 'showSelection': 'featureFlag(optionsEnum="BoolFlag", behaviorOfDefault="enabled")', 'speakOnRouting': 'boolean(default=false)', 'tetherTo': 'option("auto", "focus", "review", default="auto")', 'translationTable': 'string(default=en-ueb-g1.ctb)', 'unicodeNormalization': 'featureFlag(optionsEnum="BoolFlag", behaviorOfDefault="disabled")', 'wordWrap': 'boolean(default=true)'}, 'brailleViewer': {'autoPositionWindow': 'boolean(default=True)', 'defaultCellCount': 'integer(min=20, max=160, default=40)', 'displays': 'string_list()', 'secondsOfHoverToActivate': 'float(min=0.0, default=1.0)', 'shouldHoverRouteToCell': 'boolean(default=false)', 'showBrailleViewerAtStartup': 'boolean(default=false)', 'x': 'integer()', 'y': 'integer()'}, 'debugLog': {'MSAA': 'boolean(default=false)', 'UIA': 'boolean(default=false)', 'annotations': 'boolean(default=false)', 'audioDucking': 'boolean(default=false)', 'events': 'boolean(default=false)', 'garbageHandler': 'boolean(default=false)', 'gui': 'boolean(default=false)', 'hwIo': 'boolean(default=false)', 'louis': 'boolean(default=false)', 'nvwave': 'boolean(default=false)', 'speech': 'boolean(default=false)', 'speechManager': 'boolean(default=false)', 'synthDriver': 'boolean(default=false)', 'timeSinceInput': 'boolean(default=false)', 'vision': 'boolean(default=false)'}, 'development': {'enableScratchpadDir': 'boolean(default=false)'}, 'documentFormatting': {'detectFormatAfterCursor': 'boolean(default=false)', 'fontAttributeReporting': 'integer(0, 3, default=0)', 'ignoreBlankLinesForRLI': 'boolean(default=False)', 'includeLayoutTables': 'boolean(default=False)', 'reportAlignment': 'boolean(default=false)', 'reportArticles': 'boolean(default=false)', 'reportBlockQuotes': 'boolean(default=true)', 'reportBookmarks': 'boolean(default=true)', 'reportCellBorders': 'integer(0, 2, default=0)', 'reportClickable': 'boolean(default=true)', 'reportColor': 'boolean(default=False)', 'reportComments': 'boolean(default=true)', 'reportEmphasis': 'boolean(default=false)', 'reportFigures': 'boolean(default=true)', 'reportFontAttributes': 'boolean(default=false)', 'reportFontName': 'boolean(default=false)', 'reportFontSize': 'boolean(default=false)', 'reportFrames': 'boolean(default=true)', 'reportGraphics': 'boolean(default=True)', 'reportGroupings': 'boolean(default=true)', 'reportHeadings': 'boolean(default=true)', 'reportHighlight': 'boolean(default=true)', 'reportLandmarks': 'boolean(default=true)', 'reportLineIndentation': 'integer(0, 3, default=0)', 'reportLineNumber': 'boolean(default=False)', 'reportLineSpacing': 'boolean(default=false)', 'reportLinks': 'boolean(default=true)', 'reportLists': 'boolean(default=true)', 'reportPage': 'boolean(default=true)', 'reportParagraphIndentation': 'boolean(default=False)', 'reportRevisions': 'boolean(default=true)', 'reportSpellingErrors': 'boolean(default=true)', 'reportStyle': 'boolean(default=false)', 'reportSuperscriptsAndSubscripts': 'boolean(default=false)', 'reportTableCellCoords': 'boolean(default=True)', 'reportTableHeaders': 'integer(0, 3, default=1)', 'reportTables': 'boolean(default=true)', 'reportTransparentColor': 'boolean(default=False)'}, 'documentNavigation': {'paragraphStyle': 'featureFlag(optionsEnum="ParagraphNavigationFlag", behaviorOfDefault="application")'}, 'editableText': {'caretMoveTimeoutMs': 'integer(min=0, max=2000, default=100)'}, 'featureFlag': {'cancelExpiredFocusSpeech': 'integer(0, 2, default=0)', 'playErrorSound': 'integer(0, 1, default=0)'}, 'general': {'askToExit': 'boolean(default=true)', 'language': 'string(default="Windows")', 'loggingLevel': 'string(default="INFO")', 'playStartAndExitSounds': 'boolean(default=true)', 'saveConfigurationOnExit': 'boolean(default=True)', 'showWelcomeDialogAtStartup': 'boolean(default=true)'}, 'inputComposition': {'alwaysIncludeShortCharacterDescriptionInCandidateName': 'boolean(default=True)', 'announceSelectedCandidate': 'boolean(default=True)', 'autoReportAllCandidates': 'boolean(default=True)', 'reportCompositionStringChanges': 'boolean(default=True)', 'reportReadingStringChanges': 'boolean(default=True)'}, 'keyboard': {'NVDAModifierKeys': 'integer(1, 7, default=6)', 'alertForSpellingErrors': 'boolean(default=True)', 'allowSkimReadingInSayAll': 'boolean(default=False)', 'beepForLowercaseWithCapslock': 'boolean(default=true)', 'handleInjectedKeys': 'boolean(default=true)', 'keyboardLayout': 'string(default="desktop")', 'multiPressTimeout': 'integer(default=500, min=100, max=20000)', 'speakCommandKeys': 'boolean(default=false)', 'speakTypedCharacters': 'boolean(default=true)', 'speakTypedWords': 'boolean(default=false)', 'speechInterruptForCharacters': 'boolean(default=true)', 'speechInterruptForEnter': 'boolean(default=true)'}, 'mouse': {'audioCoordinatesOnMouseMove': 'boolean(default=False)', 'audioCoordinates_blurFactor': 'integer(default=3)', 'audioCoordinates_detectBrightness': 'boolean(default=False)', 'audioCoordinates_maxPitch': 'integer(default=880)', 'audioCoordinates_maxVolume': 'float(default=1.0)', 'audioCoordinates_minPitch': 'integer(default=220)', 'audioCoordinates_minVolume': 'float(default=0.1)', 'enableMouseTracking': 'boolean(default=True)', 'ignoreInjectedMouseInput': 'boolean(default=false)', 'mouseTextUnit': 'string(default="paragraph")', 'reportMouseShapeChanges': 'boolean(default=false)', 'reportObjectRoleOnMouseEnter': 'boolean(default=False)'}, 'presentation': {'guessObjectPositionInformationWhenUnavailable': 'boolean(default=false)', 'progressBarUpdates': {'beepMinHZ': 'integer(default=110)', 'beepPercentageInterval': 'integer(default=1)', 'progressBarOutputMode': 'string(default="beep")', 'reportBackgroundProgressBars': 'boolean(default=false)', 'speechPercentageInterval': 'integer(default=10)'}, 'reportAutoSuggestionsWithSound': 'boolean(default=True)', 'reportDynamicContentChanges': 'boolean(default=True)', 'reportHelpBalloons': 'boolean(default=true)', 'reportKeyboardShortcuts': 'boolean(default=true)', 'reportObjectDescriptions': 'boolean(default=True)', 'reportObjectPositionInformation': 'boolean(default=true)', 'reportTooltips': 'boolean(default=false)'}, 'reviewCursor': {'followCaret': 'boolean(default=True)', 'followFocus': 'boolean(default=True)', 'followMouse': 'boolean(default=False)', 'simpleReviewMode': 'boolean(default=True)'}, 'schemaVersion': 'integer(min=0, default=13)', 'speech': {'__many__': {'beepForCapitals': 'boolean(default=false)', 'capPitchChange': 'integer(default=30,min=-100,max=100)', 'sayCapForCapitals': 'boolean(default=false)', 'useSpellingFunctionality': 'boolean(default=true)'}, 'autoDialectSwitching': 'boolean(default=false)', 'autoLanguageSwitching': 'boolean(default=true)', 'beepSpeechModePitch': 'integer(default=10000,min=50,max=11025)', 'delayedCharacterDescriptions': 'boolean(default=false)', 'excludedSpeechModes': 'int_list(default=list())', 'includeCLDR': 'boolean(default=True)', 'outputDevice': 'string(default=default)', 'reportNormalizedForCharacterNavigation': 'boolean(default=true)', 'symbolDictionaries': 'string_list(default=list("cldr"))', 'symbolLevel': 'integer(default=100)', 'synth': 'string(default=auto)', 'trustVoiceLanguage': 'boolean(default=true)', 'unicodeNormalization': 'featureFlag(optionsEnum="BoolFlag", behaviorOfDefault="disabled")'}, 'speechViewer': {'autoPositionWindow': 'boolean(default=True)', 'displays': 'string_list()', 'height': 'integer()', 'showSpeechViewerAtStartup': 'boolean(default=false)', 'width': 'integer()', 'x': 'integer()', 'y': 'integer()'}, 'terminals': {'diffAlgo': 'option("auto", "dmp", "difflib", default="auto")', 'keyboardSupportInLegacy': 'boolean(default=True)', 'speakPasswords': 'boolean(default=false)', 'wtStrategy': 'featureFlag(optionsEnum="WindowsTerminalStrategyFlag", behaviorOfDefault="diffing")'}, 'touch': {'enabled': 'boolean(default=true)', 'touchTyping': 'boolean(default=False)'}, 'update': {'allowUsageStats': 'boolean(default=false)', 'askedAllowUsageStats': 'boolean(default=false)', 'autoCheck': 'boolean(default=true)', 'startupNotification': 'boolean(default=true)'}, 'upgrade': {'newLaptopKeyboardLayout': 'boolean(default=false)'}, 'uwpOcr': {'autoRefresh': 'boolean(default=false)', 'autoRefreshInterval': 'integer(default=1500, min=100)', 'language': 'string(default="")'}, 'virtualBuffers': {'autoFocusFocusableElements': 'boolean(default=False)', 'autoPassThroughOnCaretMove': 'boolean(default=false)', 'autoPassThroughOnFocusChange': 'boolean(default=true)', 'autoSayAllOnPageLoad': 'boolean(default=true)', 'enableOnPageLoad': 'boolean(default=true)', 'linesPerPage': 'integer(default=25)', 'loadChromiumVBufOnBusyState': 'featureFlag(optionsEnum="BoolFlag", behaviorOfDefault="enabled")', 'maxLineLength': 'integer(default=100)', 'passThroughAudioIndication': 'boolean(default=true)', 'textParagraphRegex': 'string(default="((?<=\\w)(?<!\\d)["”»)]?[.…]{1,3}["”»)]?(\\[\\d+\\])*(?=[\\r\\n \xa0]|$)|[?!]|[.!?:;])")', 'trapNonCommandGestures': 'boolean(default=true)', 'useScreenLayout': 'boolean(default=True)'}, 'vision': {'__many__': {'enabled': 'boolean(default=false)'}}}

The configuration specification @type: ConfigObj

config.featureFlag module

Manages NVDA configuration. Provides utility classes to make handling featureFlags easier.

class config.featureFlag.FeatureFlag(value: FlagValueEnum, behaviorOfDefault: FlagValueEnum)

Bases: object

A FeatureFlag allows the selection of a preference for behavior or its default state. It’s typically used to introduce a feature that isn’t expected to handle all use-cases well when initially introduced. The feature can be disabled initially, some users can manually enable and try the feature giving feedback. Once developers have confidence in the feature, the default behavior is changed. This change in default behavior should not have any impact on users who have already tried the feature, and perhaps disagreed in principle with it (I.E. wished to disable the feature, not because it is buggy, but because even if it works perfectly it is not their preference). The default option allows users to explicitly defer to the NVDA default behaviour. The default behaviour can change, without affecting a user’s preference.

isDefault() bool
calculated() FlagValueEnum
config.featureFlag._validateConfig_featureFlag(value: str | FeatureFlag | None, optionsEnum: str, behaviorOfDefault: str) FeatureFlag

Used in conjunction with configObj.Validator param value: The value to be validated / converted to a FeatureFlag object. Expected: “enabled”, “disabled”, “default” param behaviorOfDefault: Required, the default behavior of the flag, should be “enabled” or “disabled”.

config.featureFlag._transformSpec_AddFeatureFlagDefault(specString: str, **kwargs) str

Ensure that default is specified for featureFlag used in configSpec. Param examples based on the following spec string in configSpec:

loadChromiumVBufOnBusyState = featureFlag(behaviorOfDefault=”enabled”, optionsEnum=”BoolFlag”)

@param specString: EG ‘featureFlag(behaviorOfDefault=”enabled”, optionsEnum=”BoolFlag”)’ @param kwargs: EG {‘behaviorOfDefault’: ‘enabled’, ‘optionsEnum’:’BoolFlag’} @return ‘featureFlag(behaviorOfDefault=”ENABLED”, optionsEnum=”BoolFlag”, default=”DEFAULT”)’ @remarks Manually specifying ‘default’ in the configSpec string (for featureFlag) will result in a

VdtParamError. Required params: - ‘behaviorOfDefault’ - ‘optionsEnum’

config.featureFlagEnums module

Feature flag value enumerations. Some feature flags require feature specific options, this file defines those options. All feature flags enums should - inherit from DisplayStringEnum and implement _displayStringLabels (for the ‘displayString’ property) - have a ‘DEFAULT’ member.

class config.featureFlagEnums.FeatureFlagEnumProtocol(*args, **kwargs)

Bases: Protocol

All feature flags are expected to have a “DEFAULT” value. This definition is provided only for type annotations

DEFAULT: Enum
name: str
value: str
_abc_impl = <_abc._abc_data object>
_is_protocol = True
class config.featureFlagEnums.FlagValueEnum(cls, bases, classdict, *, boundary=None, _simple=False, **kwds)

Bases: EnumType, _DisplayStringEnumMixin, FeatureFlagEnumProtocol

Provided only for type annotations.

_abc_impl = <_abc._abc_data object>
_is_protocol = False
class config.featureFlagEnums.BoolFlag(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: DisplayStringEnum

Generic logically bool feature flag. The explicit DEFAULT option allows developers to differentiate between a value set that happens to be the current default, and a value that has been returned to the “default” explicitly.

property _displayStringLabels

Specify a dictionary which takes members of the Enum and returns the translated display string.

DEFAULT = 1
DISABLED = 2
ENABLED = 3
class config.featureFlagEnums.ParagraphNavigationFlag(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: DisplayStringEnum

property _displayStringLabels

Specify a dictionary which takes members of the Enum and returns the translated display string.

DEFAULT = 1
APPLICATION = 2
SINGLE_LINE_BREAK = 3
MULTI_LINE_BREAK = 4
class config.featureFlagEnums.ReviewRoutingMovesSystemCaretFlag(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: DisplayStringEnum

property _displayStringLabels

Specify a dictionary which takes members of the Enum and returns the translated display string.

DEFAULT = 1
NEVER = 2
ONLY_WHEN_AUTO_TETHERED = 3
ALWAYS = 4
class config.featureFlagEnums.WindowsTerminalStrategyFlag(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: DisplayStringEnum

A feature flag for defining how new text is calculated in Windows Terminal (wt.exe).

property _displayStringLabels

Specify a dictionary which takes members of the Enum and returns the translated display string.

DEFAULT = 1
DIFFING = 2
NOTIFICATIONS = 3
class config.featureFlagEnums.FontFormattingBrailleModeFlag(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: DisplayStringEnum

Enumeration containing the possible ways to display formatting changes in braille.

DEFAULT = 1
LIBLOUIS = 2
TAGS = 3
property _displayStringLabels: dict[FontFormattingBrailleModeFlag, str]

Specify a dictionary which takes members of the Enum and returns the translated display string.

config.featureFlagEnums.getAvailableEnums() Generator[Tuple[str, FlagValueEnum], None, None]

config.profileUpgradeSteps module

Contains upgrade steps for the NVDA configuration files. These steps are run to ensure that a configuration file complies with the latest schema (@see configSpec.py).

To add a new step (after modifying the schema and incrementing the schema version number) add a new method to this module. The method name should be in the form “upgradeConfigFrom_X_to_Y” where X is the previous schema version, and Y is the current schema version. The argument profile will be a configobj.ConfigObj object. The function should ensure that no information is lost, while updating the ConfigObj to meet the requirements of the new schema.

config.profileUpgradeSteps.upgradeConfigFrom_0_to_1(profile: ConfigObj) None
config.profileUpgradeSteps.upgradeConfigFrom_1_to_2(profile: ConfigObj) None
config.profileUpgradeSteps.upgradeConfigFrom_2_to_3(profile: ConfigObj) None
config.profileUpgradeSteps.upgradeConfigFrom_3_to_4(profile: ConfigObj) None

Reporting of superscripts and subscripts can now be configured separately to font attributes.

config.profileUpgradeSteps.upgradeConfigFrom_4_to_5(profile: ConfigObj) None

reporting details has become enabled by default. Discard aria-details setting, ensure users are aware of the setting. The setting was used while the feature was in development. Prevented reporting ‘has details’ with no way to report the details.

config.profileUpgradeSteps.upgradeConfigFrom_5_to_6(profile: ConfigObj) None

useInMSWordWhenAvailable in UIA section has been replaced with allowInMSWord multichoice.

config.profileUpgradeSteps.upgradeConfigFrom_6_to_7(profile: ConfigObj) None

Selective UIA registration check box has been replaced with event registration multi choice. If the user has explicitly enabled selective UIA event registration, set the new eventRegistration preference to selective. Otherwise, the default value, auto, will be used.

config.profileUpgradeSteps.upgradeConfigFrom_7_to_8(profile: ConfigObj) None

In Document formatting settings, “Row/column headers” check box has been replaced with “Headers” combobox.

config.profileUpgradeSteps.upgradeConfigFrom_8_to_9(profile: ConfigObj) None

In NVDA config, when various values were controlling a single combobox in the settings window, these values have been replaced by a single value. The following settings are upgraded: - Line indentation (in Document formatting settings) - Cell borders (in Document formatting settings) - Show messages (in Braille settings) - Tether to (in Braille settings)

config.profileUpgradeSteps._upgradeConfigFrom_8_to_9_lineIndent(profile: ConfigObj) None
config.profileUpgradeSteps._upgradeConfigFrom_8_to_9_cellBorders(profile: ConfigObj) None
config.profileUpgradeSteps._upgradeConfigFrom_8_to_9_showMessages(profile: ConfigObj) None
config.profileUpgradeSteps._upgradeConfigFrom_8_to_9_tetherTo(profile: ConfigObj) None
config.profileUpgradeSteps.upgradeConfigFrom_9_to_10(profile: ConfigObj) None

In NVDA config, use only one value to store NVDA keys rather than 3 distinct values.

config.profileUpgradeSteps.upgradeConfigFrom_10_to_11(profile: ConfigObj) None

Remove the enableHidBrailleSupport braille config flag in favor of an auto detect exclusion.

config.profileUpgradeSteps.upgradeConfigFrom_11_to_12(profile: ConfigObj) None

Add a new key, documentFormatting.fontAttributeReporting, which allows users to select between speech and/or braille, and base it on documentFormatting.reportFontAttributes.

config.profileUpgradeSteps.upgradeConfigFrom_12_to_13(profile: ConfigObj) None

If the includeCldr speech config flag is set in a profile, enable the cldr dictionary in the speechSymbols list.

config.profileUpgrader module

config.profileUpgrader.upgrade(profile, validator, writeProfileToFileFunc)

Upgrade a profile in memory and validate it If it is safe to do so, as defined by shouldWriteProfileToFile, the profile is written out.

config.profileUpgrader._doConfigUpgrade(profile, fromVersion)
config.profileUpgrader._doValidation(profile, validator)
config.profileUpgrader._ensureVersionProperty(profile)