# Low Vision or Blindness

From low vision to blindness, the range of visual limitations is broad. Symptoms of low vision include dimness, haziness, extreme far-/near-sightedness, color blindness, and tunnel vision, among others. People with these disabilities are concerned with being able to see text or images on a computer screen and being able to perform tasks that require eye-hand coordination, such as moving a computer mouse. Text size and color can make a big difference in legibility for people with low vision.

The technologies that can assist those with low vision or blindness are:

- Desktop Appearance Enhancement - users can configure the desktop to be easy to read; for example, by increasing text size and using high-contrast themes.

- Screen Magnifier - this is like a magnifying glass. People using them are able to control what area of the computer screen they want enlarged, and can move the magnifier to view different areas of the screen. They are also known as screen enlargers or large print programs.

- Screen Reader - this makes on-screen information available as synthesized speech and/or a refreshable braille display. They generally only translate text-based information. Graphics and other non-textual objects can be translated if there is alternative text describing the item. They are also known as blind access utilities or screen reviewers.

## Desktop Appearance Enhancement

This chapter describes the methods you can use to change the appearance of the GNOME Desktop in order to enhance the accessibility of the desktop for users with visual impairments.

### Customization Options

There are several ways to customize the appearance of the GNOME Desktop to suit your specific needs:

Themes

  Themes are the most effective way to change the appearance of the desktop in a consistent manner. See for more information about themes and how to use them to achieve the type of desktop environment that you require.

Desktop and Application-Specific Configuration Settings

  You can customize different components of the desktop to achieve the display settings that you require. You can configure the desktop and applications in addition to using themes or as an alternative to themes. See for more information.

The following table summarizes the changes that you can make to the GNOME Desktop and where you can make the changes. This guide does not provide detailed instructions about how to customize the desktop. For detailed instructions about how to use the customization tools that the desktop provides, refer to the Help for each tool or to the User Guide.

#### Quick Reference to Customizing the Appearance of the Desktop

To change the... | Use...
--- | ---
Overall appearance of the desktop using high-contrast colors, low-contrast colors, or large print. | The Theme section of the Appearance preference tool.
Appearance of the desktop background only. | The Desktop Background section of the Appearance preference tool; also the file manager Backgrounds and Emblems menu item.
Appearance of the mouse pointer. | The Theme section of the Appearance preference tool; use the Pointers tab of the Customize option.
Font displayed on the desktop background and in all desktop applications. | The Font section of the Appearance preference tool.
Default font settings of the Text Editor, Terminal or Help application. | Normally these applications use the default application font that is specified in the Font section of the Appearance preference tool, but these font settings can also be overridden in the Preferences dialog for the application.

### Using Themes to Customize the Desktop

This section describes how to use themes to customize the appearance of the GNOME Desktop.

#### Introduction to Themes

A theme is a group of coordinated settings that specifies how a desktop component or a group of desktop components appears. You can use themes to modify and control the appearance of the desktop in a consistent manner. When you apply a theme, the system modifies many desktop components simultaneously to achieve the desired effect. For example, if you apply a theme that increases the font size across the desktop, the theme also modifies the size of panels and icons on the desktop for optimum compatibility with the font size. Some themes have suggested font settings that may optionally be auto-set; in addition, most colors within a theme can be customized.

A theme contains settings that affect different parts of the desktop:

Controls

  The controls setting for a theme determines the visual appearance of all windows, applications, panels, and panel applications. The controls setting also determines the visual appearance of the GNOME-compliant interface items that appear on windows, applications, panels, and panel applications such as menus, icons, and buttons. Some of the control options that are available in the desktop are designed for special accessibility needs.

Window Border

  The window frame setting determines the appearance of the border around windows only.

Icon

  The icon setting determines the appearance of icons on panels and on the desktop background.

#### Choosing Themes

To choose a theme, perform the following steps:

1. Choose System Preferences Appearance . The themes are listed under the Theme tab.

2. Click on a theme in the list box to choose a new theme. The system automatically applies the theme to the desktop, and may also prompt whether to apply a suggested font for the theme.

   There are several themes available that suit different accessibility needs, as described in the following table:

   ##### Themes Designed for Accessibility Requirements

   Theme Name | Description
   --- | ---
   High Contrast | Provides dark text on a light background using high-contrast colors.
   High Contrast Inverse | Provides light text on a dark background using high-contrast colors.
   Large Print | This theme suggests an increased font size of 18pt. The background and foreground colors are the same as those specified by the Default desktop theme. To apply the suggested font, click on the Apply Font button.
   High Contrast Large Print | This theme suggests an increased font size of 18pt using dark text on a light background. To apply the suggested font, click on the Apply Font button.
   High Contrast Large Print Inverse | This theme suggests an increased font size of 18pt using light text on a dark background. To apply the suggested font, click on the Apply Font button.

In some GNOME distributions there are also prebuilt low-contrast/low-contrast-large-print themes to complement the high-contrast theme set.

To view the controls, window frame, and icon settings that are associated with a theme, select a theme in the Appearance preference tool, then click on the Theme tab. The Customize option contains a tabbed section for each setting category. Each tabbed section lists the options that are available and the current setting for the theme is highlighted.

#### Modifying the Controls Setting for a Theme

To modify the controls setting that is associated with a theme, perform the following steps:

1. Within the Theme tab, select the theme that you want to modify.

2. Click on the Customize button. The Customize Theme dialog is displayed.

3. Click on the Controls tab to display the controls options that are available.

4. Select the controls option that you want to associate with the current theme from the list box, then click Close. The following table lists the controls options that are suitable for accessibility needs:

##### Controls Options Designed for Accessibility Requirements

Control Option | Description
--- | ---
HighContrast | Provides dark text on a light background using high-contrast colors.
HighContrastInverse | Provides light text on a dark background using high-contrast colors.
LargePrint | Increases the size of controls to accommodate larger fonts. To increase the font size, you must use the Font preference tool. The background and foreground colors are the same as those specified by the Default desktop theme.
HighContrastLargePrint | Provides dark text on a light background using high-contrast colors. Increases the size of controls to accommodate larger fonts. To increase the font size, you must use the Font preference tool.
HighContrastLargePrintInverse | Provides light text on a dark background using high-contrast colors. Increases the size of controls to accommodate larger fonts. To increase the font size, you must use the Font preference tool.

#### Modifying the Window Border Setting for a Theme

To modify the window border setting that is associated with a theme, perform the following steps:

1. In the Appearance preference tool, choose the Theme tab and the theme you want to modify.

2. Click on the Customize button. The Customize Theme dialog is displayed.

3. Click on the Window Border tab to display the window frame options that are available.

