NVDA 0.6 User Guide

Last updated July 20th 2008

Table of Contents

1. Introduction

1.1. General Features

Providing feedback by synthetic speech, NVDA allows blind and vision impaired people to access and interact with the Windows operating system and many third party applications.

Major highlights include:

1.2. Internationalization

It is important that people anywhere in the world, no matter what language they speak, get the same access to technologies. NVDA currently has been translated into over 20 languages including: Brazilian Portuguese, Croatian, Czech, Finnish, French, Galician, German, Hungarian, Italian, Japanese, Portuguese, Russian, Slovak, Spanish, Traditional Chinese, Afrikaans, Polish, Thai, Ukrainian and Vietnamese.

1.3. Speech Synthesizer Support

Apart from providing its messages and interface in several languages, NVDA can also enable the user to read content in any language, as long as they have a speech synthesizer that can speak that particular language.

NVDA is bundled with eSpeak, a free, open-source, multi-lingual speech synthesizer. Additionally, NVDA can use both SAPI4 and SAPI5 speech engines to provide speech output, as well as the Audiologic speech synthesizer.

1.4. Innovation and Experimentation

NVDA is not restricted by a need to follow market trends and demands. Commercial screen readers implement really good features, but sometimes this is biased by what the market wants, rather than what will be really useful for the user. NVDA may not be always as stable as other screen readers, but it can certainly act as an experimental testing tool. It can easily and quickly test new ideas and features perhaps not seen in other screen readers for the Windows Operating System. An example of this is NVDA's ability to use beeps to communicate to the user that a progress bar is moving. The higher the beep, the closer the progress bar is to the end. People have added this feature in to other screen readers through custom scripts and the like, but it has never been officially adopted completely in to the core of any other Windows screen reader.

1.5. Design and Implementation

NVDA is written in the Python programming language, and is built with a modular design, and much of its code can easily be extended and added to in order to support new programs and/or controls in Windows. App Modules can be written to add overall support for a specific application, virtual buffers can be written to allow NVDA to display complex documents or other data, and NVDA Objects can be written to add support for specific controls or Windows. NVDA always tries to make controls and elements of a program or Operating System as accessible as possible, so that the user can actively seek any information they require. NVDA is not so concerned with special features such as filtering and announcing particular information it thinks the user may want to know.

To communicate with the Operating System and programs, NVDA uses a mix of Operating System functions, Microsoft Active Accessibility (MSAA), IAccessible2, Java Access Bridge and specific programming interfaces provided by certain applications. NVDA does not use any special Video Intercept drivers or display hooks, and will always try to gain as much information from Accessibility specific interfaces as possible, before resorting to other means.

1.6. Licence and Copyright

NVDA is copyright ɠ2006-2008 NVDA contributors.

NVDA is covered by the GNU General Public License (Version 2). You are free to share or change this software in any way you like as long as you distribute the licence along with the software, and make all source code available to anyone who wants it. This applies to both original and modified copies of the software, plus any software that uses code taken from this software. For further details, you can view the full licence.

2. System Requirements

3. Getting NVDA

If you havenӴ yet got a copy of NVDA, you can download it from the NVDA website at: http://www.nvda-project.org/

Go to the download section and you will find a link to download the latest version of NVDA.

There are currently two ways NVDA is packaged. One is an Installer which will talk you through installing NVDA so that you can then run it at any time from the Start Menu. The other is a zip file that contains a fully portable version of NVDA, which you can run from anywhere, including a USB thumb drive or CD.

4. Installing NVDA

4.1. The NVDA Installer

If you already have the NVDA installer, simply press enter or double click on the file and the installer will start.

As the installer loads, you will hear the NVDA installation music. Once loaded, a temporary copy of NVDA will allow you to follow the prompts of the installer and install NVDA. Note that if you were running another copy of NVDA at the time you started the installer, a message will appear telling you that your previous copy of NVDA will be closed. When you press enter on this message, the installer will close your previous copy and start its own one. This is necessary so that the installer can properly update any changed files.

