gui package

gui.quit()

Deprecated, use wx.CallAfter(mainFrame.onExitCommand, None) directly instead.

gui.mainFrame: MainFrame | None = None

Set by initialize. Should be used as the parent for “top level” dialogs.

class gui.MainFrame

Bases: Frame

A hidden window, intended to act as the parent to all dialogs.

prevFocus

The focus before the last popup or C{None} if unknown. This is only valid before L{prePopup} is called, so it should be used as early as possible in any popup that needs it. @type: L{NVDAObject}

prevFocusAncestors

The focus ancestors before the last popup or C{None} if unknown. @type: list of L{NVDAObject}

prePopup()

Prepare for a popup. This should be called before any dialog or menu which should pop up for the user. L{postPopup} should be called after the dialog or menu has been shown. @postcondition: A dialog or menu may be shown.

postPopup()

Clean up after a popup dialog or menu. This should be called after a dialog or menu was popped up for the user.

showGui()
onRevertToSavedConfigurationCommand(evt)
onRevertToDefaultConfigurationCommand(evt)
onSaveConfigurationCommand(evt)
popupSettingsDialog(dialog: Type[SettingsDialog], *args, **kwargs)
_popupSettingsDialog(dialog: Type[SettingsDialog], *args, **kwargs)
onDefaultDictionaryCommand(evt)
onVoiceDictionaryCommand(evt)
onTemporaryDictionaryCommand(evt)
onExecuteUpdateCommand(evt)
evaluateUpdatePendingUpdateMenuItemCommand()
onExitCommand(evt)
onNVDASettingsCommand(evt)
onGeneralSettingsCommand(evt)
onSelectSynthesizerCommand(evt)
onSpeechSettingsCommand(evt)
onSelectBrailleDisplayCommand(evt)
onBrailleSettingsCommand(evt)
onAudioSettingsCommand(evt: CommandEvent)
onKeyboardSettingsCommand(evt)
onMouseSettingsCommand(evt)
onTouchInteractionCommand(evt)
onReviewCursorCommand(evt)
onInputCompositionCommand(evt)
onObjectPresentationCommand(evt)
onBrowseModeCommand(evt)
onDocumentFormattingCommand(evt)
onUwpOcrCommand(evt)
onSpeechSymbolsCommand(evt)
onInputGesturesCommand(evt)
onAboutCommand(evt)
onCheckForUpdateCommand(evt)
onViewLogCommand(evt)
onSpeechViewerEnabled(isEnabled)
onToggleSpeechViewerCommand(evt)
onBrailleViewerChangedState(created)
onToggleBrailleViewerCommand(evt)
onPythonConsoleCommand(evt)
onAddonsManagerCommand(evt: MenuEvent)
onAddonStoreCommand(evt: MenuEvent)
onAddonStoreUpdatableCommand(evt: MenuEvent | None)
onReloadPluginsCommand(evt)
onCreatePortableCopyCommand(evt)
onInstallCommand(evt)
onRunCOMRegistrationFixesCommand(evt)
onConfigProfilesCommand(evt)
class gui.SysTrayIcon(frame: MainFrame)

Bases: TaskBarIcon

evaluateUpdatePendingUpdateMenuItemCommand()
onActivate(evt)
_createSpeechDictsSubMenu(frame: MainFrame) Menu
_appendConfigManagementSection(frame: MainFrame) None
_appendHelpSubMenu(frame: MainFrame) None
_appendPendingUpdateSection(frame: MainFrame) None
gui.initialize()
gui.terminate()
gui.showGui()
gui.runScriptModalDialog(dialog, callback=None)

Run a modal dialog from a script. This will not block the caller, but will instead call C{callback} (if provided) with the result from the dialog. The dialog will be destroyed once the callback has returned. @param dialog: The dialog to show. @type dialog: C{wx.Dialog} @param callback: The optional callable to call with the result from the dialog. @type callback: callable

class gui.IndeterminateProgressDialog(parent: Window, title: str, message: str)

Bases: ProgressDialog

Pulse(newmsg=EmptyString)

Like Update() but makes the gauge control run in indeterminate mode.

IsActive() bool

Returns true if this window is currently active, i.e. if the user is currently working with it.

done()
gui.shouldConfigProfileTriggersBeSuspended()

Determine whether configuration profile triggers should be suspended in relation to NVDA’s GUI. For NVDA configuration dialogs, the configuration should remain the same as it was before the GUI was popped up so the user can change settings in the correct profile. Top-level windows that require this behavior should have a C{shouldSuspendConfigProfileTriggers} attribute set to C{True}. Because these dialogs are often opened via the NVDA menu, this applies to the NVDA menu as well.

class gui.NonReEntrantTimer(run=None)

Bases: Timer

Before WXPython 4, wx.Timer was nonre-entrant, meaning that if code within its callback pumped messages (E.g. called wx.Yield) and this timer was ready to fire again, the timer would not fire until the first callback had completed. However, in WXPython 4, wx.Timer is now re-entrant. Code in NVDA is not written to handle re-entrant timers, so this class provides a Timer with the old behaviour. This should be used in place of wx.Timer and wx.PyTimer where the callback will directly or indirectly call wx.Yield or some how process the Windows window message queue. For example, NVDA’s core pump or other timers that run in NVDA’s main thread. Timers on braille display drivers for key detection don’t need to use this as they only queue gestures rather than actually executing them.

run()

Subclasses can override or specify in constructor.

Notify()

This member should be overridden by the user if the default constructor was used and SetOwner() wasn’t called.

gui._isDebug()

Subpackages

Submodules

gui.addonGui module

gui.addonGui.promptUserForRestart()
class gui.addonGui.ConfirmAddonInstallDialog(parent, title, message, showAddonInfoFunction)

Bases: MessageDialog

Called in place of wx.Dialog __init__ arguments are forwarded on. Expected args (from wx docs): parent, id, title, pos=wx.DefaultPosition, size=wx.DefaultSize, style=wx.DEFAULT_DIALOG_STYLE, name=wx.DialogNameStr where: wx.DEFAULT_DIALOG_STYLE = (wxCAPTION | wxSYSTEM_MENU | wxCLOSE_BOX)

_addButtons(buttonHelper)

Adds ok / cancel buttons. Can be overridden to provide alternative functionality.

class gui.addonGui.ErrorAddonInstallDialog(parent, title, message, showAddonInfoFunction)

Bases: MessageDialog

Called in place of wx.Dialog __init__ arguments are forwarded on. Expected args (from wx docs): parent, id, title, pos=wx.DefaultPosition, size=wx.DefaultSize, style=wx.DEFAULT_DIALOG_STYLE, name=wx.DialogNameStr where: wx.DEFAULT_DIALOG_STYLE = (wxCAPTION | wxSYSTEM_MENU | wxCLOSE_BOX)

_addButtons(buttonHelper)

Adds ok / cancel buttons. Can be overridden to provide alternative functionality.

gui.addonGui.installAddon(parentWindow: Window, addonPath: str) bool

Installs the addon bundle at path. Only used for installing external add-on bundles. Any error messages / warnings are presented to the user via a GUI message box. If attempting to install an addon that is pending removal, it will no longer be pending removal. @return True on success or False on failure. @note See also L{addonStore.install.installAddon}

gui.addonGui._doneAndDestroy(window: IndeterminateProgressDialog)
gui.addonGui._performExternalAddonBundleInstall(parentWindow: Window, bundle: AddonBundle, prevAddon: Addon | None) bool

Perform the installation of an add-on bundle. :param parentWindow: The parent window for the progress dialog. :param bundle: The add-on bundle to install. :param prevAddon: The previously installed add-on, if any. :return: True if the installation was successful, False otherwise.

gui.addonGui.handleRemoteAddonInstall(addonPath: str)
class gui.addonGui.IncompatibleAddonsDialog(*args, **kwargs)

Bases: DpiScalingHelperMixinWithoutInit, ContextHelpMixin, Dialog

A dialog that lists incompatible addons, and why they are not compatible

classmethod _instance()

type: () -> IncompatibleAddonsDialog return None until this is replaced with a weakref.ref object. Then the instance is retrieved with by treating that object as a callable.

helpId = 'IncompatibleAddonsManager'
refreshAddonsList()
onAbout(evt: <wx.core.PyEventBinder object at 0x062402B0>)
onClose(evt)

gui.blockAction module

class gui.blockAction._Context(blockActionIf: Callable[[], bool], translatedMessage: str)

Bases: object

