<!DOCTYPE REFENTRY PUBLIC "-//Sun Microsystems//DTD DocBook V3.0-Based SolBook Subset V2.0//EN" [
<!--ArborText, Inc., 1988-1999, v.4002-->
<!ENTITY cmd "orca">
<!ENTITY % commonents SYSTEM "smancommon.ent">
%commonents;
<!ENTITY % booktitles SYSTEM "booktitles.ent">
%booktitles;
<!ENTITY suncopy "Copyright (c) 2004,2007 Sun Microsystems, Inc. All Rights Reserved.">
]>
<?Pub UDT _bookmark _target>
<?Pub Inc>
<refentry id="orca-1">
<!-- %Z%%M% %I% %E% SMI; -->
<refmeta><refentrytitle>orca</refentrytitle><manvolnum>1</manvolnum>
<refmiscinfo class="date">12 Nov 2007</refmiscinfo>
<refmiscinfo class="sectdesc">&man1;</refmiscinfo>
<refmiscinfo class="software">&release;</refmiscinfo>
<refmiscinfo class="arch">generic</refmiscinfo>
<refmiscinfo class="copyright">&suncopy;</refmiscinfo>
</refmeta>
<indexterm><primary>orca</primary></indexterm>
<indexterm><primary></primary></indexterm>

<refnamediv id="orca-1-name"><refname>orca</refname><refpurpose>a screen reader / magnifier</refpurpose></refnamediv>

<refsynopsisdiv id="orca-1-synp"><title>&synp-tt;</title>
<cmdsynopsis><command>&cmd;</command>

<arg><option>-gui-setup</option></arg>
<arg><option>-text-setup</option></arg>
<arg><option>-no-setup</option></arg>
<arg><option>-disable=<replaceable>options</replaceable></arg>
<arg><option>-enable=<replaceable>options</replaceable></arg>
<arg><option>-user-prefs-dir</option></arg>
<arg><option>-help</option></arg>
<arg><option>-version</option></arg>
<arg><option>-quit</option></arg>

</cmdsynopsis></refsynopsisdiv>

<refsect1 id="orca-1-desc"><title>&desc-tt;</title>

<para>&cmd; is a screen reader for people with visual impairments,
and provides alternative access to the desktop by making use
of speech synthesis, braille, and magnification  support on
the platform.</para>
<para>In addition, &cmd; only provides access to
applications/toolkits that support the assistive technology
service provide interface (AT-SPI), which include GTK,
Mozilla, Firefox, Evolution, OpenOffice, StarOffice,
Java/Swing, etc.</para>

</refsect1>
<refsect1 id="orca-1-opts"><title>&opts-tt;</title>
<para>The following options are supported:</para>
<variablelist termlength="wholeline">

<varlistentry>
<term><option>s</option>, <option>-gui-setup</option>, <option>-setup</option></term>
<listitem><para>
When starting &cmd; bring up the GUI configuration dialog.
</para></listitem></varlistentry>

<varlistentry>
<term><option>t</option>, <option>-text-setup</option></term>
<listitem><para>
When starting &cmd; initiate the text-based configuration.
</para></listitem></varlistentry>

<varlistentry>
<term><option>n</option>, <option>-no-setup</option></term>
<listitem><para>
When starting &cmd; force the application to be started without
configuration, even though it might have needed it. This is useful
when starting &cmd; via something like gdm.
</para></listitem></varlistentry>

<varlistentry>
<term><option>u</option>, <option>-user-prefs-dir=<replaceable>directory</replaceable></option></term>
<listitem><para>
When starting &cmd;, specify the <replaceable>directory</replaceable> as
an alternate directory for the user preferences.
</para></listitem></varlistentry>

<varlistentry>
<term><option>e</option>, <option>-enable=<replaceable>speech|braille-monitor|magnifier|main-window</replaceable></option></term>
<listitem><para>
When starting &cmd;, force the enabling of the supplied options.
</para></listitem></varlistentry>

