PDF version of this manual.

This tutorial explains how to use Orca in general (orca.gnome.org), and more specifically on Emmabuntüs Debian Edition 5 which, from version 1.02, incorporates accessibility features for the visually impaired.

This manual is inspired by this article in English “An Orca screen reader tutorial” by Michael Große : techblog.wikimedia.org/2020/07/02/an-orca-screen-reader-tutorial

Orca configuration

You can open the Orca settings dialog by typing the Alt Super S shortcut on Emmabuntüs or, on other versions of Linux, by typing Alt F2 (the application launch menu) and then entering “orca -s”, followed by the Enter key. The most important parameter is at the top left: Keyboard layout. This toggles between two sets of key combinations, suitable for either narrow notebook keyboards or wider external keyboards with a dedicated numeric keypad. The keys on this keypad will be prefixed “KP”, KP Plus, for example, will refer to the Plus key on the keypad. Note that the numeric lock must be deactivated, which is normally the case on Emmabuntüs when the system is configured in accessibility mode.

Choose what suits you best. By default, the Emmabuntüs accessibility mode will choose the keyboard configuration that seems most appropriate for your hardware. However, you can change this at any time by typing the shortcut Alt Super A to open the accessibility configuration window:

Accessibility settings window
Accessibility settings window

Note: This document will always mention the two key combinations when they differ.

One of the most important keys is the Orca control key, which activates certain meta-commands for Orca, and which is called Orca Key in this manual, or simply Orca in the shortcut manuals.

Desktop: Insert or KP zero

Laptop: Caps Lock

You can reopen the settings window while Orca is running with the Orca Key Spacebar shortcut.

Starting and stopping Orca

When Orca is not running, you can start it by pressing Alt Super O on Emmabuntüs or, on other versions of Linux, by displaying the application launch menu with Alt F2, then typing “orca” and pressing Enter. You can stop it by typing the Orca key F4 shortcut on Emmabuntüs or, on other versions of Linux, by displaying the application launch menu with Alt F2, then typing “killall orca” and pressing Enter .

When Orca is running, it replaces a large number of normal keyboard letters with commands for navigating the document according to its structure, as shown below. You can disable this behavior with the shortcut Orca Key Z.

The fact that Orca talks all the time can be quite annoying. You can silence it with the shortcut Orca Key S, and retype this shortcut to reactivate Orca reading aloud. But beware: Orca’s structural navigation commands, which are affecting many keys on your keyboard, are not disabled by this behavior and may still be active. This can lead to a very confusing behavior, so take care.

Learning mode

To get started with Orca, you may wish to use its learning mode, which announces each key combination you make and the associated Orca commands. In this mode, you can also obtain a shortcut list containing all the Orca commands you can use.

Using the learning mode

To enter learning mode, press the Orca key H shortcut, then press a key or key combination to learn its function. Press the escape key to exit this mode.

Note: For learning mode to work properly, the keypad lock must not be activated.

Get a list of Orca shortcuts

Once you’ve entered learning mode, press F2 if you want the list of shortcuts that apply to Orca in general, or press F3 if you want the list of shortcuts that apply specifically to the application that has the focus.

Press Arrow Up or Arrow Down to examine the contents of the list.

Press the escape key to exit the list.

Reading

Use Left Arrow and Right Arrow to move forward or backward by one character, and Left Arrow Control and Right Arrow Control to move forward or backward by one word. Up Arrow and Down Arrow read the previous or next line. You can use the Tab and Shift Tab keys to move between focusable elements such as links, buttons, text boxes, etc.

Say All

Orca’s Say All command speaks document content from your present location to the end of the document.

Desktop: KP Plus
Laptop: Orca key Semicolon

Where am I

Orca’s “Where am I” function provides context-dependent information about your current location. For example, in a table, the “Where am I” function provides details about the cell you’re in, but in text, it provides the line as well as the text that is selected.

Orca provides the following “Where am I” commands:

Perform the basic “Where am I” operation:
Desktop: KP Enter
Laptop: Orca Key Enter