4. Select the window frame option that you want to associate with the current theme from the list box, then click Close. The Atlanta option is designed for accessibility.

#### Modifying the Icon Setting for a Theme

To modify the icon setting that is associated with a theme, perform the following steps:

1. In the Appearance preference tool, choose the Theme tab and select the theme that you want to modify.

2. Click on the Customize button. The Customize Theme dialog is displayed.

3. Click on the Icons tab to display the icon options that are available.

4. Select the icon option that you want to associate with the theme from the list box, then click Close. The following table lists the icon options that are suitable for accessibility needs:

##### Icon Options Designed for Accessibility Requirements

Icon Option | Description
--- | ---
HighContrast | Provides dark-on-light icons using high-contrast colors.
HighContrastInverse | Provides light-on-dark icons using high-contrast colors.

#### Creating Your Own Themes

For information about how to create your own themes, see the System Administration Guide.

### Customizing Specific Components of the Desktop

This section describes how to customize specific components of the GNOME Desktop individually.

#### Customizing the Desktop Background

The themes do not affect the desktop background. To set the desktop background, choose System Preferences Appearance and select a background from the Background tab. If no background is chosen, the first entry listed here may be used.

#### Customizing Desktop Background Objects

The size of the icons that are displayed on the desktop background is controlled by the File Management preference tool. To change the size of the icons, perform the following steps:

1. From the File Manager window, choose the Edit Preferences menu item.

2. Select the Views tabbed section.

3. In the Icon View Defaults group, select the zoom level that you require in the Default Zoom Level drop-down list.

#### Customizing Fonts

This section describes how to customize the font settings for the desktop and frequently-used applications.

If you have difficulty with the default font type and font size that is used on the desktop and desktop background, you can customize the font settings to suit your needs.

You can specify individual font settings for the following desktop components and applications:

- Entire desktop (excluding the desktop background)

- Desktop background only

- Terminal

- Text Editor

- Help

- Web Browser

##### Customizing Desktop Fonts

The Appearance preference tool allows you to specify the default fonts for the desktop.

To start the Appearance preference tool, choose System Preferences Appearance. The Fonts tab contains the following options:

Application Font

  Click on this button to select a default font to use for the text that is displayed on the desktop, including the text displayed on the windows and dialogs associated with GNOME-compliant applications and panel applications.

  If you use a predefined theme and you click on the Apply Font button, the font that is associated with the theme overrides the font from the Appearance preference tool.

Document Font

  Click on this button to select a font to use for displaying documents.

Desktop Font

  Click on this button to select a font to use for the text that is displayed on the desktop background only.

Window Title Font

  Click on this button to select a font to use for the text that is displayed in the titlebar area of windows.

Fixed Width Font

  Click on this button to select a font to use for editing documents.

Font Rendering

  To specify how to render fonts on the desktop, select one of the following options:

  - Monochrome

  - Best Shapes

  - Best Contrast

  - Subpixel Smoothing

If you use large fonts, you may need to change the size of panes in some applications, such as the file manager and Help browser.

For more information about the Appearance preference tool and fonts, see the User Guide.

##### Customizing Application Fonts

By default, GNOME applications use the default font specified in the Appearance preference tool. Some applications allow this default font to be customized. These applications are:

- Help Browser

- Text Editor

- Terminal

- Web Browser

### Meeting Specific Accessibility Needs

The following sections summarize the steps you need to take to improve the accessibility of the desktop in a particular area.

#### Achieving a High- or Low-Contrast Desktop

To achieve a high- or low-contrast desktop, perform the following steps:

1. Use the Appearance preference tool to select the high-contrast or low-contrast desktop theme that you require from the Theme tab.

2. Use the Background tab to customize your desktop background as follows:

   - Set the Desktop Wallpaper to No Wallpaper.

   - Set the Desktop Colors to Solid Color.

   - Select a background color that suits your needs.

3. In the Terminal application, ensure that the Use colors from system theme option is selected in the Colors tabbed section of the Editing Profile dialog.

4. In the gedit (Text Editor) application, ensure that the Use default theme colors option is selected in the Fonts & Colors tabbed section of the Preferences dialog.

#### Achieving a Large Print Desktop

To achieve a large-print desktop, perform the following steps:

1. Use the Appearance preference tool to select the Large Print theme.

2. Click on the Apply Font button to increase the size of the font that is used on the desktop and on window frames.

3. Use the Desktop Font option in the Font tab to increase the font that is displayed on desktop background objects.

4. Increase the font size that is used to display the contents of the Terminal application window.

5. If the Use default theme font option is selected in the gedit (Text Editor) Preferences dialog, gedit uses the font size that is specified in the large-print theme that you selected. However, if the Use default theme font option is not selected, increase the font size that is used to display the contents of the gedit text editor window. See the gedit manual for more information.

6. If you use applications that use panes, such as the file manager and help browser, you may need to change the size of panes to accommodate the large print. See the online help for the appropriate application for more information.

## Orca: Screen Reader and Magnifier

The Orca Screen Reader and Magnifier application enables users with limited or no vision to use the GNOME Desktop and associated applications. Orca provides the following functionality:

- Screen Reader

  The screen reader enables non-visual access to standard applications in the GNOME Desktop by using speech and braille output.

- Magnifier

  The magnifier provides automated focus tracking and full-screen magnification to aid low-vision users.

The following sections provide information about Orca and how to use it.

### Introduction to Orca

#### What is Orca?

Orca is a flexible, extensible, and powerful assistive technology for people with visual impairments. Using various combinations of speech synthesis, braille and magnification, Orca helps provide access to applications and toolkits that support the AT-SPI (e.g., the GNOME Desktop). Orca is also free open source software.

#### Why the name Orca?

One of the first DOS screen readers was Flipper, made by Omnichron Corporation in Berkeley, CA. It was named Flipper in part because the blind wife of the programmer envisioned computers as being programmed by flipping switches (an accurate image of a bygone era). Then came another DOS screen reader, this one from Henter-Joyce in Florida - "Jobs Access With Speech" (or JAWS). And so on....

Although no obvious connection exists between blindness and creatures from the sea, there is certainly a naming tradition for screen-reader software. Hence Orca, which is a lot tougher-sounding than Nemo, Ariel, Willy, or Mr. Limpet.

#### What's the schedule?

Orca is part of the GNOME platform and Orca's releases are coupled with the releases of the GNOME platform.

#### How do I request a new feature?

Bugs and feature/enhancement requests (RFEs) should be reported to the GNOME Bug Tracking System . Patches are always welcome, and instructions for creating patches can be found in the GNOME Introduction to Subversion (SVN) .

#### Where is the discussion list?

You can get in touch with developers and other users by sending an e-mail to the Orca mailing list (Archives).