<varlistentry>
<term><option>d</option>, <option>-disable=<replaceable>speech|braille-monitor|magnifier|main-window</replaceable></option></term>
<listitem><para>
When starting &cmd;, force the disabling of the supplied options.
</para></listitem></varlistentry>

<varlistentry>
<term><option>?</option>, <option>h</option>, <option>-help</option></term>
<listitem><para>
Show the help message of this release of the &cmd; program.
</para></listitem></varlistentry>

<varlistentry>
<term><option>v</option>, <option>-version</option></term>
<listitem><para>
Return the &cmd; version number.
</para></listitem></varlistentry>

<varlistentry>
<term><option>q</option>, <option>-quit</option></term>
<listitem><para>
Quit &cmd;.
</para></listitem></varlistentry>

</variablelist></refsect1>

<refsect1 id="orca-1-exde"><title>&exde-tt;</title>
<para>
In order for the "Accessible GNOME Desktop" to be accessible
to users who are blind or have low vision, users will need to 
employ an assistive technology (AT) that exposes the graphical
desktop information encoded in the GNOME Accessibility Framework.
</para>
<para>
Customers with blind employees/students need to have the ability
to adapt and customize their assistive technology solutions - both 
to improve the efficiency of their blind users (to help make up for
disadvantages inherent in not being able to "see" the entire screen
immediately at a glace), and also to "work around" poorly designed 
and not particularly accessible applications that their blind users
need to use.
</para>
<para>
&cmd; is an extensible assistive technology that provides end-user
access to applications and toolkits that support the GNOME 
Accessibility Framework. It has been designed with direct continual
feedback from its disability user community.
</para>
<para>
&cmd; uses a "scripting" approach to easily allow  customization
per application and provides the ability for each user to further 
customize their AT environment based on their own preferences.
The "scripting" approach of &cmd; provides a much more adaptable
and compelling assistive technology solution than existing AT 
for the JDS desktop.
</para>
<para>
Functionally &cmd; does 4 major things:
</para>
<orderedlist>

<listitem><para>
Present information to the user via speech synthesis
(text-to-speech), or refreshable braille (hardware connected
to serial or USB port), or a magnified image on the user's display.
</para></listitem>

<listitem><para>
Acquire information from the applications and desktop
graphical display via the GNOME Accessibility Framework.
</para></listitem>

<listitem><para>
Track events occurring in the applications and desktop
graphical display via the GNOME Accessibility Framework.
</para></listitem>

<listitem><para>
Intercept and optionally consume user input events from
the system keyboard and the buttons on a refreshable braille
display. Based on the input, &cmd; will either pass the
event on to the application for normal processing, execute
&cmd;-specific commands (such as reading the next line in the
display or panning the braille display), or perform operations 
on application objects (such as clicking buttons or modifying text areas).
</para></listitem>
</orderedlist>

<para>
&cmd; will also:
</para>
<itemizedlist>

<listitem><para>
be a collection of building blocks that comprise screen reading and 
magnification technology, including use of text-to-speech, braille
input/output, magnification logic, screen reading logic, keyboard 
and mouse interception modules, and event coalescing.
</para></listitem>

<listitem><para>
be developed with the standard GNOME build environment.
</para></listitem>

<listitem><para>
support multiple braille displays.
</para></listitem>

<listitem><para>
support the gnome-speech module for text-to-speech.
</para></listitem>

<listitem><para>
intercept keyboard & mouse events through the GNOME
Accessibility Framework and other supported X mechanisms.
</para></listitem>

<listitem><para>
support the gnome-mag module to provide end-user magnification
of the screen between 2 and 16 times magnification in integer increments.
</para></listitem>

<listitem><para>
render its own graphical user interface using GTK+ widgets.
</para></listitem>

<listitem><para>
provide a scripting mechanism, giving it the ability to customize how 
each application on the JDS desktop is handled by &cmd;.
</para></listitem>

<listitem><para>
provide further customization on a per-user basis.
</para></listitem>

</itemizedlist>

