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
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
Bases:
DisplayStringEnum
Specify a dictionary which takes members of the Enum and returns the translated display string.
- 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)