#### Is braille supported?

Yes! Braille is supported via BrlTTY and it is tightly integrated with Orca. BrlTTY offers support for nearly every refreshable braille display known to man.

#### Is contracted braille supported?

Yes, Orca fully supports contracted braille output.

#### What voices are available?

Orca provides interfaces to both `gnome-speech` and `emacspeak` speech services. As such, the available voices for Orca are only restricted by the speech engines supported by the available speech services. For free speech engines, you typically have a choice of the eSpeak, Festival, and FreeTTS speech engines. For commercial engines, you have a choice of additional engines such as Fonix DECtalk, Loquendo, Eloquence, Cepstral and IBMTTS, with others on the way. Periodically check the `gnome-speech` package for more progress in this area.

#### What languages are supported?

The GNOME translation teams are composed of many passionate volunteers from around the world. These teams do a great job and keep an up-to-date status report. See the Orca translation status page for the large number of languages into which Orca has been translated.

Note: support for a language also depends on the speech synthesis engine also supporting the same language.

#### How well does magnification work?

Orca currently uses the `gnome-mag` magnification service. `gnome-mag` has incorporated support for smoother full-screen magnification, which relies upon newer extensions in the X Window System server. These extensions do not always function well on all platforms, so smooth full-screen magnification may not always work.

### Enabling Orca

For a text-only guided setup, open a Run dialog with AltF2 or MetaR and use the command `orca --text-setup` Enter.

The first time Orca is launched you will be asked a few questions:

First you will be presented with a list of languages to choose from; there are currently about 45 languages supported. Most of this list will scroll off the screen, so you may have to use the terminal's scrollbar to view earlier parts of the list. Type in the number of your language choice (e.g., 7 for American English) and press Enter. You do not need to wait for the entire list to be spoken, and Orca attempts to make your default language the first choice (choice 1).

You are next asked to set Echo By Word. This option instructs Orca to speak words as you finish typing them. Type y or n and press Enter.

The next item is Key Echo. This option will speak all keys as they are pressed. Type y or n and press Enter.

Now select your desired keyboard layout; generally, you will want to choose the layout that matches your keyboard type - 1 for Desktop or 2 for Laptop. This choice will determine what key will act as the Orca modifier key. The Desktop layout uses Insert while the Laptop layout uses Caps Lock. A system, host, shift or modifier key is one which is used in conjunction with other keys, enabling keyboard access to most program functions.

Next, specify if you require braille output. This functionality assumes a BrlTTY-compatible device is available. Type y or n and press Enter. Note that you can usually just enter y here; Orca will recover gracefully and function even if it cannot find BrlTTY.

Lastly, indicate whether you want an on-screen braille output monitor. This is mostly for developers who need to verify BrlTTY output, but may also be useful in other situations, such as visually diagnosing or verifying braille output. Type y or n and press Enter.

That's it! Orca is now ready for use. If accessibility was not yet enabled, Orca does so now and asks you to logout and back in for the services to start. Type y and press Enter to restart your login session.

After completing the first-time Orca settings, use AltF2 or MetaR to bring up the Run dialog, type in `orca` and press Enter. Accessibility functions should now be active. Orca's Configuration GUI () also has an option to let you indicate that Orca should be started automatically when you log in.

If you plan to use the Magnifier portion of Orca in full screen mode, nonfirm the Xserver "Composite" extension is enabled: use AltF2 or MetaR to bring up the Run dialog, type in `xdpyinfo` and press Enter. Look for the string "Composite" in the output.

### Using Orca

#### Initial Setup

When you run Orca for the first time, it will automatically enter setup mode. If you want to run setup at some later point, you can pass the `--setup` option to Orca the next time you run it. Furthermore, while Orca is running, you can press InsertSpace to bring up Orca's Configuration GUI (). Finally, Orca provides a text setup utility that you can start by passing the `--text-setup` option to Orca. All of these options will create a `~/.orca/user-settings.py` file that holds your preferences and will also enable the accessibility infrastructure. You need to log out and log back in for the new settings to take effect.

#### How do I run Orca?

Run Orca by typing `orca` in a terminal session window. You can do so from a virtual console window if you do not yet have access to the GUI. With the GUI installed you can also press Alt F2 or Meta R to bring up the Run dialog and then type `orca` as the command (followed by any optional parameters). Then, press Enter. Orca will automatically enter text setup mode if you run it from a virtual console window or your GUI environment is not yet set up for accessibility.

#### Quitting Orca

To quit Orca, press Insert Q (or CapsLock Q in laptop layout mode). A confirmation dialog will appear. Select Quit to close Orca. If the system seems unresponsive, you can try a few things:

- Run `orca --quit` from a terminal window, such as a virtual console; press Ctrl AltF1 (on most Linux platforms) to get to a virtual console, enter your commands, and then use Alt F7 to get back to the desktop. This will kill the Orca process and reclaim system resources. You can then rerun Orca using the previously outlined methods.

- Press Ctrl AltBackspace to end your login session and get back to the graphical login prompt (not implemented in all Linux distributions).

### Orca Configuration GUI

The Orca Configuration GUI allows you to customize the behavior and features of Orca, such as speech, braille, and magnification. For example, you can select which speech synthesis engine you want to use, whether braille is enabled or not, and which magnification preferences you want. You can select which general keyboard layout you want (desktop or laptop) and you can also examine and modify the existing keyboard layout with fine-grained control. To bring up the Orca Configuration GUI, press Orca_ModifierSpace, where Orca_Modifier is Insert when you use the Desktop Keyboard Layout () and CapsLock when you use the Laptop Keyboard Layout (). If you want to change settings for a single application, press CtrlOrca_ModifierSpace while the application has focus.

The Orca Configuration GUI is a dialog containing several tabbed pages, each of which is described in the following sections.

#### General Page

Orca GUI Configuration - General Page

The General page allows you to customize general aspects of Orca. These include the following:

##### Keyboard Layout

The keyboard layout section allows you to specify if you will be working on a laptop (small) or desktop (large, with a numeric keypad) keyboard. You select which layout you want by selecting one of the following options:

Desktop - if selected, the Desktop Keyboard Layout () will be used.

Laptop - if selected, the Laptop Keyboard Layout () will be used.

##### Show Orca main window

Orca GUI Configuration - Main window

The Orca main window provides you with a graphical way to display the Orca Configuration GUI (also accessible with Orca_ModifierSpace, where Orca_Modifier is Insert when you use the Desktop Keyboard Layout () and Caps_Lock when you use the Laptop Keyboard Layout ()). The main window also provides a Quit option, also available with Orca_ModifierQ). Many users do not like the Orca main window because it shows up in the window manager's tab order when you press AltTab to switch windows. By deselecting the "Show Orca main window" button, you can tell Orca to not show the Orca main window.