<para>&cmd; provides a set of its own keyboard commands. 
Note that you can always enter &cmd;'s "learn mode" while running &cmd; by 
pressing Insert+F1. When in learn mode, &cmd; will intercept all keyboard 
and braille input events and will tell you what the effect of them would 
be. To exit learn mode, press the escape key.
</para>
<itemizedlist>

<listitem>
<para>Commands for adjusting speech parameters</para>
<variablelist termlength="small">

<varlistentry><term><option> Insert-right arrow</option></term>
<listitem><para>increase speech rate</para></listitem>
</varlistentry>

<varlistentry><term><option> Insert-left arrow</option></term>
<listitem><para>decrease speech rate</para></listitem>
</varlistentry>

<varlistentry><term><option> Insert-up arrow</option></term>
<listitem><para>raise the pitch</para></listitem>
</varlistentry>

<varlistentry><term><option> Insert-down arrow</option></term>
<listitem><para>decrease the pitch</para></listitem>
</varlistentry>
</variablelist>
</listitem>

<listitem>
<para>Flat review commands</para>
<variablelist termlength="narrow">

<varlistentry><term><option> Numpad-7</option></term>
<listitem>
<para>move the flat review cursor to the previous line, and read it.</para>
</listitem>
</varlistentry>

<varlistentry><term><option> Numpad-8</option></term>
<listitem>
<para>read the current line.</para>
</listitem>
</varlistentry>

<varlistentry><term><option> Numpad-9</option></term>
<listitem>
<para>move the flat review cursor to the next line, and read it.</para>
</listitem>
</varlistentry>

<varlistentry><term><option> Numpad-4</option></term>
<listitem>
<para>move the flat review cursor to the previous word, and read it.</para>
</listitem>
</varlistentry>

<varlistentry><term><option> Numpad-5</option></term>
<listitem>
<para>read the current word.</para>
</listitem>
</varlistentry>

<varlistentry><term><option> Numpad-6</option></term>
<listitem>
<para>move the flat review cursor to the next word, and read it.</para>
</listitem>
</varlistentry>

<varlistentry><term><option> Numpad-1</option></term>
<listitem>
<para>move the flat review cursor to the previous character, and read it.</para>
</listitem>
</varlistentry>

<varlistentry><term><option> Numpad-2</option></term>
<listitem>
<para>read the current character.</para>
</listitem>
</varlistentry>

<varlistentry><term><option> Numpad-3</option></term>
<listitem>
<para>move the flat review cursor to the next character, and read it.</para>
</listitem>
</varlistentry>

<varlistentry><term><option> Numpad-slash</option></term>
<listitem>
<para>perform a left mouse click at the location of the flat review 
cursor.</para>
</listitem>
</varlistentry>

<varlistentry><term><option> Numpad-star</option></term>
<listitem>
<para>perform a right mouse click at the location of the flat review 
cursor.</para>
</listitem>
</varlistentry>

</variablelist>
</listitem>
</itemizedlist>

<para>
Note: 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 read next word 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.
</para>

<itemizedlist>

<listitem>
<para>Miscellaneous functions</para>
<variablelist termlength="small">

<varlistentry><term><option> Insert-F1</option></term>
<listitem>
<para>enter learn mode (press escape to exit)</para>
</listitem>
</varlistentry>

<varlistentry><term><option> Insert-f</option></term>
<listitem>
<para>speak font and attribute information for the current character.</para>
</listitem>
</varlistentry>

<varlistentry><term><option> Insert-space</option></term>
<listitem>
<para>launch the &cmd; Configuration dialog.</para>
</listitem>
</varlistentry>

<varlistentry><term><option> Insert-Control-space</option></term>
<listitem>
<para>reload user settings and reinitialize services as necessary.</para>
</listitem>
</varlistentry>

<varlistentry><term><option> Insert-s</option></term>
<listitem>
<para>toggle speech on and off</para>
</listitem>
</varlistentry>

<varlistentry><term><option> Insert-F11</option></term>
<listitem>
<para>toggle the reading of tables, either by single cell, or whole row.</para>
</listitem>
</varlistentry>

<varlistentry><term><option>Insert-q</option></term>
<listitem>
<para>quit &cmd;.</para>
</listitem>
</varlistentry>