blockActionIf: Callable[[], bool]
translatedMessage: str
class gui.blockAction.Context(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: _Context, Enum

SECURE_MODE = _Context(blockActionIf=<function Context.<lambda>>, translatedMessage='Action unavailable in secure context')
WINDOWS_STORE_VERSION = _Context(blockActionIf=<function Context.<lambda>>, translatedMessage='Action unavailable in NVDA Windows Store version')
MODAL_DIALOG_OPEN = _Context(blockActionIf=<function isModalMessageBoxActive>, translatedMessage='Action unavailable while a dialog requires a response')
WINDOWS_LOCKED = _Context(blockActionIf=<function Context.<lambda>>, translatedMessage='Action unavailable while Windows is locked')
RUNNING_LAUNCHER = _Context(blockActionIf=<function Context.<lambda>>, translatedMessage='Action unavailable in a temporary version of NVDA')
BRAILLE_MODE_SPEECH_OUTPUT = _Context(blockActionIf=<function Context.<lambda>>, translatedMessage='Action unavailable while the braille mode is set to speech output')
_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_ = False
_member_names_ = ['SECURE_MODE', 'WINDOWS_STORE_VERSION', 'MODAL_DIALOG_OPEN', 'WINDOWS_LOCKED', 'RUNNING_LAUNCHER', 'BRAILLE_MODE_SPEECH_OUTPUT']
_member_map_ = {'BRAILLE_MODE_SPEECH_OUTPUT': Context.BRAILLE_MODE_SPEECH_OUTPUT, 'MODAL_DIALOG_OPEN': Context.MODAL_DIALOG_OPEN, 'RUNNING_LAUNCHER': Context.RUNNING_LAUNCHER, 'SECURE_MODE': Context.SECURE_MODE, 'WINDOWS_LOCKED': Context.WINDOWS_LOCKED, 'WINDOWS_STORE_VERSION': Context.WINDOWS_STORE_VERSION}
_value2member_map_ = {}
_unhashable_values_ = [_Context(blockActionIf=<function Context.<lambda>>, translatedMessage='Action unavailable in secure context'), _Context(blockActionIf=<function Context.<lambda>>, translatedMessage='Action unavailable in NVDA Windows Store version'), _Context(blockActionIf=<function isModalMessageBoxActive>, translatedMessage='Action unavailable while a dialog requires a response'), _Context(blockActionIf=<function Context.<lambda>>, translatedMessage='Action unavailable while Windows is locked'), _Context(blockActionIf=<function Context.<lambda>>, translatedMessage='Action unavailable in a temporary version of NVDA'), _Context(blockActionIf=<function Context.<lambda>>, translatedMessage='Action unavailable while the braille mode is set to speech output')]
_member_type_

alias of _Context

_value_repr_()

Return repr(self).

blockActionIf: Callable[[], bool]
translatedMessage: str
gui.blockAction.when(*contexts: Context)

Returns a function wrapper. A function decorated with when will exit early if any supplied context in contexts is active. The first supplied context to block will be reported as a message. Consider supplying permanent conditions first.

For example, to block a function when a modal dialog is open (a temporary condition) and in the Windows Store version (per installation), decorate it with @blockAction.when(blockAction.Context.WINDOWS_STORE_VERSION, blockAction.Context.MODAL_DIALOG_OPEN).

gui.configProfiles module

class gui.configProfiles.ProfilesDialog(*args, **kwargs)

Bases: ContextHelpMixin, Dialog

shouldSuspendConfigProfileTriggers = True
helpId = 'ConfigurationProfiles'
_instance = None
getProfileDisplay(name, includeStates=False)
getProfileStates(name)
isProfileManual(name)
onChangeState(evt)
onNew(evt)
onDelete(evt)
onProfileListChoice(evt)
onRename(evt)
onTriggers(evt)
getSimpleTriggers()
onClose(evt)
saveTriggers(parentWindow=None)
class gui.configProfiles.TriggerInfo(spec, display, profile)

Bases: object

spec
display
profile
class gui.configProfiles.TriggersDialog(parent)

Bases: ContextHelpMixin, Dialog

helpId = 'ConfigProfileTriggers'
onTriggerListChoice(evt)
onProfileListChoice(evt)
onClose(evt)
class gui.configProfiles.NewProfileDialog(parent)

Bases: ContextHelpMixin, Dialog

helpId = 'ProfilesCreating'
onOk(evt)
onCancel(evt)
onTriggerChoice(evt)
class gui.configProfiles.RenameProfileDialog(*args, **kwargs)

Bases: ContextHelpMixin, TextEntryDialog

helpId = 'ProfilesBasicManagement'

gui.contextHelp module

gui.contextHelp.writeRedirect(helpId: str, helpFilePath: str, contextHelpPath: str)
gui.contextHelp.showHelp(helpId: str)

Display the corresponding section of the user guide when either the Help button in an NVDA dialog is pressed or the F1 key is pressed on a recognized control.

gui.contextHelp.bindHelpEvent(helpId: str, window: Window)
gui.contextHelp._onEvtHelp(helpId: str, evt: HelpEvent)
class gui.contextHelp.ContextHelpMixin(*args, **kwargs)

Bases: object

helpId = ''
bindHelpEvent(helpId: str, window: Window)

A helper method, to bind helpId strings to sub-controls of this Window. Useful for adding context help to wx controls directly.

gui.dpiScalingHelper module

gui.dpiScalingHelper.scaleSize(scaleFactor: float, size: Tuple[int | float, int | float] | int | float) Tuple[int, int] | int

Helper method to scale a size using the logical DPI @param size: The size (x, y) as a tuple or a single numerical type to scale @returns: The scaled size, as a tuple or a single numerical type.

gui.dpiScalingHelper.getScaleFactor(windowHandle: int) int

Helper method to get the window scale factor. The window needs to be constructed first, in order to get the window handle, this likely means calling the wx.window __init__ method prior to calling self.GetHandle()

class gui.dpiScalingHelper.DpiScalingHelperMixin(windowHandle: int)

Bases: object

mixin to provide size scaling intended to be used with wx.Window (usually wx.Dialog) Sub-classes are responsible for calling wx.Window init

scaleSize(size: Tuple[int | float, int | float] | int | float) Tuple[int, int] | int
class gui.dpiScalingHelper.DpiScalingHelperMixinWithoutInit

Bases: object

Same concept as DpiScalingHelperMixin, but ensures you do not have to explicitly call the init of wx.Window or this mixin

GetHandle: Callable[[], Any]
_scaleFactor: int | None = None
scaleSize(size: Tuple[int | float, int | float] | int | float) Tuple[int, int] | int

gui.exit module

class gui.exit._ExitAction(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: DisplayStringEnum

EXIT = 1
RESTART = 2
RESTART_WITH_ADDONS_DISABLED = 3
RESTART_WITH_DEBUG_LOGGING_ENABLED = 4
INSTALL_PENDING_UPDATE = 5
property _displayStringLabels

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

class gui.exit.ExitDialog(parent)

Bases: Dialog

_instance = None
onOk(evt)
onCancel(evt)

gui.guiHelper module

Utilities to simplify the creation of wx GUIs, including automatic management of spacing. Example usage:

class myDialog(wx.Dialog):

def __init__(self, parent):

super().__init__(parent, title=’Usage example of guiHelper’)

mainSizer = wx.BoxSizer(wx.VERTICAL)

sHelper = guiHelper.BoxSizerHelper(self, wx.VERTICAL)

# Adding controls with their associated label # according on the control type, they are associated horizontally or vertically. filterElement = sHelper.addLabeledControl(“Filter:”, wx.TextCtrl) symbols = sHelper.addLabeledControl(“Select a row:”, wx.ListCtrl)

# A control with its associated label choice = sHelper.addLabeledControl(“Choose option”, wx.Choice, choices=[“1”, “2”, “3”])

# A single button button = sHelper.addItem(wx.Button(self, label=”Does stuff”))

# for general items checkbox = sHelper.addItem(wx.CheckBox(self, label=”always do something”))

# for groups of buttons buttonGroup = gui.guiHelper.ButtonHelper(wx.VERTICAL) oneButton = buttonGroup.addButton(self, label=”one”) twoButton = buttonGroup.addButton(self, label=”two”) threeButton = buttonGroup.addButton(self, label=”three”) sHelper.addItem(buttonGroup)

mainSizer.Add(sHelper.sizer, border=10, flag=wx.ALL) mainSizer.Fit(self) self.SetSizer(mainSizer)

gui.guiHelper.BORDER_FOR_DIALOGS = 10

border space to be used around all controls in dialogs

gui.guiHelper.SPACE_BETWEEN_VERTICAL_DIALOG_ITEMS = 10

when dialog items are laid out vertically use this much space between them

gui.guiHelper.SPACE_BETWEEN_BUTTONS_HORIZONTAL = 7

put this much space between buttons next to each other horizontally.

gui.guiHelper.SPACE_BETWEEN_BUTTONS_VERTICAL = 5

put this much space between buttons next to each other vertically

gui.guiHelper.SPACE_BETWEEN_ASSOCIATED_CONTROL_HORIZONTAL = 10

put this much space between two horizontally associated elements (such as a wx.StaticText and a wx.Choice or wx.TextCtrl)

gui.guiHelper.SPACE_BETWEEN_ASSOCIATED_CONTROL_VERTICAL = 3

put this much space between two vertically associated elements (such as a wx.StaticText and a wx.Choice or wx.TextCtrl)

gui.guiHelper.autoThaw(control: Window)
class gui.guiHelper.ButtonHelper(orientation)

Bases: object

Class used to ensure that the appropriate space is added between each button, whether in horizontal or vertical arrangement. This class should be used for groups of buttons. While it won’t cause problems to use this class with a single button there is little benefit. Individual buttons can be added directly to a sizer / sizer helper.

@param orientation: the orientation for the buttons, either wx.HORIZONTAL or wx.VERTICAL

property sizer

Useful if you wish to add this group of buttons to another sizer and provide other arguments

addButton(*args, **kwargs)

add another button to the group. Space between the buttons is added automatically. usage hint:

parent = self # a wx window class. EG wx.Dialog myButtonHelper.addButton(dialog, label=_(“my new button”))

@param args: The formal arguments to pass directly to wx.Button. The only required parameter is ‘parent’. @param kwargs: The keyword args passed directly to wx.Button

gui.guiHelper.associateElements(firstElement: Control, secondElement: Control) BoxSizer

Associates two GUI elements together. Handles choosing a layout and appropriate spacing. Abstracts away common pairings used in the NVDA GUI. Currently handles:

wx.StaticText and (wx.Choice, wx.TextCtrl, wx.Slider, wx.Button or wx.SpinCtrl) - Horizontal layout wx.StaticText and (wx.ListCtrl or wx.ListBox or wx.TreeCtrl ) - Vertical layout wx.Button and wx.CheckBox - Horizontal layout wx.TextCtrl and wx.Button - Horizontal layout

class gui.guiHelper.LabeledControlHelper(parent: Window, labelText: str, wxCtrlClass: Type[_LabeledControlT], **kwargs)

Bases: Generic[_LabeledControlT]

Represents a Labeled Control. Provides a class to create and hold on to the objects and automatically associate the two controls together. Relies on guiHelper.associateElements(), any limitations in guiHelper.associateElements() also apply here.

@param parent: An instance of the parent wx window. EG wx.Dialog @param labelText: The text to associate with a wx control. @param wxCtrlClass: The class to associate with the label, eg: wx.TextCtrl @param kwargs: The keyword arguments used to instantiate the wxCtrlClass

EnableChanged

alias of _Event

EVT_ENABLE_CHANGED = <wx.core.PyEventBinder object>
ShowChanged

alias of _Event

EVT_SHOW_CHANGED = <wx.core.PyEventBinder object>
property control: _LabeledControlT
property sizer: BoxSizer
class gui.guiHelper.PathSelectionHelper(parent, buttonText, browseForDirectoryTitle)

Bases: object

Abstracts away details for creating a path selection helper. The path selection helper is a textCtrl with a button in horizontal layout. The Button launches a directory explorer. To get the path selected by the user, use the pathControl property which exposes a wx.TextCtrl.

@param parent: An instance of the parent wx window. EG wx.Dialog @param buttonText: The text for the button to launch a directory dialog (wx.DirDialog). This is typically ‘Browse’ @type buttonText: string @param browseForDirectoryTitle: The text for the title of the directory dialog (wx.DirDialog) @type browseForDirectoryTitle: string

property pathControl
property sizer
getDefaultBrowseForDirectoryPath()
onBrowseForDirectory(evt)
class gui.guiHelper.BoxSizerHelper(parent: Dialog, orientation: int | None = None, sizer: BoxSizer | StaticBoxSizer | None = None)

Bases: object

Used to abstract away spacing logic for a wx.BoxSizer

Init. Pass in either orientation OR sizer. @param parent: An instance of the parent wx window. EG wx.Dialog @param orientation: the orientation to use when constructing the sizer, either wx.HORIZONTAL or wx.VERTICAL @type orientation: wx.HORIZONTAL or wx.VERTICAL @param sizer: the sizer to use rather than constructing one.

_ItemT = ~_ItemT
addItem(item: _ItemT, **keywordArgs) _ItemT

Adds an item with space between it and the previous item. Does not handle adding LabledControlHelper; use L{addLabeledControl} instead. @param item: the item to add to the sizer @param **keywordArgs: the extra args to pass when adding the item to the wx.Sizer. This parameter is

normally not necessary.

addLabeledControl(labelText: str, wxCtrlClass: Type[_LabeledControlT], **kwargs) _LabeledControlT

Convenience method to create a labeled control @param labelText: Text to use when constructing the wx.StaticText to label the control. @param wxCtrlClass: Control class to construct and associate with the label @param kwargs: keyword arguments used to construct the wxCtrlClass. As taken by guiHelper.LabeledControlHelper

Relies on guiHelper.LabeledControlHelper and thus guiHelper.associateElements, and therefore inherits any limitations from there.

_ButtonsT = ~_ButtonsT
addDialogDismissButtons(buttons: _ButtonsT, separated: bool = False) _ButtonsT

Adds and aligns the buttons for dismissing the dialog; e.g. “ok | cancel”. These buttons are expected to be the last items added to the dialog. Buttons that launch an action, do not dismiss the dialog, or are not the last item should be added via L{addItem} @param buttons: The buttons to add @type buttons:

wx.Sizer or guiHelper.ButtonHelper or single wx.Button or a bit list of the following flags: wx.OK, wx.CANCEL, wx.YES, wx.NO, wx.APPLY, wx.CLOSE, wx.HELP, wx.NO_DEFAULT

@param separated:

Whether a separator should be added between the dialog content and its footer. Should be set to L{False} for message or single input dialogs, L{True} otherwise.

class gui.guiHelper.SIPABCMeta(name, bases, namespace, /, **kwargs)

Bases: wrappertype, ABCMeta

Meta class to be used for wx subclasses with abstract methods.

gui.inputGestures module

gui.inputGestures._ScriptsModel

Type for structure returned by inputCore

alias of Dict[str, Union[AllGesturesScriptInfo, KbEmuScriptInfo]]

gui.inputGestures._GesturesModel

Type for structure returned by inputCore

alias of Dict[str, Dict[str, Union[AllGesturesScriptInfo, KbEmuScriptInfo]]]

gui.inputGestures._getAllGestureScriptInfo() Dict[str, Dict[str, AllGesturesScriptInfo | KbEmuScriptInfo]]
gui.inputGestures._formatGesture(identifier)
class gui.inputGestures._GestureVM(normalizedGestureIdentifier: str)

Bases: object

canAdd = False

adding children is not supported.

canRemove = True

gestures can be removed

normalizedGestureIdentifier: str

As per items in inputCore.AllGesturesScriptInfo.gestures

displayName: str

How the gesture should be displayed

class gui.inputGestures._PendingGesture

Bases: object

displayName = 'Enter input gesture:'
canAdd = False
canRemove = False
class gui.inputGestures._ScriptVM(displayName: str, scriptInfo: AllGesturesScriptInfo)

Bases: object

canAdd = True

able to add gestures that trigger this script

canRemove = False

Scripts can not be removed

displayName: str

Translated display name for the script

scriptInfo: AllGesturesScriptInfo
addedGestures: List[_GestureVM]

These will also be in self.gestures

removedGestures: Dict[str, _GestureVM]

These will not be in self.gestures anymore. Key is the normalized Gesture Identifier.

gestures: List[_GestureVM | _PendingGesture]
createPendingGesture() _PendingGesture
finalisePending(normalizedGestureIdentifier: str) _GestureVM
_addGesture(normalizedGestureIdentifier: str) _GestureVM
removeGesture(gestureVM: _GestureVM)
class gui.inputGestures._CategoryVM(displayName: str, scripts: Dict[str, AllGesturesScriptInfo | KbEmuScriptInfo])

Bases: object

canAdd = False

not able to add Scripts

canRemove = False

categories can not be removed

displayName: str

Translated display name for the category

scripts: List[_ScriptVM]
class gui.inputGestures._EmulatedGestureVM(emuGestureInfo: AllGesturesScriptInfo)

Bases: _ScriptVM

displayName: str

Display name for the gesture to be emulated

canAdd = True

able to add gestures that trigger this emulation

scriptInfo: AllGesturesScriptInfo | KbEmuScriptInfo
property canRemove: bool

bool(x) -> bool

Returns True when the argument x is true, False otherwise. The builtins True and False are the only two instances of the class bool. The class bool is a subclass of the class int, and cannot be subclassed.

class gui.inputGestures._PendingEmulatedGestureVM

Bases: object

displayName = 'Enter gesture to emulate:'
canAdd = False
canRemove = False
class gui.inputGestures._EmuCategoryVM(displayName: str, emuGestures: Dict[str, AllGesturesScriptInfo | KbEmuScriptInfo])

Bases: object

displayName = 'Emulated system keyboard keys'

Translated display name for the gesture emulation category

canAdd = True

Can add new emulated gestures

canRemove = False

categories can not be removed

addedKbEmulation: List[_EmulatedGestureVM]

These will also be in self.scripts

removedKbEmulation: Dict[str, _EmulatedGestureVM]

These will not be in self.scripts anymore. Key is the scriptInfo display name.

scripts: List[_ScriptVM | _EmulatedGestureVM | _PendingEmulatedGestureVM]
createPendingEmuGesture() _PendingEmulatedGestureVM
finalisePending(scriptInfo: AllGesturesScriptInfo) _EmulatedGestureVM
_addEmulation(scriptInfo: AllGesturesScriptInfo) _EmulatedGestureVM
removeEmulation(gestureEmulation: _EmulatedGestureVM)
class gui.inputGestures._InputGesturesViewModel

Bases: object

allGestures: List[_CategoryVM | _EmuCategoryVM]
filteredGestures: List[_CategoryVM | _EmuCategoryVM]
isExpectingNewEmuGesture: _EmuCategoryVM | None = None
isExpectingNewGesture: _ScriptVM | None = None
reset()
getFilteredScriptCount()
getIndexInTree(vmSelection: Tuple[_CategoryVM | _EmuCategoryVM, _ScriptVM | _EmulatedGestureVM | _PendingEmulatedGestureVM | None, _GestureVM | _PendingGesture | None])
_fillAllGestures()
commitChanges()
filter(filterText: str)
class gui.inputGestures._GesturesTree(parent, gesturesVM: _InputGesturesViewModel)

Bases: VirtualTree, TreeCtrl

OnGetChildrenCount(index: Tuple[int, ...]) int

This function must be overloaded in the derived class. It should return the number of child items of the item with the provided index. If index == () it should return the number of root items.

OnGetItemText(index: Tuple[int, ...], column: int = 0) str

This function must be overloaded in the derived class. It should return the string containing the text of the specified item.

getSelectedItemData() Tuple[_CategoryVM | _EmuCategoryVM, _ScriptVM | _EmulatedGestureVM | _PendingEmulatedGestureVM | None, _GestureVM | _PendingGesture | None] | None
getData(index: Tuple[int, int | None, int | None]) Tuple[_CategoryVM | _EmuCategoryVM, _ScriptVM | _EmulatedGestureVM | _PendingEmulatedGestureVM | None, _GestureVM | _PendingGesture | None] | None
doRefresh(postFilter=False, focus: Tuple[_CategoryVM | _EmuCategoryVM, _ScriptVM | _EmulatedGestureVM | _PendingEmulatedGestureVM | None, _GestureVM | _PendingGesture | None] | None = None)
class gui.inputGestures.InputGesturesDialog(*args, **kwargs)

Bases: SettingsDialog

@param parent: The parent for this dialog; C{None} for no parent. @param resizeable: True if the settings dialog should be resizable by the user, only set this if

you have tested that the components resize correctly.

@param hasApplyButton: C{True} to add an apply button to the dialog; defaults to C{False} for backwards compatibility.

Deprecated, use buttons instead.

@param settingsSizerOrientation: Either wx.VERTICAL or wx.HORIZONTAL. This controls the orientation of the

sizer that is passed into L{makeSettings}. The default is wx.VERTICAL.

@param multiInstanceAllowed: Whether multiple instances of SettingsDialog may exist.

Note that still only one instance of a particular SettingsDialog subclass may exist at one time.

@param buttons: Buttons to add to the settings dialog.

Should be a subset of {wx.OK, wx.CANCEL, wx.APPLY, wx.CLOSE}.

title = 'Input Gestures'
helpId = 'InputGestures'
makeSettings(settingsSizer)

Populate the dialog with settings controls. Subclasses must override this method. @param sizer: The sizer to which to add the settings controls. @type sizer: wx.Sizer

postInit()

Called after the dialog has been created. For example, this might be used to set focus to the desired control. Sub-classes may override this method.

_onWindowDestroy(evt)
_abc_impl = <_abc._abc_data object>
onFilterChange(evt)
filter(filterText: str)
onTreeSelect(evt)
_refreshButtonState()
onAdd(evt)
_addCaptured(catVM: _CategoryVM | _EmuCategoryVM, scriptVM: _ScriptVM | _EmulatedGestureVM | _PendingEmulatedGestureVM, gesture)
_addChoice(catVM: _CategoryVM | _EmuCategoryVM, scriptVM: _ScriptVM | _EmulatedGestureVM | _PendingEmulatedGestureVM, gid: str)
Parameters:
  • scriptVM – The script to add the gesture to

  • gid – Normalized gesture ID to be added.

Returns:

_addCapturedKbEmu(gesture: InputGesture, catVM: _EmulatedGestureVM)
onRemove(evt)
onReset(evt)
onOk(evt)

Take action in response to the OK button being pressed. Sub-classes may extend this method. This base method should always be called to clean up the dialog.

_onDestroyTree(evt: WindowDestroyEvent)

gui.installerGui module

gui.installerGui._canPortableConfigBeCopied() bool
gui.installerGui.doInstall(createDesktopShortcut=True, startOnLogon=True, isUpdate=False, copyPortableConfig=False, silent=False, startAfterInstall=True)
gui.installerGui._generate_executionParameters() str
gui.installerGui.doSilentInstall(copyPortableConfig=False, startAfterInstall=True)
class gui.installerGui.InstallerDialog(parent, isUpdate)

Bases: DpiScalingHelperMixinWithoutInit, ContextHelpMixin, Dialog

helpId = 'InstallingNVDA'
onInstall(evt)
onCancel(evt)
onReviewAddons(evt)
class gui.installerGui.InstallingOverNewerVersionDialog

Bases: DpiScalingHelperMixinWithoutInit, ContextHelpMixin, Dialog

helpId = 'InstallingNVDA'
gui.installerGui.showInstallGui()
gui.installerGui._nvdaExistsInDir(directory: str) bool
gui.installerGui._warnAndConfirmForNonEmptyDirectory(portableDirectory: str) bool

Display a warning message if the specified directory is not empty. :param portableDirectory: The directory to check. :return: True if the user wants to continue, False if the user wants to cancel.

gui.installerGui._getUniqueNewPortableDirectory(basePath: str) str

Generate a new directory name for a portable copy of NVDA. :param basePath: The base path to use. :return: A new directory name.

class gui.installerGui.PortableCreaterDialog(parent)

Bases: ContextHelpMixin, Dialog

helpId = 'CreatePortableCopy'
onCreatePortable(evt)
onCancel(evt)
gui.installerGui.doCreatePortable(portableDirectory: str, copyUserConfig: bool = False, silent: bool = False, startAfterCreate: bool = False, warnForNonEmptyDirectory: bool = True) None

Create a portable copy of NVDA. :param portableDirectory: The directory in which to create the portable copy. :param copyUserConfig: Whether to copy the current user configuration. :param silent: Whether to suppress messages. :param startAfterCreate: Whether to start the new portable copy after creation. :param warnForNonEmptyDirectory: Whether to warn if the destination directory is not empty.

gui.logViewer module

Provides functionality to view the NVDA log.

gui.logViewer.logViewer = None

The singleton instance of the log viewer UI.

class gui.logViewer.LogViewer(parent)

Bases: ContextHelpMixin, Frame

The NVDA log viewer GUI.

helpId = 'LogViewer'
refresh(evt=None)
onActivate(evt)
onClose(evt)
onSaveAsCommand(evt)
onOutputKeyDown(evt)
gui.logViewer.activate()

Activate the log viewer. If the log viewer has not already been created and opened, this will create and open it. Otherwise, it will be brought to the foreground if possible.

gui.message module

gui.message.isModalMessageBoxActive() bool

gui.message.messageBox is a function which blocks the calling thread, until a user responds to the modal dialog. When some action (e.g. quitting NVDA) should be prevented due to any active modal message box, even if unrelated, use isModalMessageBoxActive to check before triggering the action. NVDA is in an uncertain state while waiting for an answer from a gui.message.messageBox.

It’s possible for multiple message boxes to be open at a time. This function can be used to check before opening subsequent gui.message.messageBox instances.

Because an answer is required to continue after a modal messageBox is opened, some actions such as shutting down are prevented while NVDA is in a possibly uncertain state.

@return: True if a thread blocking modal response is still pending.

gui.message.displayDialogAsModal(dialog: Dialog) int

Display a dialog as modal. @return: Same as for wx.MessageBox.

displayDialogAsModal is a function which blocks the calling thread, until a user responds to the modal dialog. This function should be used when an answer is required before proceeding.

It’s possible for multiple message boxes to be open at a time. Before opening a new messageBox, use isModalMessageBoxActive to check if another messageBox modal response is still pending.

Because an answer is required to continue after a modal messageBox is opened, some actions such as shutting down are prevented while NVDA is in a possibly uncertain state.

gui.message.messageBox(message: str, caption: str = b'Message', style: int = 5, parent: Window | None = None) int

Display a message dialog. Avoid using C{wx.MessageDialog} and C{wx.MessageBox} directly. @param message: The message text. @param caption: The caption (title) of the dialog. @param style: Same as for wx.MessageBox. @param parent: The parent window. @return: Same as for wx.MessageBox.

gui.message.messageBox is a function which blocks the calling thread, until a user responds to the modal dialog. This function should be used when an answer is required before proceeding. Consider using a custom subclass of a wxDialog if an answer is not required or a default answer can be provided.

It’s possible for multiple message boxes to be open at a time. Before opening a new messageBox, use isModalMessageBoxActive to check if another messageBox modal response is still pending.

Because an answer is required to continue after a modal messageBox is opened, some actions such as shutting down are prevented while NVDA is in a possibly uncertain state.

exception gui.message.DisplayableError(displayMessage: str, titleMessage: str | None = None)

Bases: Exception

@param displayMessage: A translated message, to be displayed to the user. @param titleMessage: A translated message, to be used as a title for the display message. If left None, “Error” is presented as the title by default.

OnDisplayableErrorT

A type of extension point used to notify a handler when an error occurs. This allows a handler to handle displaying an error.

@param displayableError: Error that can be displayed to the user. @type displayableError: DisplayableError

alias of Action

displayError(parentWindow: Window)

gui.nvdaControls module

class gui.nvdaControls.AutoWidthColumnListCtrl(parent, id=-1, autoSizeColumn='LAST', itemTextCallable=None, pos=wx.Point(-1, -1), size=wx.Size(-1, -1), style=0)

Bases: ListCtrl, ListCtrlAutoWidthMixin

A list control that allows you to specify a column to resize to take up the remaining width of a wx.ListCtrl. It also changes L{OnGetItemText} to call an optionally provided callable, and adds a l{sendListItemFocusedEvent} method.

initialiser Takes the same parameter as a wx.ListCtrl with the following additions: @param autoSizeColumn: defaults to “LAST” which results in the last column being resized.

Pass the column number to be resized, valid values: 1 to N

@type autoSizeColumn: int @param itemTextCallable: A callable to be called to get the item text for a particular item’s column in the list.

It should accept the same parameters as L{OnGetItemText},

@type itemTextCallable: L{callable}

_onDestroy(evt)
_super_itemTextCallable(item, column)
OnGetItemText(item, column) String

This function must be overridden in the derived class for a control with wxLC_VIRTUAL style.

sendListItemFocusedEvent(index)
class gui.nvdaControls.SelectOnFocusSpinCtrl(parent, id=-1, value='', pos=wx.Point(-1, -1), size=wx.Size(-1, -1), style=16896, min=0, max=100, initial=0, name='labelStr')

Bases: SpinCtrl

A spin control that automatically selects the value when the control gains focus. This makes editing the values quicker.

initialiser - Takes the same parameters as a wx.SpinCtrl.

OnSetFocus(evt)
class gui.nvdaControls.ListCtrlAccessible

Bases: Accessible

WX Accessible implementation for checkable lists which aren’t fully accessible.

GetRole(childId)

Returns a role constant describing this object.

GetState(childId)

Returns a state constant.

class gui.nvdaControls.CustomCheckListBox(*args, **kwargs)

Bases: CheckListBox

Custom checkable list to fix a11y bugs in the standard wx checkable list box.

notifyIAccessible(evt)
class gui.nvdaControls.AutoWidthColumnCheckListCtrl(parent, id=-1, autoSizeColumn='LAST', pos=wx.Point(-1, -1), size=wx.Size(-1, -1), style=0, check_image=None, uncheck_image=None, imgsz=(16, 16))

Bases: AutoWidthColumnListCtrl, CheckListCtrlMixin

An L{AutoWidthColumnListCtrl} with accessible checkboxes per item. In contrast with L{CustomCheckableListBox}, this class supports multiple columns. Also note that this class ignores the L{CheckListCtrlMixin.OnCheckItem} callback. If you want to be notified of checked/unchecked events, create an event handler for wx.EVT_CHECKLISTBOX. This event is only fired when an item is toggled with the mouse or keyboard.

initialiser Takes the same parameter as a wx.ListCtrl with the following additions: @param autoSizeColumn: defaults to “LAST” which results in the last column being resized.

Pass the column number to be resized, valid values: 1 to N

@type autoSizeColumn: int @param itemTextCallable: A callable to be called to get the item text for a particular item’s column in the list.

It should accept the same parameters as L{OnGetItemText},

@type itemTextCallable: L{callable}

GetCheckedItems()
SetCheckedItems(indexes)
property CheckedItems
onCharHook(evt)
onLeftDown(evt)

Additional event handler for mouse clicks to call L{sendCheckListBoxEvent}.

CheckItem(index, check=True)

Adapted from L{CheckListCtrlMixin} to ignore the OnCheckItem callback and to call L{notifyIAccessible}.

notifyIAccessible(index)
sendCheckListBoxEvent(index)
class gui.nvdaControls.DPIScaledDialog(*args, **kwargs)

Bases: Dialog, DpiScalingHelperMixin

Automatically calls constructors in the right order, passing on arguments, and providing scaling features. Until wxWidgets/wxWidgets#334 is resolved, and we have updated to that build of wx.

Called in place of wx.Dialog __init__ arguments are forwarded on. Expected args (from wx docs): parent, id, title, pos=wx.DefaultPosition, size=wx.DefaultSize, style=wx.DEFAULT_DIALOG_STYLE, name=wx.DialogNameStr where: wx.DEFAULT_DIALOG_STYLE = (wxCAPTION | wxSYSTEM_MENU | wxCLOSE_BOX)

class gui.nvdaControls.MessageDialog(parent, title, message, dialogType=1)

Bases: DPIScaledDialog

Provides a more flexible message dialog. Consider overriding _addButtons, to set your own buttons and behaviour.

Called in place of wx.Dialog __init__ arguments are forwarded on. Expected args (from wx docs): parent, id, title, pos=wx.DefaultPosition, size=wx.DefaultSize, style=wx.DEFAULT_DIALOG_STYLE, name=wx.DialogNameStr where: wx.DEFAULT_DIALOG_STYLE = (wxCAPTION | wxSYSTEM_MENU | wxCLOSE_BOX)

DIALOG_TYPE_STANDARD = 1
DIALOG_TYPE_WARNING = 2
DIALOG_TYPE_ERROR = 3
_DIALOG_TYPE_ICON_ID_MAP = {2: b'wxART_WARNING', 3: b'wxART_ERROR'}
_DIALOG_TYPE_SOUND_ID_MAP = {2: 64, 3: 16}
_addButtons(buttonHelper)

Adds ok / cancel buttons. Can be overridden to provide alternative functionality.

_addContents(contentsSizer: BoxSizerHelper)

Adds additional contents to the dialog, before the buttons. Subclasses may implement this method.

_setIcon(type)
_setSound(type)
_playSound()
_onDialogActivated(evt)
_onShowEvt(evt)
class gui.nvdaControls.EnhancedInputSlider(*args, **kwargs)

Bases: Slider

SetValue(value)

Sets the slider position.

onSliderChar(evt)
class gui.nvdaControls.TabbableScrolledPanel(parent, id=-1, pos=wx.Point(-1, -1), size=wx.Size(-1, -1), style=524288, name='scrolledpanel')

Bases: ScrolledPanel

This class was created to ensure a ScrolledPanel scrolls to nested children of the panel when navigating with tabs (#12224). A PR to wxPython implementing this fix can be tracked on https://github.com/wxWidgets/Phoenix/pull/1950

Default class constructor.

Parameters:
  • parent (wx.Window) – parent window. Must not be None;

  • id (integer) – window identifier. A value of -1 indicates a default value;

  • pos (tuple or wx.Point) – the control position. A value of (-1, -1) indicates a default position, chosen by either the windowing system or wxPython, depending on platform;

  • size (tuple or wx.Size) – the control size. A value of (-1, -1) indicates a default size, chosen by either the windowing system or wxPython, depending on platform;

  • style (integer) – the underlying wx.ScrolledWindow style;

  • name (string) – the scrolled panel name.

GetChildRectRelativeToSelf(child: Window) Rect

window.GetRect returns the size of a window, and its position relative to its parent. When calculating ScrollChildIntoView, the position relative to its parent is not relevant unless the parent is the ScrolledPanel itself. Instead, calculate the position relative to scrolledPanel

ScrollChildIntoView(child: Window) None

Overrides child.GetRect with GetChildRectRelativeToSelf before calling super().ScrollChildIntoView. super().ScrollChildIntoView incorrectly uses child.GetRect to navigate scrolling, which is relative to the parent, where it should instead be relative to this ScrolledPanel.

class gui.nvdaControls.FeatureFlagCombo(parent: ~wx._core.Window, keyPath: ~typing.List[str], conf: ~config.ConfigManager, pos=wx.Point(-1, -1), size=wx.Size(-1, -1), style=0, validator=<wx._core.Validator object>, name=b'choice', onChoiceEventHandler: ~typing.Callable[[~wx._core.CommandEvent], None] | None = None)

Bases: Choice

Creates a combobox (wx.Choice) with a list of feature flags.

Parameters:
  • parent – The parent window.

  • keyPath – The list of keys required to get to the config value.

  • conf – The config.conf object.

  • pos – The position of the control. Forwarded to wx.Choice

  • size – The size of the control. Forwarded to wx.Choice

  • style – The style of the control. Forwarded to wx.Choice

  • validator – The validator for the control. Forwarded to wx.Choice

  • name – The name of the control. Forwarded to wx.Choice

  • onChoiceEventHandler – Event handler bound for EVT_CHOICE

defaultValue

The default value of the config spec. Not the “behavior of default”. This is provided to maintain compatibility with other controls in the advanced settings dialog.

_getChoiceIndex(value: FlagValueEnum) int
_getConfSpecDefaultValue() FlagValueEnum
_getConfigValue() FeatureFlag
isValueConfigSpecDefault() bool

Does the current value of the control match the default value from the config spec? This is not the same as the “behaviour of default”.

resetToConfigSpecDefault() None

Set the value of the control to the default value from the config spec.

_getControlCurrentValue() Enum
_getControlCurrentFlag() FeatureFlag
saveCurrentValueToConf() None

Set the config value to the current value of the control.

_createOptionsDict(translatedOptions: OrderedDict[FlagValueEnum, str]) OrderedDict[Enum, str]

gui.settingsDialogs module

class gui.settingsDialogs.SettingsDialog(*args, **kwargs)

Bases: DpiScalingHelperMixinWithoutInit, ContextHelpMixin, Dialog

A settings dialog. A settings dialog consists of one or more settings controls and OK and Cancel buttons and an optional Apply button. Action may be taken in response to the OK, Cancel or Apply buttons.

To use this dialog:
  • Set L{title} to the title of the dialog.

  • Override L{makeSettings} to populate a given sizer with the settings controls.

  • Optionally, override L{postInit} to perform actions after the dialog is created, such as setting the focus. Be

    aware that L{postInit} is also called by L{onApply}.

  • Optionally, extend one or more of L{onOk}, L{onCancel} or L{onApply} to perform actions in response to the

    OK, Cancel or Apply buttons, respectively.

@ivar title: The title of the dialog. @type title: str

@param parent: The parent for this dialog; C{None} for no parent. @param resizeable: True if the settings dialog should be resizable by the user, only set this if

you have tested that the components resize correctly.

@param hasApplyButton: C{True} to add an apply button to the dialog; defaults to C{False} for backwards compatibility.

Deprecated, use buttons instead.

@param settingsSizerOrientation: Either wx.VERTICAL or wx.HORIZONTAL. This controls the orientation of the

sizer that is passed into L{makeSettings}. The default is wx.VERTICAL.

@param multiInstanceAllowed: Whether multiple instances of SettingsDialog may exist.

Note that still only one instance of a particular SettingsDialog subclass may exist at one time.

@param buttons: Buttons to add to the settings dialog.

Should be a subset of {wx.OK, wx.CANCEL, wx.APPLY, wx.CLOSE}.

exception MultiInstanceError

Bases: RuntimeError

exception MultiInstanceErrorWithDialog(dialog: SettingsDialog, *args: object)

Bases: MultiInstanceError

dialog: SettingsDialog
class DialogState(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: IntEnum

CREATED = 0
DESTROYED = 1
_instances = <WeakKeyDictionary at 0x81fc910>
title = ''
helpId = 'NVDASettings'
shouldSuspendConfigProfileTriggers = True
_setInstanceDestroyedState()
_enterActivatesOk_ctrlSActivatesApply(evt)

Listens for keyboard input and triggers ok button on enter and triggers apply button when control + S is pressed. Cancel behavior is built into wx. Pressing enter will also close the dialog when a list has focus (e.g. the list of symbols in the symbol pronunciation dialog). Without this custom handler, enter would propagate to the list control (wx ticket #3725).

abstract makeSettings(sizer)

Populate the dialog with settings controls. Subclasses must override this method. @param sizer: The sizer to which to add the settings controls. @type sizer: wx.Sizer

postInit()

Called after the dialog has been created. For example, this might be used to set focus to the desired control. Sub-classes may override this method.

onOk(evt: CommandEvent)

Take action in response to the OK button being pressed. Sub-classes may extend this method. This base method should always be called to clean up the dialog.

onCancel(evt: CommandEvent)

Take action in response to the Cancel button being pressed. Sub-classes may extend this method. This base method should always be called to clean up the dialog.

onClose(evt: CommandEvent)

Take action in response to the Close button being pressed. Sub-classes may extend this method. This base method should always be called to clean up the dialog.

onApply(evt: CommandEvent)

Take action in response to the Apply button being pressed. Sub-classes may extend or override this method. This base method should be called to run the postInit method.

_onWindowDestroy(evt: WindowDestroyEvent)
_abc_impl = <_abc._abc_data object>
class gui.settingsDialogs.SettingsPanel(parent: Window)

Bases: DpiScalingHelperMixinWithoutInit, ContextHelpMixin, Panel

A settings panel, to be used in a multi category settings dialog. A settings panel consists of one or more settings controls. Action may be taken in response to the parent dialog’s OK or Cancel buttons.

To use this panel:
  • Set L{title} to the title of the category.

  • Override L{makeSettings} to populate a given sizer with the settings controls.

  • Optionally, extend L{onPanelActivated} to perform actions after the category has been selected in the list of categories, such as synthesizer or braille display list population.

  • Optionally, extend L{onPanelDeactivated} to perform actions after the category has been deselected (i.e. another category is selected) in the list of categories.

  • Optionally, extend one or both of L{onSave} or L{onDiscard} to perform actions in response to the parent dialog’s OK or Cancel buttons, respectively.

  • Optionally, extend one or both of L{isValid} or L{postSave} to perform validation before or steps after saving, respectively.

@ivar title: The title of the settings panel, also listed in the list of settings categories. @type title: str

@param parent: The parent for this panel; C{None} for no parent.

title = ''
panelDescription = ''
_buildGui()
abstract makeSettings(sizer: BoxSizer)

Populate the panel with settings controls. Subclasses must override this method. @param sizer: The sizer to which to add the settings controls.

onPanelActivated()

Called after the panel has been activated (i.e. de corresponding category is selected in the list of categories). For example, this might be used for resource intensive tasks. Sub-classes should extend this method.

onPanelDeactivated()

Called after the panel has been deactivated (i.e. another category has been selected in the list of categories). Sub-classes should extendthis method.

abstract onSave()

Take action in response to the parent’s dialog OK or apply button being pressed. Sub-classes should override this method. MultiCategorySettingsDialog is responsible for cleaning up the panel when OK is pressed.

isValid() bool

Evaluate whether the current circumstances of this panel are valid and allow saving all the settings in a L{MultiCategorySettingsDialog}. Sub-classes may extend this method. @returns: C{True} if validation should continue,

C{False} otherwise.

_validationErrorMessageBox(message: str, option: str, category: str | None = None)
postSave()

Take action whenever saving settings for all panels in a L{MultiCategorySettingsDialog} succeeded. Sub-classes may extend this method.

onDiscard()

Take action in response to the parent’s dialog Cancel button being pressed. Sub-classes may override this method. MultiCategorySettingsDialog is responsible for cleaning up the panel when Cancel is pressed.

_sendLayoutUpdatedEvent()

Notify any wx parents that may be listening that they should redo their layout in whatever way makes sense for them. It is expected that sub-classes call this method in response to changes in the number of GUI items in their panel.

_abc_impl = <_abc._abc_data object>
class gui.settingsDialogs.SettingsPanelAccessible

Bases: Accessible

WX Accessible implementation to set the role of a settings panel to property page, as well as to set the accessible description based on the panel’s description.

GetRole(childId)

Returns a role constant describing this object.

GetDescription(childId)

Returns the description for this object or a child.

class gui.settingsDialogs.MultiCategorySettingsDialog(*args, **kwargs)

Bases: SettingsDialog

A settings dialog with multiple settings categories. A multi category settings dialog consists of a list view with settings categories on the left side, and a settings panel on the right side of the dialog. Furthermore, in addition to Ok and Cancel buttons, it has an Apply button by default, which is different from the default behavior of L{SettingsDialog}.

To use this dialog: set title and populate L{categoryClasses} with subclasses of SettingsPanel. Make sure that L{categoryClasses} only contains panels that are available on a particular system. For example, if a certain category of settings is only supported on Windows 10 and higher, that category should be left out of L{categoryClasses}

@param parent: The parent for this dialog; C{None} for no parent. @type parent: wx.Window @param initialCategory: The initial category to select when opening this dialog @type parent: SettingsPanel

title = ''
categoryClasses: List[Type[SettingsPanel]] = []
exception CategoryUnavailableError

Bases: RuntimeError

INITIAL_SIZE = (800, 480)
MIN_SIZE = (470, 240)
makeSettings(settingsSizer)

Populate the dialog with settings controls. Subclasses must override this method. @param sizer: The sizer to which to add the settings controls. @type sizer: wx.Sizer

_getCategoryPanel(catId)
postInit()

Called after the dialog has been created. For example, this might be used to set focus to the desired control. Sub-classes may override this method.

onCharHook(evt)

Listens for keyboard input and switches panels for control+tab

_onPanelLayoutChanged(evt)
_doCategoryChange(newCatId)
onCategoryChange(evt)
_validateAllPanels()

Check if all panels are valid, and can be saved @note: raises ValueError if a panel is not valid. See c{SettingsPanel.isValid}

_saveAllPanels()
_notifyAllPanelsSaveOccurred()
_doSave()
onOk(evt)

Take action in response to the OK button being pressed. Sub-classes may extend this method. This base method should always be called to clean up the dialog.

onCancel(evt)

Take action in response to the Cancel button being pressed. Sub-classes may extend this method. This base method should always be called to clean up the dialog.

onApply(evt)

Take action in response to the Apply button being pressed. Sub-classes may extend or override this method. This base method should be called to run the postInit method.

_abc_impl = <_abc._abc_data object>
class gui.settingsDialogs.GeneralSettingsPanel(parent: Window)

Bases: SettingsPanel

@param parent: The parent for this panel; C{None} for no parent.

title = 'General'
helpId = 'GeneralSettings'
LOG_LEVELS = ((100, 'disabled'), (20, 'info'), (15, 'debug warning'), (12, 'input/output'), (10, 'debug'))
makeSettings(settingsSizer)

Populate the panel with settings controls. Subclasses must override this method. @param sizer: The sizer to which to add the settings controls.

onCopySettings(evt)
onSave()

Take action in response to the parent’s dialog OK or apply button being pressed. Sub-classes should override this method. MultiCategorySettingsDialog is responsible for cleaning up the panel when OK is pressed.

postSave()

Take action whenever saving settings for all panels in a L{MultiCategorySettingsDialog} succeeded. Sub-classes may extend this method.

_abc_impl = <_abc._abc_data object>
class gui.settingsDialogs.LanguageRestartDialog(parent)

Bases: ContextHelpMixin, Dialog

helpId = 'GeneralSettingsLanguage'
onRestartNowButton(evt)
class gui.settingsDialogs.SpeechSettingsPanel(parent: Window)

Bases: SettingsPanel

@param parent: The parent for this panel; C{None} for no parent.

title = 'Speech'
helpId = 'SpeechSettings'
makeSettings(settingsSizer)

Populate the panel with settings controls. Subclasses must override this method. @param sizer: The sizer to which to add the settings controls.

_enterTriggersOnChangeSynth(evt)
onChangeSynth(evt)
updateCurrentSynth()
onPanelActivated()

Called after the panel has been activated (i.e. de corresponding category is selected in the list of categories). For example, this might be used for resource intensive tasks. Sub-classes should extend this method.

onPanelDeactivated()

Called after the panel has been deactivated (i.e. another category has been selected in the list of categories). Sub-classes should extendthis method.

onDiscard()

Take action in response to the parent’s dialog Cancel button being pressed. Sub-classes may override this method. MultiCategorySettingsDialog is responsible for cleaning up the panel when Cancel is pressed.

onSave()

Take action in response to the parent’s dialog OK or apply button being pressed. Sub-classes should override this method. MultiCategorySettingsDialog is responsible for cleaning up the panel when OK is pressed.

isValid() bool

Evaluate whether the current circumstances of this panel are valid and allow saving all the settings in a L{MultiCategorySettingsDialog}. Sub-classes may extend this method. @returns: C{True} if validation should continue,

C{False} otherwise.

_abc_impl = <_abc._abc_data object>
class gui.settingsDialogs.SynthesizerSelectionDialog(*args, **kwargs)

Bases: SettingsDialog

@param parent: The parent for this dialog; C{None} for no parent. @param resizeable: True if the settings dialog should be resizable by the user, only set this if

you have tested that the components resize correctly.

@param hasApplyButton: C{True} to add an apply button to the dialog; defaults to C{False} for backwards compatibility.

Deprecated, use buttons instead.

@param settingsSizerOrientation: Either wx.VERTICAL or wx.HORIZONTAL. This controls the orientation of the

sizer that is passed into L{makeSettings}. The default is wx.VERTICAL.

@param multiInstanceAllowed: Whether multiple instances of SettingsDialog may exist.

Note that still only one instance of a particular SettingsDialog subclass may exist at one time.

@param buttons: Buttons to add to the settings dialog.

Should be a subset of {wx.OK, wx.CANCEL, wx.APPLY, wx.CLOSE}.

title = 'Select Synthesizer'
helpId = 'SynthesizerSelection'
synthNames: List[str] = []
makeSettings(settingsSizer)

Populate the dialog with settings controls. Subclasses must override this method. @param sizer: The sizer to which to add the settings controls. @type sizer: wx.Sizer

postInit()

Called after the dialog has been created. For example, this might be used to set focus to the desired control. Sub-classes may override this method.

updateSynthesizerList()
onOk(evt)

Take action in response to the OK button being pressed. Sub-classes may extend this method. This base method should always be called to clean up the dialog.

_abc_impl = <_abc._abc_data object>
class gui.settingsDialogs.DriverSettingChanger(driver, setting)

Bases: object

Functor which acts as callback for GUI events.

property driver
class gui.settingsDialogs.StringDriverSettingChanger(driver, setting, container)

Bases: DriverSettingChanger

Same as L{DriverSettingChanger} but handles combobox events.

class gui.settingsDialogs.AutoSettingsMixin(*args, **kwargs)

Bases: object

Mixin class that provides support for driver/vision provider specific gui settings. Derived classes should implement: - L{getSettings} - L{settingsSizer} Derived classes likely need to inherit from L{SettingsPanel}, in particular the following methods must be provided: - makeSettings - onPanelActivated @note: This mixin uses self.lastControl and self.sizerDict to keep track of the controls added / and maintain ordering. If you plan to maintain other controls in the same panel care will need to be taken.

Mixin init, forwards args to other base class. The other base class is likely L{gui.SettingsPanel}. @param args: Positional args to passed to other base class. @param kwargs: Keyword args to passed to other base class.

settingsSizer: BoxSizer
abstract getSettings() AutoSettings
abstract makeSettings(sizer: BoxSizer)

Populate the panel with settings controls. @note: Normally classes also inherit from settingsDialogs.SettingsPanel. @param sizer: The sizer to which to add the settings controls.

_getSettingsStorage() Any

Override to change storage object for setting values.

property hasOptions: bool
classmethod _setSliderStepSizes(slider, setting)
_getSettingControlHelpId(controlId)

Define the helpId associated to this control.

_makeSliderSettingControl(setting: NumericDriverSetting, settingsStorage: Any) BoxSizer

Constructs appropriate GUI controls for given L{DriverSetting} such as label and slider. @param setting: Setting to construct controls for @param settingsStorage: where to get initial values / set values.

This param must have an attribute with a name matching setting.id. In most cases it will be of type L{AutoSettings}

@return: wx.BoxSizer containing newly created controls.

_makeStringSettingControl(setting: DriverSetting, settingsStorage: Any)

Same as L{_makeSliderSettingControl} but for string settings displayed in a wx.Choice control Options for the choice control come from the availableXstringvalues property (Dict[id, StringParameterInfo]) on the instance returned by self.getSettings() The id of the value is stored on settingsStorage. Returns sizer with label and combobox.

_makeBooleanSettingControl(setting: BooleanDriverSetting, settingsStorage: Any)

Same as L{_makeSliderSettingControl} but for boolean settings. Returns checkbox.

updateDriverSettings(changedSetting=None)

Creates, hides or updates existing GUI controls for all of supported settings.

_createNewControl(setting, settingsStorage)
_getSettingMaker(setting)
_updateValueForControl(setting, settingsStorage)
onDiscard()
onSave()
refreshGui()
onPanelActivated()

Called after the panel has been activated @note: Normally classes also inherit from settingsDialogs.SettingsPanel.

_abc_impl = <_abc._abc_data object>
class gui.settingsDialogs.VoiceSettingsPanel(*args, **kwargs)

Bases: AutoSettingsMixin, SettingsPanel

Mixin init, forwards args to other base class. The other base class is likely L{gui.SettingsPanel}. @param args: Positional args to passed to other base class. @param kwargs: Keyword args to passed to other base class.

title = 'Voice'
helpId = 'SpeechSettings'
property driver
getSettings() AutoSettings
_getSettingControlHelpId(controlId)

Define the helpId associated to this control.

makeSettings(settingsSizer)

Populate the panel with settings controls. @note: Normally classes also inherit from settingsDialogs.SettingsPanel. @param sizer: The sizer to which to add the settings controls.

_appendSymbolDictionariesList(settingsSizerHelper: BoxSizerHelper) None
_appendSpeechModesList(settingsSizerHelper: BoxSizerHelper) None
_appendDelayedCharacterDescriptions(settingsSizerHelper: BoxSizerHelper) None
onSave()

Take action in response to the parent’s dialog OK or apply button being pressed. Sub-classes should override this method. MultiCategorySettingsDialog is responsible for cleaning up the panel when OK is pressed.

_onSpeechModesListChange(evt: CommandEvent)
_onUnicodeNormalizationChange(evt: CommandEvent)
isValid() bool

Evaluate whether the current circumstances of this panel are valid and allow saving all the settings in a L{MultiCategorySettingsDialog}. Sub-classes may extend this method. @returns: C{True} if validation should continue,

C{False} otherwise.

_abc_impl = <_abc._abc_data object>
settingsSizer: BoxSizer
class gui.settingsDialogs.KeyboardSettingsPanel(parent: Window)

Bases: SettingsPanel

@param parent: The parent for this panel; C{None} for no parent.

title = 'Keyboard'
helpId = 'KeyboardSettings'
makeSettings(settingsSizer)

Populate the panel with settings controls. Subclasses must override this method. @param sizer: The sizer to which to add the settings controls.

isValid() bool

Evaluate whether the current circumstances of this panel are valid and allow saving all the settings in a L{MultiCategorySettingsDialog}. Sub-classes may extend this method. @returns: C{True} if validation should continue,

C{False} otherwise.

onSave()

Take action in response to the parent’s dialog OK or apply button being pressed. Sub-classes should override this method. MultiCategorySettingsDialog is responsible for cleaning up the panel when OK is pressed.

_abc_impl = <_abc._abc_data object>
class gui.settingsDialogs.MouseSettingsPanel(parent: Window)

Bases: SettingsPanel

@param parent: The parent for this panel; C{None} for no parent.

title = 'Mouse'
helpId = 'MouseSettings'
makeSettings(settingsSizer)

Populate the panel with settings controls. Subclasses must override this method. @param sizer: The sizer to which to add the settings controls.

onSave()

Take action in response to the parent’s dialog OK or apply button being pressed. Sub-classes should override this method. MultiCategorySettingsDialog is responsible for cleaning up the panel when OK is pressed.

_abc_impl = <_abc._abc_data object>
class gui.settingsDialogs.ReviewCursorPanel(parent: Window)

Bases: SettingsPanel

@param parent: The parent for this panel; C{None} for no parent.

title = 'Review Cursor'
helpId = 'ReviewCursorSettings'
makeSettings(settingsSizer)

Populate the panel with settings controls. Subclasses must override this method. @param sizer: The sizer to which to add the settings controls.

onSave()

Take action in response to the parent’s dialog OK or apply button being pressed. Sub-classes should override this method. MultiCategorySettingsDialog is responsible for cleaning up the panel when OK is pressed.

_abc_impl = <_abc._abc_data object>
class gui.settingsDialogs.InputCompositionPanel(parent: Window)

Bases: SettingsPanel

@param parent: The parent for this panel; C{None} for no parent.

title = 'Input Composition'
helpId = 'InputCompositionSettings'
makeSettings(settingsSizer)

Populate the panel with settings controls. Subclasses must override this method. @param sizer: The sizer to which to add the settings controls.

onSave()

Take action in response to the parent’s dialog OK or apply button being pressed. Sub-classes should override this method. MultiCategorySettingsDialog is responsible for cleaning up the panel when OK is pressed.

_abc_impl = <_abc._abc_data object>
class gui.settingsDialogs.ObjectPresentationPanel(parent: Window)

Bases: SettingsPanel

@param parent: The parent for this panel; C{None} for no parent.

panelDescription = 'Configure how much information NVDA will present about controls. These options apply to focus reporting and NVDA object navigation, but not when reading text content e.g. web content with browse mode.'
title = 'Object Presentation'
helpId = 'ObjectPresentationSettings'
progressLabels = (('off', 'off'), ('speak', 'Speak'), ('beep', 'Beep'), ('both', 'Speak and beep'))
makeSettings(settingsSizer)

Populate the panel with settings controls. Subclasses must override this method. @param sizer: The sizer to which to add the settings controls.

onSave()

Take action in response to the parent’s dialog OK or apply button being pressed. Sub-classes should override this method. MultiCategorySettingsDialog is responsible for cleaning up the panel when OK is pressed.

_abc_impl = <_abc._abc_data object>
class gui.settingsDialogs.BrowseModePanel(parent: Window)

Bases: SettingsPanel

@param parent: The parent for this panel; C{None} for no parent.

title = 'Browse Mode'
helpId = 'BrowseModeSettings'
makeSettings(settingsSizer)

Populate the panel with settings controls. Subclasses must override this method. @param sizer: The sizer to which to add the settings controls.

onSave()

Take action in response to the parent’s dialog OK or apply button being pressed. Sub-classes should override this method. MultiCategorySettingsDialog is responsible for cleaning up the panel when OK is pressed.

_abc_impl = <_abc._abc_data object>
class gui.settingsDialogs.DocumentFormattingPanel(parent: Window)

Bases: SettingsPanel

@param parent: The parent for this panel; C{None} for no parent.

title = 'Document Formatting'
helpId = 'DocumentFormattingSettings'
panelDescription = 'The following options control the types of document formatting reported by NVDA.'
makeSettings(settingsSizer)

Populate the panel with settings controls. Subclasses must override this method. @param sizer: The sizer to which to add the settings controls.

_onLineIndentationChange(evt: CommandEvent) None
onSave()

Take action in response to the parent’s dialog OK or apply button being pressed. Sub-classes should override this method. MultiCategorySettingsDialog is responsible for cleaning up the panel when OK is pressed.

_abc_impl = <_abc._abc_data object>
class gui.settingsDialogs.DocumentNavigationPanel(parent: Window)

Bases: SettingsPanel

@param parent: The parent for this panel; C{None} for no parent.

title = 'Document Navigation'
helpId = 'DocumentNavigation'
makeSettings(settingsSizer: BoxSizer) None

Populate the panel with settings controls. Subclasses must override this method. @param sizer: The sizer to which to add the settings controls.

onSave()

Take action in response to the parent’s dialog OK or apply button being pressed. Sub-classes should override this method. MultiCategorySettingsDialog is responsible for cleaning up the panel when OK is pressed.

_abc_impl = <_abc._abc_data object>
gui.settingsDialogs._synthWarningDialog(newSynth: str)
class gui.settingsDialogs.AudioPanel(parent: Window)

Bases: SettingsPanel

@param parent: The parent for this panel; C{None} for no parent.

title = 'Audio'
helpId = 'AudioSettings'
makeSettings(settingsSizer: BoxSizer) None

Populate the panel with settings controls. Subclasses must override this method. @param sizer: The sizer to which to add the settings controls.

_appendSoundSplitModesList(settingsSizerHelper: BoxSizerHelper) None
onSave()

Take action in response to the parent’s dialog OK or apply button being pressed. Sub-classes should override this method. MultiCategorySettingsDialog is responsible for cleaning up the panel when OK is pressed.

onPanelActivated()

Called after the panel has been activated (i.e. de corresponding category is selected in the list of categories). For example, this might be used for resource intensive tasks. Sub-classes should extend this method.

_onSoundVolChange(event: Event) None

Called when the sound volume follow checkbox is checked or unchecked.

isValid() bool

Evaluate whether the current circumstances of this panel are valid and allow saving all the settings in a L{MultiCategorySettingsDialog}. Sub-classes may extend this method. @returns: C{True} if validation should continue,

C{False} otherwise.

_abc_impl = <_abc._abc_data object>
class gui.settingsDialogs.AddonStorePanel(parent: Window)

Bases: SettingsPanel

@param parent: The parent for this panel; C{None} for no parent.

title = 'Add-on Store'
helpId = 'AddonStoreSettings'
makeSettings(settingsSizer: BoxSizer) None

Populate the panel with settings controls. Subclasses must override this method. @param sizer: The sizer to which to add the settings controls.

onSave()

Take action in response to the parent’s dialog OK or apply button being pressed. Sub-classes should override this method. MultiCategorySettingsDialog is responsible for cleaning up the panel when OK is pressed.

_abc_impl = <_abc._abc_data object>
class gui.settingsDialogs.TouchInteractionPanel(parent: Window)

Bases: SettingsPanel

@param parent: The parent for this panel; C{None} for no parent.

title = 'Touch Interaction'
helpId = 'TouchInteraction'
makeSettings(settingsSizer)

Populate the panel with settings controls. Subclasses must override this method. @param sizer: The sizer to which to add the settings controls.

onSave()

Take action in response to the parent’s dialog OK or apply button being pressed. Sub-classes should override this method. MultiCategorySettingsDialog is responsible for cleaning up the panel when OK is pressed.

_abc_impl = <_abc._abc_data object>
class gui.settingsDialogs.UwpOcrPanel(parent: Window)

Bases: SettingsPanel

@param parent: The parent for this panel; C{None} for no parent.

title = 'Windows OCR'
helpId = 'Win10OcrSettings'
makeSettings(settingsSizer)

Populate the panel with settings controls. Subclasses must override this method. @param sizer: The sizer to which to add the settings controls.

onSave()

Take action in response to the parent’s dialog OK or apply button being pressed. Sub-classes should override this method. MultiCategorySettingsDialog is responsible for cleaning up the panel when OK is pressed.

_abc_impl = <_abc._abc_data object>
class gui.settingsDialogs.AdvancedPanelControls(parent)

Bases: ContextHelpMixin, Panel

Holds the actual controls for the Advanced Settings panel, this allows the state of the controls to be more easily managed.

helpId = 'AdvancedSettings'
selectiveUIAEventRegistrationVals

The possible event registration config values, in the order they appear in the combo box.

consoleVals

The possible console config values, in the order they appear in the combo box.

diffAlgoVals

The possible diffAlgo config values, in the order they appear in the combo box.

isValid() bool
onOpenScratchpadDir(evt)
_getDefaultValue(configPath)
haveConfigDefaultsBeenRestored()
restoreToDefaults()
onSave()
class gui.settingsDialogs.AdvancedPanel(parent: Window)

Bases: SettingsPanel

@param parent: The parent for this panel; C{None} for no parent.

enableControlsCheckBox: CheckBox = None
title = 'Advanced'
helpId = 'AdvancedSettings'
warningHeader = 'Warning!'
warningExplanation = 'The following settings are for advanced users. Changing them may cause NVDA to function incorrectly. Please only change these if you know what you are doing or have been specifically instructed by NVDA developers.'
panelDescription = 'Warning!\nThe following settings are for advanced users. Changing them may cause NVDA to function incorrectly. Please only change these if you know what you are doing or have been specifically instructed by NVDA developers.'
makeSettings(settingsSizer)
onSave()

Take action in response to the parent’s dialog OK or apply button being pressed. Sub-classes should override this method. MultiCategorySettingsDialog is responsible for cleaning up the panel when OK is pressed.

onEnableControlsCheckBox(evt)
isValid() bool

Evaluate whether the current circumstances of this panel are valid and allow saving all the settings in a L{MultiCategorySettingsDialog}. Sub-classes may extend this method. @returns: C{True} if validation should continue,

C{False} otherwise.

_abc_impl = <_abc._abc_data object>
class gui.settingsDialogs.BrailleSettingsPanel(parent: Window)

Bases: SettingsPanel

@param parent: The parent for this panel; C{None} for no parent.

title = 'Braille'
helpId = 'BrailleSettings'
makeSettings(settingsSizer)

Populate the panel with settings controls. Subclasses must override this method. @param sizer: The sizer to which to add the settings controls.

_enterTriggersOnChangeDisplay(evt)
onChangeDisplay(evt)
updateCurrentDisplay()
onPanelActivated()

Called after the panel has been activated (i.e. de corresponding category is selected in the list of categories). For example, this might be used for resource intensive tasks. Sub-classes should extend this method.

onPanelDeactivated()

Called after the panel has been deactivated (i.e. another category has been selected in the list of categories). Sub-classes should extendthis method.

onDiscard()

Take action in response to the parent’s dialog Cancel button being pressed. Sub-classes may override this method. MultiCategorySettingsDialog is responsible for cleaning up the panel when Cancel is pressed.

onSave()

Take action in response to the parent’s dialog OK or apply button being pressed. Sub-classes should override this method. MultiCategorySettingsDialog is responsible for cleaning up the panel when OK is pressed.

_abc_impl = <_abc._abc_data object>
class gui.settingsDialogs.BrailleDisplaySelectionDialog(*args, **kwargs)

Bases: SettingsDialog

@param parent: The parent for this dialog; C{None} for no parent. @param resizeable: True if the settings dialog should be resizable by the user, only set this if

you have tested that the components resize correctly.

@param hasApplyButton: C{True} to add an apply button to the dialog; defaults to C{False} for backwards compatibility.

Deprecated, use buttons instead.

@param settingsSizerOrientation: Either wx.VERTICAL or wx.HORIZONTAL. This controls the orientation of the

sizer that is passed into L{makeSettings}. The default is wx.VERTICAL.

@param multiInstanceAllowed: Whether multiple instances of SettingsDialog may exist.

Note that still only one instance of a particular SettingsDialog subclass may exist at one time.

@param buttons: Buttons to add to the settings dialog.

Should be a subset of {wx.OK, wx.CANCEL, wx.APPLY, wx.CLOSE}.

title = 'Select Braille Display'
helpId = 'SelectBrailleDisplay'
displayNames = []
possiblePorts = []
makeSettings(settingsSizer)

Populate the dialog with settings controls. Subclasses must override this method. @param sizer: The sizer to which to add the settings controls. @type sizer: wx.Sizer

postInit()

Called after the dialog has been created. For example, this might be used to set focus to the desired control. Sub-classes may override this method.

static getCurrentAutoDisplayDescription()
updateBrailleDisplayLists()
updateStateDependentControls()
onDisplayNameChanged(evt)
onOk(evt)

Take action in response to the OK button being pressed. Sub-classes may extend this method. This base method should always be called to clean up the dialog.

_abc_impl = <_abc._abc_data object>
class gui.settingsDialogs.BrailleSettingsSubPanel(*args, **kwargs)

Bases: AutoSettingsMixin, SettingsPanel

Mixin init, forwards args to other base class. The other base class is likely L{gui.SettingsPanel}. @param args: Positional args to passed to other base class. @param kwargs: Keyword args to passed to other base class.

helpId = 'BrailleSettings'
property driver
getSettings() AutoSettings
makeSettings(settingsSizer)

Populate the panel with settings controls. @note: Normally classes also inherit from settingsDialogs.SettingsPanel. @param sizer: The sizer to which to add the settings controls.

onSave()

Take action in response to the parent’s dialog OK or apply button being pressed. Sub-classes should override this method. MultiCategorySettingsDialog is responsible for cleaning up the panel when OK is pressed.

onShowCursorChange(evt)
onBlinkCursorChange(evt)
onShowMessagesChange(evt)
onTetherToChange(evt: CommandEvent) None

Shows or hides “Move system caret when routing review cursor” braille setting.

onReadByParagraphChange(evt: CommandEvent)
_onModeChange(evt: CommandEvent)
_abc_impl = <_abc._abc_data object>
settingsSizer: BoxSizer
gui.settingsDialogs.showStartErrorForProviders(parent: Window, providers: List[ProviderInfo]) None
gui.settingsDialogs.showTerminationErrorForProviders(parent: Window, providers: List[ProviderInfo]) None
class gui.settingsDialogs.VisionProviderStateControl(parent: Window, providerInfo: ProviderInfo)

Bases: VisionProviderStateControl

Gives settings panels for vision enhancement providers a way to control a single vision enhancement provider, handling any error conditions in a UX friendly way.

getProviderInfo() ProviderInfo

@return: The provider info @rtype: providerInfo.ProviderInfo

getProviderInstance() VisionEnhancementProvider | None

Gets an instance for the provider if it already exists @rtype: Optional[VisionEnhancementProvider]

startProvider(shouldPromptOnError: bool = True) bool

Initializes the provider, prompting user with the error if necessary. @param shouldPromptOnError: True if the user should be presented with any errors that may occur. @return: True on success

terminateProvider(shouldPromptOnError: bool = True) bool

Terminate the provider, prompting user with the error if necessary. @param shouldPromptOnError: True if the user should be presented with any errors that may occur. @return: True on success

_doStartProvider() bool

Attempt to start the provider, catching any errors. @return True on successful termination.

_doTerminate() bool

Attempt to terminate the provider, catching any errors. @return True on successful termination.

class gui.settingsDialogs.VisionSettingsPanel(parent: Window)

Bases: SettingsPanel

@param parent: The parent for this panel; C{None} for no parent.

settingsSizerHelper: BoxSizerHelper
providerPanelInstances: List[SettingsPanel]
initialProviders: List[ProviderInfo]
title = 'Vision'
helpId = 'VisionSettings'
panelDescription = 'Configure visual aids.'
_createProviderSettingsPanel(providerInfo: ProviderInfo) SettingsPanel | None
makeSettings(settingsSizer: BoxSizer)

Populate the panel with settings controls. Subclasses must override this method. @param sizer: The sizer to which to add the settings controls.

safeInitProviders(providers: List[ProviderInfo]) None

Initializes one or more providers in a way that is gui friendly, showing an error if appropriate.

safeTerminateProviders(providers: List[ProviderInfo], verbose: bool = False) None

Terminates one or more providers in a way that is gui friendly, @verbose: Whether to show a termination error. @returns: Whether termination succeeded for all providers.

refreshPanel()
onPanelActivated()

Called after the panel has been activated (i.e. de corresponding category is selected in the list of categories). For example, this might be used for resource intensive tasks. Sub-classes should extend this method.

onDiscard()

Take action in response to the parent’s dialog Cancel button being pressed. Sub-classes may override this method. MultiCategorySettingsDialog is responsible for cleaning up the panel when Cancel is pressed.

onSave()

Take action in response to the parent’s dialog OK or apply button being pressed. Sub-classes should override this method. MultiCategorySettingsDialog is responsible for cleaning up the panel when OK is pressed.

_abc_impl = <_abc._abc_data object>
class gui.settingsDialogs.VisionProviderSubPanel_Settings(parent: Window, *, settingsCallable: Callable[[], VisionEnhancementProviderSettings])

Bases: AutoSettingsMixin, SettingsPanel

@param settingsCallable: A callable that returns an instance to a VisionEnhancementProviderSettings.

This will usually be a weakref, but could be any callable taking no arguments.

helpId = 'VisionSettings'
_settingsCallable: Callable[[], VisionEnhancementProviderSettings]
getSettings() AutoSettings
makeSettings(settingsSizer)

Populate the panel with settings controls. @note: Normally classes also inherit from settingsDialogs.SettingsPanel. @param sizer: The sizer to which to add the settings controls.

_abc_impl = <_abc._abc_data object>
class gui.settingsDialogs.VisionProviderSubPanel_Wrapper(parent: Window, providerControl: VisionProviderStateControl)

Bases: SettingsPanel

@param parent: The parent for this panel; C{None} for no parent.

_checkBox: CheckBox
makeSettings(settingsSizer)

Populate the panel with settings controls. Subclasses must override this method. @param sizer: The sizer to which to add the settings controls.

_updateOptionsVisibility()
_createProviderSettings()
_nonEnableableGUI(evt)
_enableToggle(evt)
onDiscard()

Take action in response to the parent’s dialog Cancel button being pressed. Sub-classes may override this method. MultiCategorySettingsDialog is responsible for cleaning up the panel when Cancel is pressed.

onSave()

Take action in response to the parent’s dialog OK or apply button being pressed. Sub-classes should override this method. MultiCategorySettingsDialog is responsible for cleaning up the panel when OK is pressed.

_abc_impl = <_abc._abc_data object>
class gui.settingsDialogs.NVDASettingsDialog(*args, **kwargs)

Bases: MultiCategorySettingsDialog

@param parent: The parent for this dialog; C{None} for no parent. @type parent: wx.Window @param initialCategory: The initial category to select when opening this dialog @type parent: SettingsPanel

title = 'NVDA Settings'
categoryClasses: List[Type[SettingsPanel]] = [<class 'gui.settingsDialogs.GeneralSettingsPanel'>, <class 'gui.settingsDialogs.SpeechSettingsPanel'>, <class 'gui.settingsDialogs.BrailleSettingsPanel'>, <class 'gui.settingsDialogs.AudioPanel'>, <class 'gui.settingsDialogs.VisionSettingsPanel'>, <class 'gui.settingsDialogs.KeyboardSettingsPanel'>, <class 'gui.settingsDialogs.MouseSettingsPanel'>, <class 'gui.settingsDialogs.ReviewCursorPanel'>, <class 'gui.settingsDialogs.InputCompositionPanel'>, <class 'gui.settingsDialogs.ObjectPresentationPanel'>, <class 'gui.settingsDialogs.BrowseModePanel'>, <class 'gui.settingsDialogs.DocumentFormattingPanel'>, <class 'gui.settingsDialogs.DocumentNavigationPanel'>, <class 'gui.settingsDialogs.AddonStorePanel'>, <class 'gui.settingsDialogs.AdvancedPanel'>]
makeSettings(settingsSizer)

Populate the dialog with settings controls. Subclasses must override this method. @param sizer: The sizer to which to add the settings controls. @type sizer: wx.Sizer

_doOnCategoryChange()
_getDialogTitle()
onCategoryChange(evt)
Destroy(self) bool
_abc_impl = <_abc._abc_data object>
catIdToInstanceMap: Dict[int, SettingsPanel]
class gui.settingsDialogs.AddSymbolDialog(parent)

Bases: ContextHelpMixin, Dialog

helpId = 'SymbolPronunciation'
class gui.settingsDialogs.SpeechSymbolsDialog(*args, **kwargs)

Bases: SettingsDialog

@param parent: The parent for this dialog; C{None} for no parent. @param resizeable: True if the settings dialog should be resizable by the user, only set this if

you have tested that the components resize correctly.

@param hasApplyButton: C{True} to add an apply button to the dialog; defaults to C{False} for backwards compatibility.

Deprecated, use buttons instead.

@param settingsSizerOrientation: Either wx.VERTICAL or wx.HORIZONTAL. This controls the orientation of the

sizer that is passed into L{makeSettings}. The default is wx.VERTICAL.

@param multiInstanceAllowed: Whether multiple instances of SettingsDialog may exist.

Note that still only one instance of a particular SettingsDialog subclass may exist at one time.

@param buttons: Buttons to add to the settings dialog.

Should be a subset of {wx.OK, wx.CANCEL, wx.APPLY, wx.CLOSE}.

helpId = 'SymbolPronunciation'
makeSettings(settingsSizer)

Populate the dialog with settings controls. Subclasses must override this method. @param sizer: The sizer to which to add the settings controls. @type sizer: wx.Sizer

postInit()

Called after the dialog has been created. For example, this might be used to set focus to the desired control. Sub-classes may override this method.

filter(filterText='')
getItemTextForList(item, column)
onSymbolEdited()
onListItemFocused(evt)
OnAddClick(evt)
OnRemoveClick(evt)
onOk(evt)

Take action in response to the OK button being pressed. Sub-classes may extend this method. This base method should always be called to clean up the dialog.

_abc_impl = <_abc._abc_data object>
_refreshVisibleItems()
onFilterEditTextChange(evt)

gui.speechDict module

class gui.speechDict.DictionaryEntryDialog(parent, title='Edit Dictionary Entry')

Bases: ContextHelpMixin, Dialog

helpId = 'SpeechDictionaries'
TYPE_LABELS = {0: '&Anywhere', 1: 'Regular &expression', 2: 'Whole &word'}
TYPE_LABELS_ORDERING = (0, 2, 1)
getType()
onOk(evt)
setType(type)
class gui.speechDict.DictionaryDialog(*args, **kwargs)

Bases: SettingsDialog

A dictionary dialog. A dictionary dialog is a setting dialog containing a list of dictionary entries and buttons to manage them.

To use this dialog, override L{__init__} calling super().__init__.

@param parent: The parent for this dialog; C{None} for no parent. @param resizeable: True if the settings dialog should be resizable by the user, only set this if

you have tested that the components resize correctly.

@param hasApplyButton: C{True} to add an apply button to the dialog; defaults to C{False} for backwards compatibility.

Deprecated, use buttons instead.

@param settingsSizerOrientation: Either wx.VERTICAL or wx.HORIZONTAL. This controls the orientation of the

sizer that is passed into L{makeSettings}. The default is wx.VERTICAL.

@param multiInstanceAllowed: Whether multiple instances of SettingsDialog may exist.

Note that still only one instance of a particular SettingsDialog subclass may exist at one time.

@param buttons: Buttons to add to the settings dialog.

Should be a subset of {wx.OK, wx.CANCEL, wx.APPLY, wx.CLOSE}.

TYPE_LABELS = {0: 'Anywhere', 1: 'Regular expression', 2: 'Whole word'}
helpId = 'SpeechDictionaries'
makeSettings(settingsSizer)

Populate the dialog with settings controls. Subclasses must override this method. @param sizer: The sizer to which to add the settings controls. @type sizer: wx.Sizer

postInit()

Called after the dialog has been created. For example, this might be used to set focus to the desired control. Sub-classes may override this method.

onCancel(evt)

Take action in response to the Cancel button being pressed. Sub-classes may extend this method. This base method should always be called to clean up the dialog.

onOk(evt)

Take action in response to the OK button being pressed. Sub-classes may extend this method. This base method should always be called to clean up the dialog.

onAddClick(evt)
onEditClick(evt)
onRemoveClick(evt)
onRemoveAll(evt)
_abc_impl = <_abc._abc_data object>
class gui.speechDict.DefaultDictionaryDialog(*args, **kwargs)

Bases: DictionaryDialog

@param parent: The parent for this dialog; C{None} for no parent. @param resizeable: True if the settings dialog should be resizable by the user, only set this if

you have tested that the components resize correctly.

@param hasApplyButton: C{True} to add an apply button to the dialog; defaults to C{False} for backwards compatibility.

Deprecated, use buttons instead.

@param settingsSizerOrientation: Either wx.VERTICAL or wx.HORIZONTAL. This controls the orientation of the

sizer that is passed into L{makeSettings}. The default is wx.VERTICAL.

@param multiInstanceAllowed: Whether multiple instances of SettingsDialog may exist.

Note that still only one instance of a particular SettingsDialog subclass may exist at one time.

@param buttons: Buttons to add to the settings dialog.

Should be a subset of {wx.OK, wx.CANCEL, wx.APPLY, wx.CLOSE}.

_abc_impl = <_abc._abc_data object>
class gui.speechDict.VoiceDictionaryDialog(*args, **kwargs)

Bases: DictionaryDialog

@param parent: The parent for this dialog; C{None} for no parent. @param resizeable: True if the settings dialog should be resizable by the user, only set this if

you have tested that the components resize correctly.

@param hasApplyButton: C{True} to add an apply button to the dialog; defaults to C{False} for backwards compatibility.

Deprecated, use buttons instead.

@param settingsSizerOrientation: Either wx.VERTICAL or wx.HORIZONTAL. This controls the orientation of the

sizer that is passed into L{makeSettings}. The default is wx.VERTICAL.

@param multiInstanceAllowed: Whether multiple instances of SettingsDialog may exist.

Note that still only one instance of a particular SettingsDialog subclass may exist at one time.

@param buttons: Buttons to add to the settings dialog.

Should be a subset of {wx.OK, wx.CANCEL, wx.APPLY, wx.CLOSE}.

_abc_impl = <_abc._abc_data object>
class gui.speechDict.TemporaryDictionaryDialog(*args, **kwargs)

Bases: DictionaryDialog

@param parent: The parent for this dialog; C{None} for no parent. @param resizeable: True if the settings dialog should be resizable by the user, only set this if

you have tested that the components resize correctly.

@param hasApplyButton: C{True} to add an apply button to the dialog; defaults to C{False} for backwards compatibility.

Deprecated, use buttons instead.

@param settingsSizerOrientation: Either wx.VERTICAL or wx.HORIZONTAL. This controls the orientation of the

sizer that is passed into L{makeSettings}. The default is wx.VERTICAL.

@param multiInstanceAllowed: Whether multiple instances of SettingsDialog may exist.

Note that still only one instance of a particular SettingsDialog subclass may exist at one time.

@param buttons: Buttons to add to the settings dialog.

Should be a subset of {wx.OK, wx.CANCEL, wx.APPLY, wx.CLOSE}.

_abc_impl = <_abc._abc_data object>

gui.startupDialogs module

class gui.startupDialogs.WelcomeDialog(parent)

Bases: ContextHelpMixin, Dialog

The NVDA welcome dialog. This provides essential information for new users, such as a description of the NVDA key and instructions on how to activate the NVDA menu. It also provides quick access to some important configuration options. This dialog is displayed the first time NVDA is started with a new configuration.

helpId = 'WelcomeDialog'
WELCOME_MESSAGE_DETAIL = 'Most commands for controlling NVDA require you to hold down the NVDA key while pressing other keys.\nBy default, the Insert and numpad Insert keys may both be used as the NVDA key.\nYou can also configure NVDA to use the CapsLock as the NVDA key.\nPress NVDA+n at any time to activate the NVDA menu.\nFrom this menu, you can configure NVDA, get help, and access other NVDA functions.'
_instances: Set[WelcomeDialog] = set()
onOk(evt)
classmethod run()

Prepare and display an instance of this dialog. This does not require the dialog to be instantiated.

classmethod closeInstances()
class gui.startupDialogs.LauncherDialog(parent)

Bases: DpiScalingHelperMixinWithoutInit, ContextHelpMixin, Dialog

The dialog that is displayed when NVDA is started from the launcher. This displays the license and allows the user to install or create a portable copy of NVDA.

helpId = 'InstallingNVDA'
_createLicenseAgreementGroup() StaticBoxSizer
onLicenseAgree(evt)
onAction(evt, func)
onContinueRunning(evt)
onExit(evt: CommandEvent)
classmethod run()

Prepare and display an instance of this dialog. This does not require the dialog to be instantiated.

class gui.startupDialogs.AskAllowUsageStatsDialog(parent)

Bases: ContextHelpMixin, Dialog

A dialog asking if the user wishes to allow NVDA usage stats to be collected by NV Access.

helpId = 'UsageStatsDialog'
onYesButton(evt)
onNoButton(evt)
onLaterButton(evt)