##### Quit Orca without Confirmation

Normally, when you press Orca_ModifierQ to quit Orca or press the Quit button in the Orca main window, Orca will pop up a confirmation dialog asking you if you want to quit. Unchecking this option prevents the confirmation window from appearing.

##### Disable gksu keyboard grab

When running commands from the launch menu, many distributions use an application known as gksu to authorize the user to run these commands; gksu is the GUI that asks you for your password. When it runs, gksu enables what is known as a "keyboard grab," which is a feature to prevent keyboard actions from going to any other application on the desktop, including Orca. The result of a keyboard grab is that Orca will not receive any keyboard events, preventing Orca from functioning normally.

By selecting the "Disable gksu keyboard grab" button, you will turn off the keyboard grab behavior, allowing Orca to function normally with system administration applications.

The keyboard grab is a security attempt by gksu to prevent nefarious applications from "sniffing" the keyboard and grabbing secret information. Please be advised that disabling the gksu keyboard grab feature can expose you to such nefarious behavior. If you do not feel comfortable with this, you can always use the root account for system administration purposes. To do so, you need to enable the root account for login, and then logout and log back in as root whenever you want to perform a system administration command.

##### Present tooltips

When checked, this option will tell Orca to present information about tooltips when they appear as the result of mouse hovering. Specific actions to force tooltips to appear, such as pressing CtrlF1 when an object has focus, will always result in tooltips being presented, regardless of this setting.

##### Speak object under mouse

When checked, this option will tell Orca to present information about the object under the mouse when you move it around the screen. Note that this can cause Firefox and Thunderbird versions 2.x and earlier to crash; this is not a problem with Firefox and Thunderbird versions 3.x and later.

##### Start Orca when you login

When checked, this option will tell the system to automatically launch Orca when you log in.

#### Speech Page

Orca GUI Configuration - Speech Page

The speech page allows you to customize how Orca uses speech synthesis.

##### Enable speech

The first control of note on the speech page is the "enable speech" check box. This check box toggles whether or not Orca will make use of a speech synthesizer. This option, along with the ability to enable braille and enable magnifier support, allow Orca to be tailored to meet the needs of a wide variety of users.

##### Speech System and Speech Synthesizer

The next two controls deal with selecting the speech system and synthesizer. Orca provides support for a growing number of speech systems. At the time of this writing, these include GNOME-speech, Emacspeak, and an experimental backend for Speech Dispatcher. Depending upon how your machine is configured, you may have all or none of these options. Typically, you will have just GNOME-speech.

First, determine which speech system you would like to use - GNOME-speech works best at this time. After making your selection, tab to the speech synthesizer combo box and choose from the list of available synthesizers.

##### Voice Settings

If your synthesizer supports it, Orca can utilize multiple voices in order to identify special cases within an application, such as hyperlinks or upper case text. The voice settings and person combo boxes can be adjusted to customize these settings to your liking. For example, assume you were using Fonix DECtalk and wanted the Betty voice to denote upper case. To accomplish this, you could do the following:

1. Tab to the voice settings combo box, and down arrow until the upper case voice is selected.

2. Tab to the person combo box, and down arrow to choose the Betty voice.

The next three sliders in the tab order allow adjustment of the synthesizer's rate, pitch and volume, respectively.

##### Punctuation Level

The punctuation level radio button group is used to adjust the amount of punctuation spoken by the synthesizer. The available levels are None, Some, Most and All.

##### Verbosity

The verbosity setting determines the amount of information that will be spoken in certain situations. For example, if it is set to verbose, the synthesizer will speak shortcut keys for items in pull down menus. When it is set to brief, these shortcut keys are not announced.

##### Table Row Speech

The table row speech option determines the way in which Orca will read items within tables. The available settings are "speak current row" or "speak current cell". The ability to adjust this behavior can be useful in many situations. For example, consider the process of browsing email messages in Evolution. In this instance it may be preferable to set table speech to "speak current row" so that while arrowing through the list of messages all relevant info, such as the sender, subject, and whether the message has attachments, is read automatically. While the current row setting is active, it is still possible to read individual cells by using the left and right arrows.

You can quickly toggle this behavior by pressing Orca_ModifierF11.

##### Speak Blank Lines

Some users desire to hear "blank" when navigating to a blank line in a document. Other users do not. If the "speak blank lines" check box is selected, Orca will speak blank lines.

##### Speak multicase strings as words

When working with code, one often comes across a "word" consisting of several words with alternating case, such as "MultiCaseString." Speech synthesizers do not always pronounce such multicase strings correctly. Checking the Speak multicase strings as words checkbox will cause Orca to break a word like "MultiCaseString" into separate words ("Multi," "Case," and "String") prior to passing it along to the speech synthesizer.

##### Speak tutorial messages

When moving from component to component in an interface, this option will provide spoken tutorial messages for how to work with the component.

##### Speak object mnemonics

This option will cause Orca to announce the mnemonic associated with the object with focus (such as "Alt O" for the OK button).

##### Break speech into chunks between pauses

Depending on the enabled speech settings, Orca may have quite a bit to say about a particular object such as its name, its role, its state, its mnemonic, its tutorial message, and so on. Checking the Break speech into chunks between pauses checkbox will cause Orca to insert brief pauses in between each of these pieces of information.

##### Speak child position

Checking the Speak child position checkbox will cause Orca to announce the position of the focused item in menus and lists (e.g. "9 of 16").

##### Speak Indentation and Justification

When working with code or editing other documents it is often desirable to be aware of justification and indentation. Selecting the Speak indentation and justification check box will cause Orca to provide this information.

##### Speak Progress Bar Updates

If this setting is enabled, Orca will periodically announce the status of progress bars. How often the announcement is made is determined by the value chosen in the update interval spin button. Note that this spin button is only available if the Speak progress bar updates checkbox has been checked.

##### Restrict progress bar updates to

This setting controls which progress bars should be spoken, assuming the Speak progress bar updates checkbox has been checked. The choices are All, Application, and Window. Choosing All will result in Orca speaking updates for all progress bars, regardless of where the progress bars are located. Choosing Application will result in Orca speaking updates from progress bars in the active application, even if they are not in the active window. Choosing Window will result in Orca only speaking updates for progress bars in the active window. The default value is Application.

##### Say All By

This combo box allows you to specify whether the "say all" functionality of Orca speaks by sentence or line. See the Desktop Keyboard Layout () and Laptop Keyboard Layout () for how to invoke the "say all" functionality).

#### Braille Page

Orca GUI Configuration - Braille Page