</variablelist>
</listitem>

<listitem>
<para>Commands for debugging</para>
<variablelist termlength="narrow">

<varlistentry><term><option> Insert-F3</option></term>
<listitem>
<para>report information on the currently active script.</para>
</listitem>
</varlistentry>

<varlistentry><term><option> Insert-F4</option></term>
<listitem>
<para>cycle through &cmd;'s various debug levels.</para>
</listitem>
</varlistentry>

<varlistentry><term><option> Insert-F5</option></term>
<listitem>
<para>prints a debug listing of all known applications to the console 
where &cmd; is running.</para>
</listitem>
</varlistentry>

<varlistentry><term><option> Insert-F7</option></term>
<listitem>
<para>prints debug information about the ancestry of the object with 
focus.</para>
</listitem>
</varlistentry>

<varlistentry><term><option> Insert-F8</option></term>
<listitem>
<para>prints debug information about the application with focus.</para>
</listitem>
</varlistentry>

<para>Note, in order for the last three commands to be of use, &cmd; 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).</para>

</variablelist>
</listitem>

</itemizedlist>

</refsect1>

<refsect1 id="orca-1-exit"><title>&exit-tt;</title>
<para>The following exit values are returned:</para>

<variablelist termlength="xtranarrow">
<varlistentry><term><returnvalue>0</returnvalue></term><listitem><para>
Application exited successfully</para>
</listitem></varlistentry>

<varlistentry><term><returnvalue>1</returnvalue></term><listitem><para>
Application exited with error</para>
</listitem></varlistentry>

<varlistentry><term><returnvalue>2</returnvalue></term><listitem><para>
&cmd; cannot parse its command line options.
</listitem></varlistentry>

</variablelist></refsect1>

<refsect1 id="orca-1-file"><title>&file-tt;</title>
<para>The following files are used by this application:</para>
<variablelist termlength="wide">

<varlistentry><term><filename>/usr/bin/&cmd;</filename></term><listitem><para>
&cmd; executable</para>
</listitem></varlistentry>

<varlistentry><term><filename>~/.orca/user-settings.py</filename></term><listitem><para>
user's personal configuration settings for &cmd;</para>
</listitem></varlistentry>

</variablelist></refsect1>

<refsect1 id="orca-1-attr"><title>&attr-tt;</title>
<para>See <olink targetdocent="REFMAN5" localinfo="attributes-5"><citerefentry>
<refentrytitle>attributes</refentrytitle><manvolnum>5</manvolnum></citerefentry></olink>
for descriptions of the following attributes:</para>
<informaltable frame="all">
<tgroup cols="2" colsep="1" rowsep="1"><colspec colname="COLSPEC0" colwidth="1*">
<colspec colname="COLSPEC1" colwidth="1*">
<thead>
<row><entry align="center" valign="middle">ATTRIBUTE TYPE</entry><entry align="center"
valign="middle">ATTRIBUTE VALUE</entry></row>
</thead>
<tbody>
<row><entry><para>Availability</para></entry><entry><para>gnome/accessibility/orca</para></entry>
</row>
<row><entry colname="COLSPEC0"><para>Interface stability</para></entry><entry
colname="COLSPEC1"><para>Volatile</para></entry></row>
</tbody>
</tgroup>
</informaltable>
</refsect1>

<refsect1 id="orca-1-also"><title>&also-tt;</title>
<para>
<citerefentry><refentrytitle>attributes</refentrytitle><manvolnum>5</manvolnum></citerefentry>
</para>

<para>&cmd; online reference manual.</para>

<para>Latest version of the <citetitle>GNOME Accessibility Guide</citetitle>
for your platform.</para>

<para>Latest version of the <citetitle>GNOME Desktop User Guide</citetitle>
for your platform.</para>
5</manvolnum></citerefentry></para>
</refsect1>

<refsect1 id="orca-1-note"><title>&note-tt;</title>
<para>Written by Rich Burridge, Sun Microsystems Inc., 2006, 2007.</para>
</refsect1>
</refentry>