Once you have successfully completed the installation, the installer will finally start the newly installed copy of NVDA for you.

4.2. The Portable Zip File

If you have the zip file version of NVDA, then all you have to do is unzip this file to any place you like on your hard drive or other portable media.

5. Getting started with NVDA

5.1. Launching NVDA

If you have installed NVDA with the installer, then starting NVDA is as simple as either pressing control+alt+n, or choosing NVDA from the NVDA menu under Programs on the Start Menu.

To start the portable zip file version, go to the directory you unzipped NVDA to, and press enter or double click on nvda.exe.

As NVDA starts, you will first hear an ascending set of tones (telling you that NVDA is loading). You should then hear it say "NVDA Started". Depending on how fast your computer is, or if you are running NVDA off a USB key or other slower medium, it may take a little while to start. If it is taking an extra long time, NVDA should say "Loading subsystems. Please wait...ԍ

If you don't hear any of this, or you hear the Windows error sound, or a descending set of tones, then this means that NVDA has an error, and you will need to possibly report a bug to the developers. Please check out the NVDA website for how to do this.

When NVDA starts for the first time, you will be greeted by a dialog box which provides you with some basic information about the NVDA modifier key and the NVDA menu. (Please see further sections about these topics). The dialog box also contains two checkboxes. The first lets you control if NVDA should use the capslock as an NVDA modifier key, and the second lets you control if this Welcome dialog should appear each time NVDA starts.

5.2. About NVDA keyboard commands

most NVDA-specific keyboard commands usually consist of pressing the NVDA modifier key, in conjunction with one or more other keys. An exception to this are the text review commands which just use the numpad keys by themselves.

By default both numpad insert and extended insert can be used as the NVDA modifier key. However, you can also configure NVDA so that the capslock key also becomes an NVDA modifier key. When configured this way, pressing or holding down capslock acts as an NVDA modifier key, but pressing it twice in quick succession causes it to act as the normal capslock key.

Many key commands are mentioned through out the rest of this user guide, but an easy way to explore all the different key commands is to turn on keyboard help.

To turn on keyboard help, press NVDA+1. To turn it off again, press NVDA+1 again. While in keyboard help, pressing any key will announce what it does (if in deed it does do something). The keys will not actually perform their function while in keyboard help mode, so you can press what ever keys you like.

6. The NVDA menu

The NVDA menu allows you to control NVDA's settings, access help, save/revert your configuration, and exit NVDA.

6.1. Accessing the NVDA menu

To get to the NVDA menu from anywhere in Windows while NVDA is running, press NVDA+n. When the menu comes up, You can use the arrow keys to navigate the menu, and the enter key to activate an item. The Preferences menu allows you to configure NVDA how you like, the tools menu contains a one or two useful tools such as the NVDA log viewer and the NVDA Python console for developers, the help menu allows you to access the user guide, a quick key reference, and much more. The NVDA menu also contains items that allow you to save or revert your current configuration, and even to exit NVDA alltogether.

The NVDA menu can also be accessed from the NVDA icon in the Windows System Tray. Either right mouse click on the icon, or move to the System tray by pressing windowsKey+b and arrowing to the NVDA icon and pressing the applications key.

6.2. Saving and Reloading the configuration

NVDA stores its settings in a file called nvda.ini in its directory. You will probably never have to touch this file, but for advanced users, this file does allow you to change some extra settings which don't yet have dialog boxes to do so.

NVDA does not automatically save your settings, so if you exit NVDA, and then restart it, the settings will go back to the original values. To save the settings, you can either choose the Save configuration item in the NVDA menu, or press NVDA+Control+c from anywhere.

If NVDA is on a read-only file system, such as a CD, it will not be able to save your settings, and it will tell you so.

If you ever make a mistake with your settings and need to revert back to the saved settings, you can either choose the "revert to saved configuration" item in the NVDA menu, or you can press NVDA+Control+r from anywhere.

6.3. The Preferences Menu

In the NVDA menu , there is a Preferences menu which contains many menu items that open dialog boxes for you to control NVDA's various settings.

