This add-on gathers various features for NVDA debugging and testing.
The NVDA+shift+Q command opens a dialog to specify some extra options before restarting NVDA.
The options that can be specified correspond to the command line options that can be used with nvda.exe, e.g. -c for config path, --disable-addons to disable add-ons, etc.
Pressing NVDA+shift+alt+E allows to report the last error logged without needing to open the log. A second press clears the memorized last error.
The "Play a sound for logged errors" setting has been introduced in NVDA 2021.3 and allows to specify if NVDA will play an error sound in case an error is logged.
This add-on provides an additional command (NVDA+control+alt+E) to toggle this setting. You can choose:
For NVDA prior to 2021.3, this add-on provides the backport of this feature and the possibility to control it with the keyboard command. The checkbox in the Advanced settings panel is not backported however.
This feature allows to report some properties of the current navigator object without opening the log viewer.
To list the properties of an object, move the navigator object to it and use the following commands:
The list of the supported properties is the following: name, role, state, value, windowClassName, windowControlID, windowHandle, location, Python class, Python class mro.
When using object navigation commands, you can also choose to have the currently selected property reported instead of NVDA usual object reporting. A toggle command allows to switch between this custom reporting of objects and NVDA usual reporting.
For exemple, you may select "windowClassName" property and enable custom object reporting. Then when moving the navigator object to next or previous object, you will hear the object's windowClassName instead of usual reporting.
All the commands of the Object property explorer are unassigned by default; you will have to assign them a shortcut in the Input gesture dialog to use them.
When the Extended script description mode is active, the input help mode (NVDA+1) is modified as follows. If a script has no description, the script's name and class are reported. If a script has a description, its description is reported as usual. The gesture to activate or deactivate this feature is NVDA+control+alt+D.
Executing a gesture bound to a script without description in input help mode also create an entry for this script in the gesture management dialog. This entry is located in a dedicated category called "Scripts without description (modify at your own risk!)". This allow to easily add, delete or change the native NVDA gestures for these script. Be aware however that it is often intended that such script do not have any description to prevent the user to modify the associated gesture. Indeed, the gesture may be defined to match an application shortcut key. For example the script script_toggleItalic on NVDAObjects.window.winword.WordDocument is bound to control+I and this should not be modified since the gesture is passed to the application to actually execute the shortcut key.
Control+shift+I also toggle italic in Word, even if it is not natively reported by NVDA. To have the control+shift+I result reported by NVDA as control+I, you should perform the following steps:
Known bug: A script added for a specific class is visible even if gesture manager is opened in another context.
While testing or working, you may want to mark a specific moment in the log, so that you can turn to it easily later when reading the log.
To add a marker message in the log, press NVDA+control+K.
A message as follows will be logged at INFO level:
-- NDTT marker 0 --
You can add as many markers as you want in the log.
The marker's number will be incremented each time you place a marker in the log; it will only be reset when NVDA is restarted.
A log reader mode provides commands to ease log reading and analyzing. In the log viewer window the log reader is enabled by default, thus log reading commands are available immediately. In another text reading area such as an editor (e.g. Notepad++) or a webpage (e.g. GitHub issue), you need to press NVDA+control+alt+L to enable log reader mode and use its commands. When you are done with log reading and analyzing tasks, you can disable again NVDA+control+alt+L to disable the log reader mode.
The commands available in log reader mode are described hereafter.
Single letter command similar to browse mode quick navigation keys allow to move to various type of log messages:
ERROR and CRITICAL)WARNING)INFO)DEBUGWARNING)IO)DEBUG)Pressing the single letter moves to the next occurrence of this message. Combining the letter with the shift key moves to the previous occurrence of this message.
Sometimes, you may have to look at a log taken on a system in a foreignh language that you do not understand. E.g. the log was taken on a Chinese system / NVDA, whereas you only understand French. If you have Instant Translate add-on installed, you may use it in conjonction with quick log navigation commands to have speech messages translated.
If you want to disable speech translation, press T again.
In the log some line may refer to the source code:
File "virtualBuffers\__init__.pyc", line 226, in _getStoryLength INFO - config.ConfigManager._loadConfig (22:45:26.145) - MainThread (16580): You may want to open the file containing this code to understand the context of the traceback or the logged message. Just press C to open this file.
For this feature to work, you need to have configured your favorite editor's command in the add-on's settings. If you are not running NVDA from source, the location of NVDA source code should also have been configured.
NVDA already provides a backup of the log of the previous session of NVDA; the file is called nvda-old.log.
Sometimes however you may want to access older logs, e.g. because you have had to restart NVDA again before looking at nvda-old.log.
This add-on allows you to configure if you want to backup old logs and how many of them; this is done in the add-on's settings.
A log manager dialog allows to view the backed up logs. It can be opened going to NVDA menu -> Tools -> Logs manager In this dialog, you can see the list of all the backup logs, open or delete them. To be able to open a log, you should first have configured the Command to open a file in your favorite editor.
openCodeFile functionIn the console, you can call the following function to view the source code that defines the variable myVar:
openCodeFile(myVar)
For this feature to work, you need to have configured your favorite editor's command in the add-on's settings. If you are not running NVDA from source, the location of NVDA source code should also have been configured.
The openCodeFile functions can be called on objects defined in NVDA's code or on objects defined by add-ons.
It cannot be called on objects whose source code is not available such as python builtins.
If you have not yet imported the object in the console, you can also pass its name as parameter to the openCodeFile function.
Below are examples of call in NVDA's code:
speech.speech.speak:openCodeFile(speech.speech.speak)openCodeFile("speech.speech.speak") TextInfo:openCodeFile(textInfos.TextInfo) copyToClipboard of the class TextInfo:openCodeFile(textInfos.TextInfo.copyToClipboard) openCodeFile(focus) api.py defining the module api:openCodeFile(api) You can define a custom script which will be executed in the Python console's namespace when it is first opened, or if the add-on is reloaded (NVDA+F3) after the console has already been opened.
For example, the script allows you to execute new imports and define aliases that you will be able to use directly in the console, as shown below:
# Various import that I want in the console.
import globalVars as gv
import core
import ui
# Aliases
ocf = openCodeFile
The Python console script should be placed in the following location: pathToNVDAConfig\ndtt\consoleStartup.py
For example: C:\Users\myUserName\AppData\Roaming\nvda\ndtt\consoleStartup.py
Sometimes, you may want to see which part of the code is responsible for speaking something. For this, you can enable the stack trace logging of the speech function pressing NVDA+control+alt+S. Each time NVDA speaks, a corresponding stack trace will be logged in the log.
Note: You may modify the script's file directly to patch another function. See all instructions in the file for details on usage.
Some features of the add-on may require a specific configuration. A settings panel allows to enable them or to control how they work. To view and modify these settings, go to NVDA menu -> Preferences and select the category NVDA Dev & Test Toolbox. This settings dialog can also be accessed directly from the Logs Manager dialog.
These settings are global and can only be configured when the default profile is active.
Some features allow to see content in your favorite editor. This includes the commands to view the source file from a log or from an object in the console as well as the log manager's Open button.
To use them, you first need to configure the command that will be called to open the file in your favorite editor.
The command should be of the form:
"C:\path\to\my\editor\editor.exe" "{path}":{line}
You should of course modify this line according to the real name and location of your editor and the syntax used by it to open files.
{path} will be replaced by the full path of the file to open and {line} by the line number where you want the cursor to be set.
For Notepad++ for example the command to type in the console would be:
"C:\Program Files\Notepad++\notepad++.exe" "{path}" -n{line}
When using a command to view the source file from a log or from an object in the console, the file may belong to NVDA itself.
If you are not running NVDA from source, your NVDA only contains compiled files.
Thus you may specify here an alternate location where the corresponding source file will be found, e.g. the place where you have cloned NVDA source files, so that a source file can be opened anyway.
The path should be such as:
C:\pathExample\GIT\nvda\source
Of course, replace the path of NVDA source with the correct one.
Be sure however that the version of your source file (e.g. GIT commit) is the same as the one of the running instance of NVDA.
The combobox Backup of old logs allows to enable or disable the feature. If it is enabled, you can also specify below in "Limit the number of backups" the maximum number of backups you want to keep. These settings only take effect at next NVDA startup when the backup takes place.
openCodeFile function can now receive as parameter the object or a string containing its name.openCodeFile Python console's function and the command to open the source file corresponding to a line in the log.openCodeFile function is available to view the source code of an object.