Perform detailed “Where am I” operation:
Desktop: KP Enter
double clicked
Laptop: Orca
Key Enter double clicked

In addition to the dedicated “Where am I” commands, Orca has two additional linked commands in order to obtain information about your current location:

Read the title bar :
Desktop: Orca
Key KP Enter
Laptop: Orca
Key Slash

Read status bar :
Desktop: Orca
Key KP Enter double clicked
Laptop: Orca
Key Slash double clicked

Structural navigation

Listening to a document from beginning to end is probably not your usual use case. Screen readers offer a variety of commands for navigating the document structure. A full list of these commands is available in the official documentation on structural navigation. Below is a small selection of commands to get you started.

As previously mentioned, these commands can be activated or deactivated using the Orca Z shortcut. By default, they are enabled.

When is it necessary to disable structural navigation?

In web pages, explicitly disabling navigation by structure is generally not necessary, as your interaction with the document is generally limited to reading. There’s no need to ask: is the “H” you’ve just typed a write command or a navigation command?

On the other hand, in editable documents such as those found in LibreOffice, it’s much harder for Orca to interpret correctly what should happen when you press the “H” key. So, before you can use any structural navigation commands in an editable document, you must first activate structural navigation by pressing the Orca Key Z shortcut. When you’ve finished browsing the document and wish to resume editing, press Orca Key Z shortcut again to deactivate structural navigation.

Moving by header

Next and previous headers: H and Shift H

Display a list of headers : Alt Shift H

You can use keys 1 to 6 to move to the next header of the corresponding level, and Shift 1 to Shift 6 to move to the previous header. Alt Shift 1 to Alt Shift 6 gives a list of all headers on that level.

Moving by landmarks

Different areas of a web page have different functions, such as navigation, main content or search. To facilitate navigation, these areas are ideally identified by landmarks.

Next and previous landmark: M and Shift M

Display a list of landmarks: Alt Shift M

Moving by links

Previous and next link: K and Shift K

Display a list of links : Alt Shift K

Moving through lists

Next and previous list : L and Shift L

Display a list of lists : Alt Shift L

Next and previous list item: I and Shift I

Display a list of list items: Alt Shift I

Examples of structural navigation

Structural navigation is well suited to Internet browsing, and here is an example of its use with Firefox on Emmabuntüs.

Start Firefox with the shortcut Super W, then when Firefox is open type the shortcut Control K to position the focus on the browser’s search bar, and then enter the words you want to search for.

To display the list of links in Lilo’s search window, type the structural navigation shortcut Alt Shift K, then move through the list using the up and down arrows. Each time you move, Orca reads the selected link. To go to the link page, simply press Enter.

Internet search with Firefox using structural navigation
Internet search with Firefox using structural navigation

You’re now on the Accessibility page of the Emmabuntüs website. To display the list of headings on this page, press the shortcut Alt Shift H, then move through the drop-down list with the up and down arrows to hear the names of the headings or titles of all the levels on this page, then press Enter to go to this chapter.

Displaying headers of all levels with Firefox using structural navigation
Displaying headers of all levels with Firefox using structural navigation

You can also display the list of headers or titles for one level only. For example, to view the headers for level 1 only, type the shortcut Alt Shift 1, as in the example below.

Displaying only level 1 headers with Firefox using structural navigation
Displaying only level 1 headers with Firefox using structural navigation

Interacting with focus mode

You can follow links by pressing Enter, and push buttons by pressing the Spacebar or Enter.

When navigating through forms, you can use Tab or Shift Tab to move to the next or previous focusable object, whatever its type, or you can use Orca’s structural navigation commands for forms to move to the next or previous form field. To use structural navigation commands to leave a form field, you must be in navigation mode. If you are in focus mode, you can switch to navigation mode by using the Orca Key A shortcut.

Toggling navigation and focus modes

Orca’s navigation and focus modes let you toggle between reading and interacting with web content, such as forms.

Toggle between navigation and focus modes: Orca Key A

Activate permanent focus mode: Orca Key A double clicked

Activate permanent navigation mode: Orca Key A triple clicked