You can control General settings, synthesizer selection, voice settings, keyboard settings, mouse settings, object presentation, virtual buffer settings, and document formatting settings.

7. Navigating with NVDA

7.1. Navigating with the Focus

The Most common way of navigating around Windows with NVDA, is to just move around with normal keyboard commands, such as tab and shift tab to move forward and back between controls, pressing alt to get to the menu bar and then using the arrows to navigate menus, using alt-tab to move between running applications. As you do this, NVDA will announce what has focus.

When NVDA announces an object (e.g. when it receives focus), it will usually say the object's name, type, state, value, description, keyboard shortcut, and positional information. This is quite similar to other screen readers; however the types of objects may be a little different.

There are some key commands useful when moving with focus:

7.2. Object Navigation

If you wish to look around the Operating System a bit, but with out moving the focus, you can use NVDA's object navigation. This allows you to move from object to object in a tree like structure.

The tree structure of objects starts at the desktop window, the root of the tree. The first branches of the tree are the currently running applications, and of course these applications have their own branches (objects), representing various parts of the application.

The tree structure can get quite large, but it does allow you to navigate in a logical order, so that you can quickly find the information you need.

This structure has nothing to do with how the objects are laid out on the screen, but how they are related logically. This may take a little bit of time to get used to, but once you grasp this, you should be able to move around quite easily.

NVDA currently can not navigate the objects in a screen-based layout due to not having a video intercept driver or display hooks. NVDA chooses not to interact with the screen, more so because over all it should allow a much clearer, and more logical perception of an application and the operating system, rather than trying to picture a flat screen layout.

Not all applications have a perfect tree structure, but this is up to the developer of that particular application. Most seem to be ok; certainly most Dialog boxes and highly structured applications seem to have gotten it right.

To navigate by object, use the following keys:

note: numpad keys require numlock key to be turned off to work properly

When you move with the focus, the current navigator object changes along with it. However, if you wish to lock the object navigation to one specific object, so it doesn't change with the focus, you can turn off focus Moves Navigator Object with NVDA+7.

7.3. Reviewing the Text in the Current Object

Sometimes you might want to know how something is spelt, or perhaps you need to read something by words. You can review the text inside the current object with the numpad keys:

note: numpad keys require numlock key to be turned off to work properly

For most objects, the text inside is made up of name, value and description. However for objects that actually have real text, or editable content, then the text is the actual text in the object.

For example: a list item in a list will have text which contains its name, value and description. But an edit field, or a dos console window, will have the actual text that is in the field or window.

When an object contains an edit cursor (system caret), and it moves, the review cursor is also updated to that position. If you want the review cursor to stay where it is, and not move with the caret, you can turn off caret Moves Review Cursor by pressing NVDA+6.

7.4. Navigating with the System Caret

When the focus is on an object that has an edit cursor (system caret), you can arrow around and edit like you normally would. NVDA will announce as you move by character, word, line, and will also announce selecting and unselecting text.

When you move with the system caret, the position of the review cursor will also be updated to match the system caret.

You can also read the entire text (say all) with NVDA+down Arrow. Note though that this is different to numpad Plus which only moves the review cursor, this moves the system caret as it goes.

7.5. Navigating with the Mouse

When you move the Mouse, NVDA by default reports the text that is directly under the mouse pointer, as it moves over it. Where supported, NVDA will read a paragraph's worth of text, though some controls may only read by line.

NVDA can also be configured to also announce the type of control or object the mouse is currently over as it moves (e.g. list, button etc), which may be useful for totally blind users as sometimes the text isn't enough.

NVDA provides a way for users to understand where the mouse is in regards to the dimentions of the screen, by playing the current mouse coordinates as audio beeps. The higher the mouse is up the screen, the higher the pitch of the beeps. The more left or right the mouse is on the screen, the more left or right the sound will seem to come from (assuming the user has stereo speakers).

These extra mouse features are not turned on by default in NVDA, but if you wish to take advantage of them, you can configure them from the Mouse settings dialog, found in the Preferences menu on the NVDA menu.

8. Virtual Buffers