The braille page allows you to customize various aspects about the use of braille.

Orca does not automatically start BrlTTY for you; typically you need to do this yourself, usually at boot time.

##### Enable Braille Support

The first control on the braille page is the "Enable braille support" check box. This check box toggles whether or not Orca will make use of a braille display. This option, along with the ability to enable braille and enable magnifier support, allow Orca to be tailored to meet the needs of a wide variety of users. By default, this check box is enabled. If BrlTTY is not running, Orca will recover gracefully and will not communicate with the braille display. If you configure BrlTTY later on, you need to restart Orca in order for it to use braille.

##### Enable Braille Monitor

Orca's braille monitor provides an on-screen representation of what takes place on the braille display. This feature is mostly for demonstration purposes, but is also useful for Orca developers who do not have access to a braille display.

##### Abbreviated Role Names

The "Abbreviated role names" check box determines the manner in which role names are displayed and can be used to help conserve real estate on the braille display. The "Abbreviated role names" option can be better understood if we consider the following example. Let us assume that a slider had focus, and that the abbreviated role names box was not checked. In this case, the word "slider" would be shown on the display, to reflect the fact that the current control was indeed a slider. If the abbreviated role names box were checked, the word "slider" would be abbreviated to "sldr".

##### Disable end of line symbol

When checked, this feature tells Orca to not present the "$l" string at the end of a line.

##### Contracted Braille

Orca supports contracted braille via the liblouis project. Refer to the Orca WIKI, where you can find additional information about setting up liblouis with Orca.

##### Verbosity

The verbosity radio button group determines the amount of information that will be brailled in certain situations. For example, if it is set to verbose, keyboard shortcut and role name information is displayed. This information is not displayed in brief mode.

##### Selection Indicator

When you select text, Orca will "underline" that text on your braille display with Dots 7 and 8. If you would prefer, you can change the indicator to only be Dot 7, only be Dot 8, or not be present at all.

##### Hyperlink Indicator

When you encounter a hyperlink, Orca will "underline" that text on your braille display with Dots 7 and 8. If you would prefer, you can change the indicator to only be Dot 7, only be Dot 8, or not be present at all.

#### Key Echo Page

Orca GUI Configuration - Key Echo Page

The key echo page allows you to specify the behavior of Orca when pressing keys on the page and whether words are spoken as you complete them.

##### Enable Key Echo

The first control on the key echo page is the "Enable key echo" check box. When this box is selected, seven additional check boxes become available. These are: "Enable alphanumeric and punctuation keys", "Enable modifier keys", "Enable locking keys", "Enable function keys", "Enable action keys", "Enable navigation keys", and "Enable non-spacing diacritical keys".

The alphanumeric and function key groups are relatively self explanatory.

Modifier keys are those such as Shift, Ctrl, and Alt.

Locking keys include Caps Lock, Scroll Lock and Num Lock.

The action keys group consists of keys that perform some logical action, such as Backspace, Return and Tab.

The navigation keys group include the four arrow keys as well as any key combination in which the Orca Modifier key is being held down. The latter is designed to prevent Orca from echoing flat review commands.

Non-spacing diacritical keys are those "dead keys" used to generate accented letters.

##### Enable Echo by Character

The next toggle on the key echo page is the "Enable echo by character" check box, used to echo the character you just typed. While echo by character seems quite similar to the key echo of alphanumeric and punctuation keys, there are important differences, especially with respect to accented letters and other symbols for which there is no dedicated key. Key echo causes Orca to announce what you just pressed; character echo causes it to announce what was inserted. The "Echo by character" control is always available, regardless of whether any of the key echo options are checked.

##### Enable Echo by Word

The next toggle on the key echo page is the "Enable echo by word" check box, used to echo the word you just typed. The "Echo by word" control is always available, regardless of whether any of the key echo options are checked.

##### Enable Echo by Sentence

The last toggle on the key echo page is the "Enable echo by sentence" check box, used to echo the sentence you just typed. The echo by sentence control is always available, regardless of whether any of the key echo options are checked.

In summary, the key echo scheme can offer a great deal of flexibility. For example, one user might choose to enable all key echo options, while another might prefer to use word echo, but only have locking keys announced.

#### Magnifier Page

Orca GUI Configuration - Magnifier Page

The magnifier page allows you to enable/disable magnification and specify how magnification is performed.

##### Enable Magnifier

The first control on the magnifier page is the "Enable magnifier" check box. This check box toggles whether or not Orca will provide magnification. This option, along with the ability to enable speech and enable braille support, allow Orca to be tailored to meet the needs of a wide variety of users.

##### Zoomer Settings

Two zoomer GUI controls determine magnification characteristics:

- "Scale factor", which sets magnification power from 1.0x to 16.0x (fractional values are supported).

- "Position", which sets the location and size of the magnifier window: "Full Screen", "Left Half", "Right Half", "Top Half", "Bottom Half", and "Custom". The default position is "Full Screen". Choosing "Custom" causes four spin buttons to become available: "Top", "Left", "Right", and "Bottom". These spin buttons allow you to define the location of each edge of the zoom window. Units are in pixels.

##### Border Settings

These options are not available in "Full Screen" mode.

###### Enable border

This option determines if a window border is visible for the magnifier.

###### Border size

This value determines the size of the border in pixels.

##### Cursor Settings

These controls can be used to customize the size and color of the magnifier's cursor.

###### Enable cursor

If this check box is enabled then a cursor is visible and the size and color options become available.

###### Custom size

Enable this check box if you would like to make the mouse pointer larger than it normally is. The cursor size can be changed from the default value of 32 pixels.

###### Custom color

If the cursor is enabled, a custom color can also be applied.

##### Cross-hair Settings

This set of controls can be used to customize the magnifier's optional area-targeting cursor.

###### Enable cross-hair

If checked, you can additionally configure the clipping behavior, size and color of the cross-hair.

###### Enable cross-hair clip

If enabled, the cross-hair will be "clipped" (removed) in the area immediately surrounding the mouse pointer.

###### Cross-hair size

This control sets the thickness of the cross-hair in pixels.

###### Cross-hair color

This control allows a custom color to be used for the cross-hair.

##### Color Settings

This allows you to do some rough color adjustments of the magnified region.

###### Invert colors

Creates a reverse or negative-image effect.

###### Brightness

Ranges from -1 to 1 (-1 is black/no brightness; 1 is white/total brightness; 0 is "normal"/unchanged).

###### Contrast

Ranges from -1 to 1 (-1 is grey/no contrast; 1 is maximum contrast; 0 is "normal"/unchanged).

##### Tracking and Alignment Settings

These options control the tracking of the mouse cursor.

###### Mouse pointer