Supported application configuration

Orca supports the following applications: Firefox, LibreOffice, Thunderbird, Pidgin, and a few other applications not included in Emmabuntüs.

When you’re in these applications, navigation modes can be activated by default. To adapt them to your needs, type the shortcut Control Orca Key Spacebar to launch the application-specific settings window, and go to the last tab on the right bearing the application’s name to adjust these options:

Firefox screen reader preferences window
Firefox screen reader preferences window

Below is an extract from Orca’s documentation explaining the different operating modes configured in this tab for the Firefox application:

Page Navigation

The group of navigation controls across the page lets you customize how Orca pronounces, and allows you to interact with text and other types of content such as forms.

Control caret navigation

This checkbox toggles Orca’s cursor navigation. When enabled, Orca takes control of the cursor as you move around the page; when disabled, the browser’s native cursor navigation is active.

Default value: checked

To toggle this setting on the fly without saving it, use the Orca Key F12 shortcut.

Automatic focus mode during caret navigation

If this box is checked, Orca automatically activates focus mode when you use cursor navigation commands to navigate to a form field. For example, pressing the Down Arrow key would take you to the input field, but after that, Orca would switch to focus mode and subsequent presses of the Down Arrow key would be controlled by the web browser and no longer by Orca. Conversely, if this box is unchecked, Orca continues to control what happens when you press Down Arrow again, allowing you to exit this area with the arrow keys and continue reading.

Default: unchecked

To start or stop interaction with a focused form field, use the Orca Key A shortcut to toggle between navigation and focus modes.

Enable structural navigation

This checkbox toggles Orca’s Structural Navigation. Structure-based navigation lets you browse the page from element to element, such as headers, links and form fields.

Default value: checked

To toggle this setting on the fly without saving it, use the Orca Key Z shortcut.

Automatic focus mode during structural navigation

If this box is checked, Orca automatically activates focus mode when you use structural navigation commands to navigate to a form field. For example, pressing E to move to the next entry will move the focus to that point and also activate focus mode so that the next press on E will write an “e” character in the input field. If this box is unchecked, Orca remains in navigation mode and the next press on E will move you to the next input field on the page.

Default value: unchecked

To start or stop interaction with a form field in focus, use the Orca Key A shortcut to toggle between navigation and focus modes.

Automatic focus mode during native navigation

If this box is checked, Orca automatically activates focus mode when you use the browser’s native navigation commands to access a form field. For example, pressing Tab to move to the next entry will move the focus to that point and also activate focus mode so that the next press on E will write an “e” character in the input field. If this box is unchecked, Orca remains in navigation mode and the next press on E will move you to the next input field on the page.

Default value: checked

To start or stop interaction with a form field in focus, use the Orca Key A shortcut to toggle between navigation and focus modes.

Enable layout mode for content

If this box is checked, Orca’s cursor navigation respects the layout of the content on the screen and presents the complete line, including any links or form fields on that line. If this box is unchecked, Orca treats objects such as links and form fields as if they appeared on separate lines, both for presentation and navigation.

Default value: checked

Table Navigation

Table options let you customize Orca’s behavior when browsing a table in applications that support Structural Navigation.

Find Options

The Find Option control group allows you to customize Orca’s presentation of search results within an application.

Speak results during find

If this box is checked, Orca speaks the line containing the item you’re looking for.

Default value: checked

Only speak changed lines during find

If this box is checked, Orca won’t speak a matching line if it’s the same as the previous matching line. This option is designed to prevent “chatter” if a line contains several instances of the string you’re looking for.

Default value: unchecked

Minimum length of matched text

This setting knob is used to specify the number of characters that must match your find before Orca will speak the corresponding lines. This option is also designed to prevent “chatter”, as there are very many matches when you start typing the string you’re looking for.

Default value: 4

Conclusion

You should now be able to move around the document in a basic way and have the screen reader tell you its contents. Other useful commands can be found in the Orca Command Reference and in the Orca Preferences documentation. Further information on high-level concepts can be found in the Orca documentation.