Complex read-only documents, such as web pages, are represented in NVDA with in a Virtual Buffer.

A Virtual Buffer is a flat textual representation of the document, which allows the user to arrow around, to read the text and fields that are in the document. Apart from arrowing around, you can also press enter or space on links and buttons to activate them, press enter or space on edit fields to then edit their content, press enter or space on check boxes or radio buttons to select them, and press enter or space on combo boxes to then be able to change their selection.

As you arrow in to a field, the field type (such as link, heading, list etc) is spoken, however this information is not physically in the buffer, which means you can arrow through the text as normal.

Currently NVDA uses Virtual Buffers for reading documents in Mozilla Firefox, Microsoft Internet Explorer, and Adobe Reader.

Note that the virtualBuffers used for Internet Explorer and Adobe Reader are much more basic, and take much more time to load. These older virtualBuffers also cannot deal very well with dynamic content, nore do they support a Links List or some of the virtualBuffer quick keys. For best performance and ease of use, try Mozilla Firefox for browsing the Web.

8.1. Single Letter Navigation

For quicker navigation, NVDA also provides single character keys to jump to certain fields in a virtual buffer.

By themselves they jump to the next field, with the shift key they jump to the previous field.

Keys supported by both old and new virtualBuffers:

Keys not supported by the older virtualBuffers:

8.2. Forms and Virtual Buffer Pass-Through Mode

Sometimes you may wish to interact with form fields with out the virtual buffer keys getting in the way. Virtual Buffer Pass-Through mode is created for this problem, and can be toggled on and off with NVDA+space.

Generally though, when pressing on a form field it will automatically be turned on, and when loading a new page it will be turned off.

8.3. The Links List

To access a list of links for the current virtualBuffer, press NVDA+f7. From the dialog that appears, you can select the link you are interested in, and then either move to it or activate it using the buttons provided.

9. Configuring NVDA

9.1. General Settings

The General settings dialog box is found in the Preferences menu. It contains the following options:

Language

A combo box which allows you to select the language that NVDA's user interface and messages should be shown in. There are many languages, however the last choice in the list is called "Windows". This choice tells NVDA to use the language that Windows is currently set to (in the Regional and Language Options in Control Panel). Please note that NVDA must be restarted when changing the language, NVDA will ask you if you wish to restart if you do change the selection and press OK.

Save Configuration on Exit

A check box that when checked tells NVDA to automatically save the current configuration when you exit NVDA.

Warn befor exiting NVDA

A checkbox that allows you to state whether or not NVDA should ask if you are sure when you want to exit NVDA.

Log level

A combo box that allows you to choose how much NVDA wil log as its running. Generally users should not need to touch this as not too much is logged. However if you are wanting to provide information in a bug report etc, then it may be an idea to set it to a higher level.

9.2. Synthesizer Selection

The Synthesizer dialog, which is found under "Synthesizers..." on the Preferences menu, allows you to select which Synthesizer NVDA should use to speak with.

The dialog contains a simple combo box, which lists all the available synthesizers. Choose the synthesizer you want using the arrow keys, and then press ok. If there is an error loading the synthesizer, a message box will alert you to the fact, and keep the old synthesizer loaded.

The current list of synthesizers NVDA supports is: eSpeak, SAPI4, SAPI5, Audiologic, Display, and Silence.

The eSpeak synthesizer is built directly in to NVDA, and does not depend on any other special drivers or SAPI runtime to be installed. NVDA starts using eSpeak by default. This synthesizer should work on any system that NVDA works on, so it will definitely work when running NVDA off a USB thumb drive or CD, on anyone else's system.

NVDA currently has two SAPI4 drivers. People report different results with both drivers, so please try them both and use the one which works best for you.

The Display synthesizer is useful for sighted developers who wish to read what NVDA is speaking, as they test NVDA with their applications.

The Silence synthesizer driver is not that useful, unless you want to not have any speech at all while running NVDA.