Choose from the following options:

###### Centered

Keeps the mouse pointer at the center of the screen whenever possible. This is the default.

###### Proportional

Positions the mouse pointer in the zoom window relative to its actual, unmagnified position. For instance, if the mouse pointer is 25% away from the left edge of the desktop, Orca positions the magnified mouse pointer 25% from the left edge of the zoom window.

###### Push

Moves the zoomer window the least amount necessary to keep the mouse pointer on the screen.

###### None

Moving the mouse pointer has no impact on what the zoomer window displays.

###### Pointer follows zoomer

This option is enabled by default. If the mouse pointer is not on the screen when you initially move the mouse, it will be moved into the zoomer so that you can continue to see what you were working on. If your preferred mouse tracking mode is centered, the pointer will be moved to the center; otherwise it will be moved to the item with focus.

###### Control and menu item

These options control additional behavior of the magnifier.

###### Centered

When navigating via keyboard, keep the focused dialog box control or menu item at the center of the screen whenever possible.

###### Push

When navigating via keyboard, move the zoomer window the least amount necessary to display the focused dialog box control or menu item. This is the default.

###### None

Using the keyboard to navigate among dialog box controls and menu items will have no impact on what the zoomer window displays.

###### Pointer follows focus

If this option is enabled, the mouse pointer will follow you as you arrow through menu items and move among controls in dialog boxes. This option is disabled by default.

###### Text cursor

These options control how the text cursor behaves.

###### Centered

As the text cursor moves, keep it at the center of the screen whenever possible.

###### Push

As the text cursor moves, move the zoomer window the least amount necessary to display it. This is the default.

###### None

Moving the text cursor will have no impact on what the zoomer window displays.

###### Edge margin

The edge margin is how close the caret should be allowed to get to the edge of the screen before it's time to "push" the zoomer window. The margin can range from 0 to 50%, with 50% being the equivalent of choosing centering. The default value is 0.

This option is only available if "Push" is your text cursor tracking mode.

##### Advanced Settings

If you press the Advanced Settings button located near the bottom of the Magnifier page, the following dialog will appear:

Orca GUI Configuration - Magnifier - Advanced Settings

###### Smoothing

Bilinear or none.

###### Brightness

Red, Green, Blue: Individual controls for choosing customized brightness levels. Choosing different brightness levels for each color allows you to create the color scheme that works best for you.

###### Contrast

Red, Green, Blue: Individual controls for choosing customized contrast levels. While not as significant as changes to brightness, choosing different contrast levels for each color helps you to create the color scheme that works best for you.

###### Color Filtering

Allows you to pick one of the colorblind filters available through libcolorblind.

In order to take advantage of this feature you will need to install libcolorblind and then rebuild gnome-mag.

###### Multi-Monitor Settings - Source Display

X Window System DISPLAY of what should be magnified. Written in the form ":0.x" where x is the number of the screen whose contents should be magnified.

###### Multi-Monitor Settings - Target Display

X Window System DISPLAY of where to put the zoomer window. Written in the form ":0.y" where y is the number of the screen where the zoomer window should appear.

#### Key Bindings Page

Orca GUI Configuration - Key Bindings Page

The key bindings page allows you to examine and modify the key bindings for Orca.

##### Orca Modifier Key(s)

The first control on the key bindings page allows you to examine which key (or keys) acts as the "Orca modifier." The Orca modifier is the key that you press and hold in conjunction with other keys to give commands to Orca. For desktop keyboards, the Orca modifier defaults to Insert. For laptop keyboards, the Orca modifier defaults to the Caps Lock key. See the Desktop Keyboard Layout () and Laptop Keyboard Layout () sections for the default values.

You cannot modify the Orca modifier key(s) using the Configuration GUI at this time.

##### Key Bindings Table

The key bindings table provides a list of Orca operations and the keys that are bound to them.

The "Function" column header is a description of the Orca operation to be performed.

The "Key Binding" header is the primary way to invoke the function from the keyboard. Note that the function description may include the word "Orca". This indicates that the Orca modifier key should be held down along with the other keys.

The "Alternate" header provides an alternate mechanism for invoking the function from the keyboard.

To modify either the "Key Binding" or the "Alternate" bindings, arrow to the cell and press Return. Then, press a key combination and press Return to confirm the new combination. When you do so, the new keystroke will be saved and the check box in the last column (the "Modified" column) will indicate that the key binding has been modified.

To undo a modified keybinding, merely arrow to the modified column, uncheck the checkbox, and press the "Apply" button AltA.

Beneath the list of Orca keybindings, you will find a group of "unbound" commands:

Orca GUI Configuration - Key Bindings Page showing the 'unbound' group of commands

These are commands which we feel will be very useful for some users, but not needed by most users. Rather than "use up" a keystroke for such commands, we have left them unassigned. You can assign a keystroke to any of these unbound commands by following the procedure outlined above. In addition, you can unbind any bound command in a similar fashion: press Return to edit the keybinding, and when prompted for the new keybinding, press Delete or Backspace. You will be told that the key binding has been removed. Press Return to confirm.

#### Pronunciation Page

Orca GUI Configuration - Pronunciation Page

Sometimes your speech synthesizer just doesn't say the right thing for a given string. You might prefer to hear "laughing out loud" rather than "LOL." Or there may be a name or a technical term which the synthesizer mispronounces. The pronunciation page is where you can add, edit, and delete Orca's pronunciation dictionary entries. Because the pronunciation page is also part of the application-specific settings dialog that's started when you give a particular application focus and type Orca_ModifierCtrlSpace, you can customize your entries on an as-needed basis for each application you use.

##### Add a new dictionary entry

1. Press the New Entry button (AltN).

2. Type the text of the new entry and press Return to finish editing the actual string.

3. Move to the Replacement String column and press Return to begin editing.

4. Type the text that you would like to have spoken instead and press Return to finish editing the replacement string.

##### Edit an existing dictionary entry

1. Move to the cell you wish to edit and press Return to begin editing.

2. Make your changes and then press Return to finish editing.

##### Delete an existing dictionary entry

1. Move to the entry you wish to delete.

2. Press the Delete button or AltD.

#### Text Attributes Page

Orca GUI Configuration - Text Attributes Page

Orca will speak known text attribute information about an object when you press InsertF (desktop layout) or Caps_LockF (laptop layout). Because the number of text attributes is large, and not everyone cares about every attribute, the "Text Attributes" tab of the configuration GUI allows you to customize which text attributes Orca will present.

On this tab is a text attribute list, where each row consists of four columns:

- The name of the text attribute.

- A checkbox which the user can set to indicate whether this text attribute should be spoken or not.