Please note that no matter how many different SAPI4 or SAPI5 voices (or engines) you have installed on your system, only the actual SAPI4 and SAPI5 synthesizers will show up in the Synthesizers dialog. To actually select one of the engines (voices), select either SAPI4 or SAPI5, and then in the Voice settings dialog, you can choose the voice you want.

9.3. Voice Settings

The Voice Settings dialog, found in the Preferences menu, contains options that let you change the sound of the speech. You can also configure many of the options from anywhere by pressing NVDA+Control along with one of the arrow keys. The left and right arrow keys move through the various options, the up and down arrows increase or decrease that option respectively.

This dialog box contains the following options:

Voice

A combo box, listing all the voices of the current synthesizer. You can use the arrow keys to listen to all the various choices.

Variant

A combo box that lets you select the Variant the synthesizer should speak with. Currently only eSpeak supports this setting. ESpeak's Variant's are rather like voices, as they provide slightly different attributes to the eSpeak voice.

Rate

A slider which goes from 0 to 100, (0 being the slowest speed and 100 being the fastest).

Pitch

A slider which goes from 0 to 100, (0 being the lowest pitch and 100 being the highest).

Volume

A slider which goes from 0 to 100, (0 being the lowest volume and 100 being the highest).

Inflection

A slider that lets you choose how much inflection (rise and fall in pitch) the synthesizer should use to speak with.

Speak All Punctuation

A check box, that when checked tells NVDA to speak all punctuation symbols as words (very useful for proof reading). When unchecked, NVDA leaves the punctuation unchanged, so the synthesizer will still read sentences with the right inflection, however the symbols won't be spoken aloud.

Say "Cap" for Capitals

A check box, that when checked tells NVDA to say the word "cap" before any capital letter, when arrowing over it or speaking it when its being typed. Usually, NVDA raises the pitch slightly for any capital letter, but some synthesizers may not support this well, so perhaps this option may be of use.

Beep for capitals

If this checkbox is checked, NVDA will make a small beep each time it is speaking a capitalized character by itself. Like the 'say cap for capitals' checkbox, this is useful for Synthesizers that can't change their pitch for capital letters.

9.4. Keyboard settings

This dialog box is found in the Preferences menu, under "Keyboard settings...". It contains the following options:

Keyboard layout

This combo box lets you choose what type of keyboard layout NVDA should use. Currently the two that come with NVDA are Desktop and Laptop..

Use capslock as an NVDA modifier key

If this checkbox is checked, capslock can be used as an NVDA modifier key.

Use extended insert as an NVDA modifier key

If this checkbox is checked, the extended insert key (usually found above the arrow keys, near home and end) can be used as an NVDA modifier key.

Use numpad insert as an NVDA modifier key

If this checkbox is checked, the insert key on the number pad can be used as an NVDA modifier key.

Speak Typed Characters

A check box that when checked means that NVDA will announce all characters you type on the keyboard. You can also configure this option from anywhere by pressing NVDA+2.

Speak Typed Words

A check box that when checked means that NVDA will announced all words you type on the keyboard. You can also configure this option from anywhere by pressing NVDA+3.

Speak Command Keys

A check box that when checked means that NVDA will announce all non-character keys you type on the keyboard. This includes key combinations such as control plus another letter. You can also configure this option from anywhere by pressing NVDA+4.

9.5. Mouse Settings

The Mouse Settings dialog is found on the Preferences Menu, under "Mouse settings...". It contains the following options:

Report Mouse Shape Changes

A checkbox, that when checked means that NVDA will announce the shape of the mouse pointer each time it changes. The mouse pointer in Windows changes shape to convey certain information such as when something is editable, or when something is loading etc.

Report text Under Mouse

A check box that when checked means that NVDA will announce the text currently under the mouse pointer, as you move it around the screen. This allows you to find things on the screen, by physically moving the mouse, rather than trying to find them through object navigation.

Report role when mouse enters object

If this checkbox is set, NVDA will announce the role (type) of object as the mouse moves in side it.

Play audo coordinates when mouse moves

Checking this checkbox makes NVDA play beeps as the mouse moves, so that the user can work out where the mouse is in regards to the dimentions of the screen.