- A checkbox which the user can set to indicate whether this text attribute should be "underlined" on the braille display.

- An editable "Present unless" string value. By default, not all text attributes will have this set. If present, what it means (assuming the user wants this text attribute presented) is that the value of the attribute will only be presented if it is not this value.

  For example, by default the "underline" text attribute has a value of "none." If the user has this attribute checked and the user types Orca_ModifierF and the text in question is not underlined, then this attribute is not spoken. If you always want this attribute to be spoken irrespective of whether the text is underlined, then the attribute should be checked and the "Present unless" value cleared.

- There is also a Reset button (AltR) which will set the list values back to their initial state when the dialog was first displayed.

When you initially display the text attribute pane, all your checked attributes are put at the top of the list. They are given in the order that they will be spoken and brailled.

If you decide to check others or adjust the order, there are four buttons to help you do this:

- Move to top (AltT) - moves the selected attribute to the top of the list.

- Move up one (AltU) - moves the selected attribute up one row.

- Move down one (AltD) - moves the selected attribute down one row.

- Move to bottom (AltB) - moves the selected attribute to the bottom of the list.

Beneath these push buttons is the Braille Indicator group of radio buttons. Here you can select the cell or cells to be used to indicate text which has at least one of the specified attributes. Your choices are:

- None (the default)

- Dot 7

- Dot 8

- Dots 7 and 8

Text attributes can also be set on an individual application basis. The text attribute pane is also part of the application-specific settings dialog that's started when you give a particular application focus and type Orca_ModifierCtrlSpace.

### Orca Keyboard Commands

You can get a complete list of available keyboard commands by visiting the Key Bindings page of the Orca Configuration GUI (). To bring up the Orca Configuration GUI, press Orca_ModifierSpace, where `Orca_Modifier` is the Insert key for the desktop layout and the Caps_Lock key for the laptop layout. Note that you can also enter Orca's "learn mode" while running Orca by pressing Orca_ModifierH. When in learn mode, Orca will intercept all keyboard and braille input events and tell you what the effect would be. To exit learn mode, press the Escape key.

Orca provides additional commands for some applications, such as Firefox. To get the list of additional commands for an application, press CtrlOrca_ModifierSpace when that application has focus. This will bring up the Orca Configuration GUI in the "application-specific" state, and the additional commands will appear in the Key Bindings page.

The GNOME Desktop itself also has built in keyboard commands to control the desktop and its applications.

WARNING: the MouseKeys functionality of AccessX can interfere with the Orca modifier key (see bug 548169), resulting in odd behavior. In particular, MouseKeys uses the KP_Insert key to emulate a mouse button press. When enabled, MouseKeys can conflict with KP_Insert as the Orca modifier, resulting in what appears to be a stuck Orca modifier key. As an alternative, you can use the laptop key bindings, which avoids the keypad for Orca commands. If you accidentally enabled MouseKeys, you can disable it via the gnome-keyboard-properties application.

#### Desktop Layout

Following is a list of common Orca keyboard commands for desktop keyboards arranged by category:

##### Flat review commands

- Numpad-7 - move the flat review cursor to the previous line and read it.

- Numpad-8 - read the current line.

- Numpad-9 - move the flat review cursor to the next line and read it.

- Numpad-4 - move the flat review cursor to the previous word and read it.

- Numpad-5 - read the current word.

- Numpad-6 - move the flat review cursor to the next word and read it.

- Numpad-1 - move the flat review cursor to the previous character and read it.

- Numpad-2 - read the current character.

- Numpad-3 - move the flat review cursor to the next character and read it.

- Numpad-slash - perform a left mouse click at the location of the flat review cursor.

- Numpad-star - perform a right mouse click at the location of the flat review cursor.

- Numpad-minus - toggle between flat review and focus tracking mode.

The above commands apply when working with objects as well as when working with text. For example, if the flat review cursor were positioned on a menu bar, pressing the "read current line" command would speak the names of all visible menus. Similarly, pressing the "read next word" command would speak the object to the right of the flat review cursor on the same line, or move flat review to the next line if no more objects were found.

##### Bookmark commands

- AltInsert[1-6] - assign a bookmark to a numbered slot. If a bookmark already exists in the slot it will be replaced with the new one.

- Insert[1-6] - go to the position pointed to by the bookmark bound to this numbered slot.

- AltShift[1-6] - "Where am I" information for this bookmark relative to the current pointer location.

- InsertB and InsertShiftB - move between the given bookmarks for the given application or page.

- AltInsertB - save the defined bookmarks for the current application or page.

##### Miscellaneous functions

- NumpadPlus - "say all" command; reads from the current position of the caret to the end of the document.

- NumpadEnter - "Where am I" command; speaks information such as the title of the current application window, as well as the name of the control that currently has focus.

- InsertH - enter into Orca's "learn mode"; press Escape to exit.

- InsertF - speak font and attribute information for the current character.

- InsertSpace - Launch the Orca Configuration dialog.

- InsertCtrlSpace - reload user settings and reinitialize services as necessary. Also launches the Orca Configuration dialog for the current application.

- InsertS - toggle speech on and off.

- InsertF11 - toggle the reading of tables, either by single cell or whole row.

- InsertQ - quit Orca.

##### Commands for debugging

- CtrlAltInsertHome - report information on the currently active script.

In order for the next three commands to be of use, Orca needs to be started from a virtual console or via gnome-terminal. Output is sent to the console only (i.e., it is not sent to speech or braille).

- CtrlAltInsertEnd - print a debug listing of all known applications to the console where Orca is running.

- CtrlAltInsertPage_Up - print debug information about the ancestry of the object with focus.

- CtrlAltInsertPage_Down - print debug information about the hierarchy of the application with focus.

#### Laptop Layout

Following is a list of common Orca keyboard commands for laptop keyboards arranged by category:

##### Flat review commands

- Caps_LockU - move the flat review cursor to the previous line and read it. Double-click to move flat review to the top of the current window.

- Caps_LockI - read the current line. Double-click to read the current line along with formatting and capitalization details.

- Caps_LockO - move the flat review cursor to the next line and read it. Double- click to move flat review to the bottom of the current window.

- Caps_LockJ - move the flat review cursor to the previous word and read it. Double-click to move flat review to the word above the current word.

- Caps_LockK - read the current word. Double-click to spell the word. Triple-click to hear the word spelled phonetically.

- Caps_LockL - move the flat review cursor to the next word and read it. Double- click to move flat review to the word below the current word.

- Caps_LockM - move the flat review cursor to the previous character and read it. Double-click to move flat review to the end of the current line.

- Caps_LockComma - read the current character. Double-click to pronounce the character phonetically if it is a letter.