Brightness controls audio coordinates volume

If the 'play audio coordinates when mouse moves' checkbox is checked, then checking this checkbox means that the volume of the audio coordinates beeps is controled by how bright the screen is under the mouse. This may cause some performence issues on Windows Vista, so it is unchecked by default.

9.6. Object Presentation Settings

Found on the Preferences menu under "Object Presentation..." this dialog box contains the following options:

Report Tool Tips

A check box that when checked tells NVDA to announce tool tips as they appear. Many Windows and controls show a small message (or tool tip) when you move the mouse pointer over them, or sometimes when you move the focus to them.

Report Help Balloons

This check box when checked tells NVDA to announce help balloons as they appear. Help Balloons are like tool tips, but are usually larger in size, and are associated with system events such as a network cable being unplugged, or perhaps to alert you about Windows security issues.

Report Object Shortcut Keys

When this check box is checked, NVDA will include the shortcut key that is associated with a certain object or control when it is announced. For example the File menu on a menu bar may have a shortcut key of alt+f.

Report Object descriptions

Uncheck this checkbox if you feel you don't need to hear the description announced along with objects.

Say Object State First

When this check box is checked, NVDA will announce the state of an object before any other information. For example a button with a name of "play" and a state of "pressed" will be announced as "pressed play button" rather than "play button pressed". This is sometimes useful if you are tabbing around a lot of objects of the same type, but you are only really interested to see whether they are "pressed", or "checked" etc.

Beep on Progress Bar Updates

A progress bar is a control which looks a bit like a ruler. As a task is slowly being completed, more of the bar gets highlighted. It also shows a percentage value, to numerically tell you how far along it is. Progress bars are shown for things like loading a web page, checking your email, or processing a sound file etc. If this check box is checked, NVDA will use beeps to let you know how far along a progress bar is as it moves. This is sometimes a lot nicer than hearing lots of numbers.

9.7. Virtual Buffer Settings

The Virtual Buffer settings dialog can be found on the Preferences menu, under "Virtual Buffers...". Note that a lot of the settings in this dialog may only affect the older virtualBuffers (used for Internet Explorer and Adobe Reader). In future releases of NVDA this problem should be resolved.

The dialog contains the following options:

Maximum Number of Characters on One Line

This field sets the maximum length of a line of a virtual buffer (in characters). Its not guaranteed that all lines will end up being this length or under, but most should.

Maximum Lines Per Page

Although virtual buffers don't really have pages, this field sets the amount of lines you will move by when pressing page up or page down while in a virtual buffer.

Report Virtual Presentation on Focus Changes

This check box when checked tells NVDA to announce the text and presentation information in the virtual buffer for a control, as it gets focus, rather than simply asking Windows for the control information. For example, tabbing to a link called "cats" will say "link cats" rather than "cats link" because in virtual buffers when arrowing around, the type is always said before the text. It may be desirable in certain cases then to not have this option enabled since this means the control will be announced in a some what better order. However, for some web browsers, you may get more accurate information announced when this is enabled.

Update the Content Dynamically

When this check box is checked, Virtual buffers have the ability to be updated as the page changes, due to such things as java script. Currently NVDA only supports dynamic updating for Mozilla Firefox, but hopefully Internet Explorer will also be supported with this feature in future releases.

Specific Field Announcement Settings

The other eleven or so check boxes in this dialog box allow you to configure what type of information is announced when arrowing around virtual buffers. For example, report links, will say the word "link" before any text that is a link when it is checked.

You can configure links, headings, graphics, lists, list items, tables, forms, form fields, block quotes, frames and paragraphs.

9.8. Document Formatting Settings

This dialog box is found in the Preferences menu, under "Document Formatting...". All the check boxes in this dialog are for configuring what type of formatting you wish to hear automatically as you move the cursor around documents such as in Wordpad or Microsoft Word. For example, if you check the report font name check box, each time you arrow on to text with a different font, the name of the font will be announced.

You can configure font names, font size, font attributes, text alignment, text style, tables, page numbers, and line numbers.