- Caps_LockPeriod - move the flat review cursor to the next character and read it.

- Caps_Lock7 - perform a left mouse click at the location of the flat review cursor.

- Caps_Lock8 - perform a right mouse click at the location of the flat review cursor.

- Caps_Lockp - toggle between flat review and focus tracking mode.

The above commands apply when working with objects as well as when working with text. For example, if the flat review cursor were positioned on a menu bar, pressing the "read current line" command would speak the names of all visible menus. Similarly, pressing the "read next word" command would speak the object to the right of the flat review cursor on the same line, or move flat review to the next line if no more objects were found.

##### Bookmark commands

- AltCaps_Lock[1-6] - add a bookmark to the numbered slot. If a bookmark already exists for the slot it will be replaced with the new one.

- Caps_Lock[1-6] - go to the position pointed to by the bookmark bound to this numbered slot.

- AltShift[1-6] - "Where am I" information for this bookmark relative to the current pointer location.

- Caps_LockBand Caps_LockShiftB - move between the given bookmarks for the given application or page.

- AltCaps_LockB - save the defined bookmarks for the current application or page.

##### Miscellaneous functions

- Caps_LockSemicolon - "Say all" command; reads from the current position of the caret to the end of the document.

- Caps_LockEnter - "Where am I" command; speaks information such as the title of the current application window, as well as the name of the control that currently has focus.

- Caps_LockH - enter learn mode (press Escape to exit).

- Caps_LockF - speak font and attribute information for the current character.

- Caps_LockSpace - launch the Orca Configuration dialog.

- Caps_LockCtrlSpace - reload user settings and reinitialize services as necessary; also launches the Orca Configuration dialog for the current application.

- Caps_LockS - toggle speech on and off.

- Caps_LockF11 - toggle the reading of tables, either by single cell or whole row.

- Caps_LockQ - quit Orca.

##### Commands for debugging

- Caps_LockAltCtrlHome - report information on the currently active script.

In order for the next three commands to be of use, Orca needs to be started from a virtual console or via gnome-terminal. Output is sent to the console only (i.e., it is not sent to speech or braille).

- Caps_LockAltCtrlEnd - prints a debug listing of all known applications to the console where Orca is running.

- Caps_LockAltCtrlPage_Up - prints debug information about the ancestry of the object with focus.

- Caps_LockAltCtrlPage_Down - prints debug information about the object hierarchy of the application with focus.

### Application-Specific Information

#### Accessible Applications

Orca is designed to work with applications and toolkits that support the Assistive Technology Service Provider Interface (AT-SPI). This includes the GNOME Desktop and its bundled applications: OpenOffice, Firefox, and the Java platform. Some applications work better than others, however, and the Orca community continually works to provide superior access to more and more applications.

#### Making Application-Specific Settings

To customize the settings for a particular application, you will first need to run that application. Make sure the application has focus, then press Orca_Modifier CtrlSpace (by default, this will be InsertCtrl Space for the Desktop keyboard layout).

This brings up a tabbed dialog window very similar to the Orca configuration dialog, but with the following differences:

1. There is no initial General pane.

2. The Speech System and Speech Synthesizer combo boxes on the Speech pane will be grayed out (made inactive).

3. Any existing application-specific key bindings will appear at the top of the list on the Key Bindings pane.

4. There may be a new application-specific settings pane at the end of the set of tabbed panes. Note that pressing the End key from the tab list will get you directly to the right-most tab.

Adjust your application-specific settings in the same way you set your general Orca preferences. For example, you may have Key Echo disabled generally in Orca but would like to specifically have it enabled for the gcalctool (GNOME Calculator) application. Here's where you could easily set that.

When you have your application settings customized the way you want, press the OK button. These settings will be written to your `~/.orca/app-settings` directory in a file called `<APPNAME>.py`, where `<APPNAME>` is the name of the application.

These files are automatically written by Orca. The contents of the file will be overwritten each time you change your application settings for that application.

If you want to have some extra application-specific settings or code that you don't want to lose, then you should put it in a file called `~/.orca/app-settings/<APPNAME>-customizations.py`. This file will be automatically read when the settings for the `<APPNAME>` application are loaded.

Note that this is an advanced feature that we don't expect many people to use. It's just there if you really want it.

There is currently one known bug (some people would call it a feature) that we are trying to track down and fix:

If you adjust one or more application-specific key bindings, the new values will not take effect until you've pressed the OK button. The work-around is to either restart Orca, or Alt-Tab away to some other application and then Alt-Tab back to the one that you've just changed the key bindings for.

### Braille

Orca uses BrlTTY for braille support. On Linux systems, BrlTTY is used to access the text mode console content. On a typical braille-enabled installation of Linux, BrlTTY is already running and providing access to the text consoles. When Orca starts, it connects to BrlTTY. If you switch from a text console to your X Windows session, your braille display will automatically follow and display the content that Orca is presenting to you.

Orca attempts to work with various releases of BrlTTY. Orca currently works best with BrlTTY v3.8 or better and also works well with BrlTTY v3.7.2. The remainder of this document provides information related to using Orca with BrlTTY 3.8.

Below are descriptions of the necessary tasks to install/setup BrlTTY in Ubuntu and Solaris. For both, you need to first obtain brltty-3.8.tar.gz from the BrlTTY site.

#### BrlTTY 3.8 on Ubuntu

First, configure your build environment to build BrlTTY. Much of this setup is done for you automatically in the Ubuntu distribution with products such as G++ already present. In addition, you must also install tcl, Pyrex, and the Python developer environment. To do this, execute the following commands as `root`:

    apt-get build-dep brltty
    apt-get install tcl8.4 python-pyrex python-dev

Then, when you build BrlTTY, avoid configuring the package with --prefix=/usr. Use the standard procedure instead, executing the following commands as `root`:

    gunzip -c brltty-3.8.tar.gz | tar xvf -
    cd brltty-3.8
    ./autogen
    ./configure
    make
    make install

Run BrlTTY as `root`:

    /bin/brltty -bauto -d/dev/ttyUSB0

If you want, you can remove the existing `/sbin/brltty` and replace it with the `/bin/brltty`, either by copying the `/bin/brltty` to `/sbin/brltty` or just by making a symbolic link. Do so at your own risk.

### Troubleshooting

#### My desktop has stopped responding. What do I do?

Press AltF2 or MetaR to open the Run dialog and restart Orca by running a new instance: type `orca` and press Enter. This will force any existing Orca processes to exit and will then restart Orca. This sometimes has the effect of unhanging the desktop (which is usually due to an ill-behaved application).

If you cannot get to a terminal window, try pressing Ctrl AltBackspace : shut down the X Window System server. This should return you to the login screen.